@finedesign/cli 0.2.0 → 0.3.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": "cd0e18216c5c827cadb64a71a947a643394d15ac",
5
+ "sourceRevision": "39a9955314410af35f1b6096076dcbdf2cc45e9a",
6
6
  "sourceDirty": false,
7
- "contentHash": "c64aec628caee0ee14cbaeb68bbe7e0d3bea0362590d94ac8f3da983f054a348",
8
- "catalogSha256": "8dd9a17aafcb42a07667d9ee50e9398a7f229fa1855efbf86a466baf819ee661",
7
+ "contentHash": "30d2e3ea566ad4fd5eed2f53b6cae59de2030db49d2f90eb81b20b3d85e66e4e",
8
+ "catalogSha256": "67db385543fa667b5a81b70f4fe35a01a7d8b2bdc8c7a559ced808babd88c7b0",
9
9
  "skillFiles": {
10
- "references/component-guide.md": "fd18509f7b304bb3073736c514c1b43d41284499a5616cb4fcba95bf849094cb",
10
+ "references/component-guide.md": "612948840948e65f250998231eaa16fc41e8e27b9c03b19af32571422ca8185a",
11
11
  "references/docs-slug-map.md": "440ce5cf137fd22eabfcc5b51c3f55b85174aa643773ef0cedd5df542e77bbc2",
12
12
  "references/imports-and-setup.md": "5bd9024770a77ddeb0f4dce94ebd103f327c2513b52f165e371da9c4dbdcd98f",
13
13
  "references/theme-and-dark-mode.md": "2eccae4930ea993e7088eee03a4b4a0f1c839033079db5f21f8c60e0fe8168d1",
14
- "SKILL.md": "035ce9e23c7c1f78addcb08198f02b3b482c61d8a9b3b939e8b5f12511058750"
14
+ "SKILL.md": "b8ef63aa9aef7cf6cb8f83556b6c09760fc4707f0466d25eb1fac8f2fed6b2a9"
15
15
  }
16
16
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@finedesign/cli",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Read-only, versioned Fine Design documentation for coding agents",
5
5
  "license": "MIT",
6
6
  "publishConfig": {
@@ -25,6 +25,7 @@
25
25
  "start": "node bin/fine-design.mjs mcp"
26
26
  },
27
27
  "dependencies": {
28
+ "@babel/parser": "7.29.2",
28
29
  "@modelcontextprotocol/sdk": "1.32.2",
29
30
  "zod": "4.6.7"
30
31
  },
@@ -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. Check the installed tool's help before using optional commands such as `doctor` 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.
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
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 and verify an affected interaction with local test data. Fix introduced failures and recheck. Report actual results and unverified behavior; reviews remain read-only.
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.
19
19
 
20
20
  ## Core Contracts
21
21
 
@@ -33,7 +33,7 @@ Use the sections relevant to the task. Selection choices are defaults for new wo
33
33
  | `Pagination`, `NextTable.pagination` | Use `page`, `size`, `sizeSet`, `count`; `sizeSet` contains the current `size`. To display the size chooser, also provide `showPageSize: size => String(size)`; `sizeSet` alone does not show it |
34
34
  | Legacy `DataTable` | Measurement may call `render('', {}, 0)`; guard the fields your renderer needs before reading records or attaching actions |
35
35
  | `PopConfirm` | Connect the confirmed mutation through `onOk` |
36
- | `Dialog` | Save via `onOk`; handle both `onCancel` and `onCloseBtnClick` |
36
+ | `Dialog` | Save via `onOk`; handle close/cancel via `onCancel` (clicking the close button triggers `onCancel`, so do not bind the same handler to both `onCancel` and deprecated `onCloseBtnClick`) |
37
37
  | `Tag` | Use semantic `type` or `style`; do not assume a `color` prop |
38
38
  | `Avatar` | Character fallback uses `name` |
39
39
  | `SvgIcon`, built-in icons | Import built-in icons from `@fx-ui/fine-design` (56 icons such as `SearchOutlined`, `PlusOutlined`, `EditOutlined`, `DeleteOutlined`, `SyncOutlined`, `RotateOutlined`, `EllipsisOutlined`); verify names via declarations or CLI `search`/`doc` instead of inventing `@ant-design/icons` names like `SettingOutlined` or `ReloadOutlined` |
package/src/cli.mjs CHANGED
@@ -2,19 +2,25 @@ import fs from 'node:fs';
2
2
  import path from 'node:path';
3
3
  import { fileURLToPath } from 'node:url';
4
4
  import { parseArgs } from 'node:util';
5
- import { queryCatalog } from './core/catalog.mjs';
5
+ import { queryCatalog, getComponentInfo, getComponentTokens, diffCatalogs } from './core/catalog.mjs';
6
6
  import { loadCatalog, readIndex } from './core/data.mjs';
7
7
  import { resolveVersion } from './core/version.mjs';
8
8
  import { ToolError, errorResult } from './core/errors.mjs';
9
9
  import { listRuntimes, resolveRuntime } from './core/runtime.mjs';
10
+ import { lintFiles } from './core/lint.mjs';
10
11
  import html from './core/html.cjs';
11
12
 
12
13
  const help = `Usage: fine-design <command> [arguments] [options]
13
14
 
14
15
  Commands:
16
+ list List all components in the target version
15
17
  search [query] Search or browse components
18
+ info <component> Show component overview and API/props sections
16
19
  doc <component> Read component documentation
20
+ token [component] [query] Inspect component or global Design Tokens
17
21
  example <component> <id> Read source files and asset metadata
22
+ lint [files-or-dirs...] Scan code for Fine Design API traps and invalid imports
23
+ diff [fromVer] [toVer] Compare component changes and migrations between versions
18
24
  doctor Inspect detected version, available catalogs and bundled Skill
19
25
  runtime [list] Resolve a versioned online UMD runtime or list published versions
20
26
  mcp Start the stdio MCP server
@@ -23,10 +29,11 @@ Options:
23
29
  --fd-version <version> Exact Fine Design component version
24
30
  --project <directory> Project used to detect the installed version
25
31
  --runtime-url <url> Runtime hosting base URL (runtime command only)
26
- --format <text|json|markdown|html> Output format (markdown: doc; html: runtime)
32
+ --format <text|json|markdown|html> Output format (markdown: doc/info/token; html: runtime)
27
33
  --section <heading> Doc section heading (exact or case-insensitive)
28
34
  --toc, --summary Show only doc metadata, section headings and example IDs
29
35
  --offset <number> Search pagination offset
36
+ --limit <number> Search page size (1..200, default 20)
30
37
  --include-assets Include binary base64 and oversized JSON fixture content
31
38
  --help Show help
32
39
  --version Show tool version`;
@@ -77,7 +84,7 @@ export async function main(argv) {
77
84
  const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, strict: true, options: {
78
85
  help: { type: 'boolean' }, version: { type: 'boolean' }, 'fd-version': { type: 'string' }, project: { type: 'string' },
79
86
  format: { type: 'string' }, section: { type: 'string' }, toc: { type: 'boolean' }, summary: { type: 'boolean' },
80
- offset: { type: 'string' }, 'include-assets': { type: 'boolean' },
87
+ offset: { type: 'string' }, limit: { type: 'string' }, 'include-assets': { type: 'boolean' },
81
88
  'runtime-url': { type: 'string' }
82
89
  }});
83
90
  format = values.format || 'text';
@@ -88,19 +95,19 @@ export async function main(argv) {
88
95
  if (command === 'mcp' && args.length === 0 && argv.length === 1) { await (await import('./mcp.mjs')).startMcp(); return; }
89
96
  const summaryFlag = Boolean(values.toc || values.summary);
90
97
  if (command !== 'runtime' && (values['runtime-url'] !== undefined)) throw new ToolError('INVALID_ARGUMENT', 'Runtime options are only supported for runtime.', 2);
91
- if (format === 'markdown' && command !== 'doc') {
92
- throw new ToolError('INVALID_ARGUMENT', 'Markdown output format is only supported for the doc command.', 2);
98
+ if (format === 'markdown' && !['doc', 'info', 'token'].includes(command)) {
99
+ throw new ToolError('INVALID_ARGUMENT', 'Markdown output format is only supported for the doc, info and token commands.', 2);
93
100
  }
94
101
  if (format === 'html' && (command !== 'runtime' || args.length)) throw new ToolError('INVALID_ARGUMENT', 'HTML output format is only supported for runtime resolution.', 2);
95
102
  if (command === 'runtime') {
96
103
  const list = args.length === 1 && args[0] === 'list';
97
- if ((!list && args.length) || values.version || values.section !== undefined || summaryFlag || values.offset !== 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);
104
+ 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);
98
105
  const result = list ? await listRuntimes(values['runtime-url']) : await resolveRuntime({ version: resolveVersion(values['fd-version'], values.project), runtimeURL: values['runtime-url'] });
99
106
  console.log(format === 'html' ? html.exampleHTML(result.resources, './').trimEnd() : format === 'json' ? JSON.stringify(result) : list ? result.versions.join('\n') : `Fine Design ${result.version} (offline docs: ${result.docsAvailable ? 'available' : 'not bundled'})\n${result.tags}\nExample: ${result.exampleURL}`);
100
107
  return;
101
108
  }
102
109
  if (command === 'doctor') {
103
- if (values.version || args.length > 0 || values.section !== undefined || summaryFlag || values.offset !== undefined || values['include-assets'] !== undefined) {
110
+ if (values.version || args.length > 0 || values.section !== undefined || summaryFlag || values.offset !== undefined || values.limit !== undefined || values['include-assets'] !== undefined) {
104
111
  throw new ToolError('INVALID_ARGUMENT', 'Invalid options for doctor. Use --help for usage.', 2);
105
112
  }
106
113
  const report = runDoctor(values);
@@ -119,6 +126,133 @@ export async function main(argv) {
119
126
  }
120
127
  return;
121
128
  }
129
+ if (command === 'list') {
130
+ if (values.version || args.length > 0 || values.section !== undefined || summaryFlag || values.offset !== undefined || values.limit !== undefined || values['include-assets'] !== undefined) {
131
+ throw new ToolError('INVALID_ARGUMENT', 'Invalid options for list. Use --help for usage.', 2);
132
+ }
133
+ const version = resolveVersion(values['fd-version'], values.project);
134
+ const result = queryCatalog(loadCatalog(version), 'search_components', { version, query: '', limit: 200 });
135
+ if (format === 'json') {
136
+ console.log(JSON.stringify(result));
137
+ } else {
138
+ console.log([
139
+ ...result.components.map((item) => `${item.id} (${item.exports.join(', ')})${item.subtitle ? ` - ${item.subtitle}` : ''}: ${item.description}`),
140
+ `Total: ${result.total} components (version ${result.version})`
141
+ ].join('\n'));
142
+ }
143
+ return;
144
+ }
145
+ if (command === 'info') {
146
+ if (values.version || args.length !== 1 || values.section !== undefined || summaryFlag || values.offset !== undefined || values.limit !== undefined || values['include-assets'] !== undefined) {
147
+ throw new ToolError('INVALID_ARGUMENT', 'Usage: fine-design info <component> [options]', 2);
148
+ }
149
+ const version = resolveVersion(values['fd-version'], values.project);
150
+ const result = getComponentInfo(loadCatalog(version), { component: args[0] });
151
+ if (format === 'json') {
152
+ console.log(JSON.stringify(result));
153
+ } else if (format === 'markdown') {
154
+ console.log([
155
+ `# ${result.title}${result.subtitle ? ` ${result.subtitle}` : ''} (\`${result.component}\`)`,
156
+ result.description || '',
157
+ `Exports: ${result.exports.map((name) => `\`${name}\``).join(', ')}`,
158
+ ...(result.aliases?.length ? [`Aliases: ${result.aliases.map((name) => `\`${name}\``).join(', ')}`] : []),
159
+ result.markdown || `No API documentation available for ${result.component}.`
160
+ ].filter(Boolean).join('\n\n'));
161
+ } else {
162
+ console.log([
163
+ `${result.component} (${result.exports.join(', ')})${result.subtitle ? ` - ${result.subtitle}` : ''}`,
164
+ ...(result.description ? [result.description] : []),
165
+ ...(result.aliases?.length ? [`Aliases: ${result.aliases.join(', ')}`] : []),
166
+ '',
167
+ result.markdown || `No API documentation available for ${result.component}.`,
168
+ '',
169
+ `Examples: ${result.examples.map((item) => item.id).join(', ') || 'none'}`
170
+ ].join('\n'));
171
+ }
172
+ return;
173
+ }
174
+ if (command === 'token') {
175
+ if (values.version || args.length > 2 || values.section !== undefined || summaryFlag || values.offset !== undefined || values.limit !== undefined || values['include-assets'] !== undefined) {
176
+ throw new ToolError('INVALID_ARGUMENT', 'Usage: fine-design token [component] [query] [options]', 2);
177
+ }
178
+ const version = resolveVersion(values['fd-version'], values.project);
179
+ const result = getComponentTokens(loadCatalog(version), { component: args[0], query: args[1] || '' });
180
+ if (format === 'json') {
181
+ console.log(JSON.stringify(result));
182
+ } else if (result.component) {
183
+ if (format === 'markdown') {
184
+ console.log(result.markdown);
185
+ } else {
186
+ const compLines = result.componentTokens.map((t) => ` ${t.name}: ${t.value}`);
187
+ const globalLines = result.globalTokens.map((t) => ` ${t.name}: ${t.value}`);
188
+ console.log([
189
+ `${result.component} (${result.exports.join(', ')}) Design Tokens`,
190
+ `Component Tokens (${result.componentTokens.length}):`,
191
+ ...(compLines.length ? compLines : [' none']),
192
+ `Global Tokens (${result.globalTokens.length}):`,
193
+ ...(globalLines.length ? globalLines : [' none'])
194
+ ].join('\n'));
195
+ }
196
+ } else {
197
+ const tokenLines = result.globalTokens.map((t) => `| \`${t.name}\` | \`${t.value}\` |`);
198
+ if (format === 'markdown') {
199
+ console.log([
200
+ `# Fine Design ${result.version} Global Tokens (${result.totalGlobalTokens})`,
201
+ '| Token 名称 | 默认值 |',
202
+ '| --- | --- |',
203
+ ...tokenLines
204
+ ].join('\n'));
205
+ } else {
206
+ console.log([
207
+ `Fine Design ${result.version} Global Tokens (${result.totalGlobalTokens}):`,
208
+ ...result.globalTokens.map((t) => ` ${t.name}: ${t.value}`),
209
+ `Components with Component Tokens (${result.componentsWithTokens.length}): ${result.componentsWithTokens.map((c) => `${c.exports[0]}(${c.componentTokenCount})`).join(', ')}`
210
+ ].join('\n'));
211
+ }
212
+ }
213
+ return;
214
+ }
215
+ if (command === 'lint') {
216
+ if (values.version || values.section !== undefined || summaryFlag || values.offset !== undefined || values.limit !== undefined || values['include-assets'] !== undefined || !['text', 'json'].includes(format)) {
217
+ throw new ToolError('INVALID_ARGUMENT', 'Usage: fine-design lint [files-or-dirs...] [--format text|json]', 2);
218
+ }
219
+ const version = resolveVersion(values['fd-version'], values.project);
220
+ const report = lintFiles(loadCatalog(version), args.length ? args : [values.project || process.cwd()]);
221
+ if (format === 'json') {
222
+ console.log(JSON.stringify(report));
223
+ } else if (!report.diagnostics.length) {
224
+ console.log(`Scanned ${report.scannedFiles} file(s) against Fine Design ${report.version}: 0 errors, 0 warnings.`);
225
+ } else {
226
+ const lines = report.diagnostics.map((d) => `${d.file}:${d.line} [${d.severity}] (${d.rule}) ${d.message}\n Suggestion: ${d.suggestion}`);
227
+ lines.push(`Scanned ${report.scannedFiles} file(s): ${report.errorCount} error(s), ${report.warningCount} warning(s).`);
228
+ console.log(lines.join('\n'));
229
+ }
230
+ if (!report.passed) process.exitCode = 1;
231
+ return;
232
+ }
233
+ if (command === 'diff') {
234
+ 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);
236
+ }
237
+ const available = Object.keys(readIndex().versions).sort();
238
+ const fromVer = args[0] || available[0];
239
+ const toVer = args[1] || available.at(-1);
240
+ const result = diffCatalogs(loadCatalog(fromVer), loadCatalog(toVer));
241
+ if (format === 'json') {
242
+ console.log(JSON.stringify(result));
243
+ } else {
244
+ console.log([
245
+ `Fine Design ${result.fromVersion} -> ${result.toVersion}`,
246
+ `Added components (${result.addedComponents.length}): ${result.addedComponents.map((c) => `${c.exports.join('/')} (${c.id})`).join(', ') || 'none'}`,
247
+ `Removed components (${result.removedComponents.length}): ${result.removedComponents.map((c) => `${c.exports.join('/')} (${c.id})`).join(', ') || 'none'}`,
248
+ `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}`)
252
+ ].join('\n'));
253
+ }
254
+ return;
255
+ }
122
256
  const tools = { search: 'search_components', doc: 'get_component_doc', example: 'get_component_example' };
123
257
  if (
124
258
  !Object.hasOwn(tools, command) ||
@@ -129,17 +263,22 @@ export async function main(argv) {
129
263
  (values.section !== undefined && command !== 'doc') ||
130
264
  ((values.toc !== undefined || values.summary !== undefined) && command !== 'doc') ||
131
265
  (values.section !== undefined && summaryFlag) ||
132
- (values.offset !== undefined && command !== 'search') ||
266
+ ((values.offset !== undefined || values.limit !== undefined) && command !== 'search') ||
133
267
  (values['include-assets'] !== undefined && command !== 'example')
134
268
  ) {
135
269
  throw new ToolError('INVALID_ARGUMENT', 'Invalid command or arguments. Use --help for usage.', 2);
136
270
  }
137
271
  if (values.offset !== undefined && !/^\d+$/.test(values.offset)) throw new ToolError('INVALID_ARGUMENT', 'Offset must be a non-negative integer.', 2);
272
+ if (values.limit !== undefined && !/^[1-9]\d*$/.test(values.limit)) throw new ToolError('INVALID_ARGUMENT', 'Limit must be a positive integer.', 2);
138
273
  const version = resolveVersion(values['fd-version'], values.project);
139
274
  const input = {
140
275
  version,
141
276
  ...(command === 'search'
142
- ? { query: args[0] ?? '', ...(values.offset !== undefined && { offset: Number(values.offset) }) }
277
+ ? {
278
+ query: args[0] ?? '',
279
+ ...(values.offset !== undefined && { offset: Number(values.offset) }),
280
+ ...(values.limit !== undefined && { limit: Number(values.limit) })
281
+ }
143
282
  : {
144
283
  component: args[0],
145
284
  ...(command === 'doc' && values.section !== undefined && { section: values.section }),
@@ -159,6 +298,7 @@ export async function main(argv) {
159
298
  `# ${result.title}${result.subtitle ? ` ${result.subtitle}` : ''} (\`${result.component}\`)`,
160
299
  result.description || '',
161
300
  `Exports: ${result.exports.map((name) => `\`${name}\``).join(', ')}`,
301
+ ...(result.aliases?.length ? [`Aliases: ${result.aliases.map((name) => `\`${name}\``).join(', ')}`] : []),
162
302
  `## Sections\n${result.sections.map((heading) => `- ${heading}`).join('\n') || '- none'}`,
163
303
  `## Examples\n${result.examples.map((item) => `- \`${item.id}\`: ${item.title}`).join('\n') || '- none'}`
164
304
  ].filter(Boolean).join('\n\n'));
@@ -166,6 +306,7 @@ export async function main(argv) {
166
306
  console.log([
167
307
  `${result.component} (${result.exports.join(', ')})${result.subtitle ? ` - ${result.subtitle}` : ''}`,
168
308
  ...(result.description ? [result.description] : []),
309
+ ...(result.aliases?.length ? [`Aliases: ${result.aliases.join(', ')}`] : []),
169
310
  `Docs available: ${result.docsAvailable}`,
170
311
  `Sections: ${result.sections.join(', ') || 'none'}`,
171
312
  `Examples: ${result.examples.map((item) => item.id).join(', ') || 'none'}`