@finedesign/cli 0.5.1 → 0.6.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 CHANGED
@@ -1,5 +1,15 @@
1
1
  # 更新日志
2
2
 
3
+ ## 0.6.0
4
+
5
+ 2026-11-09
6
+
7
+ - 新增 `init`,初始化 Cursor、Claude Code 与 Codex 的项目规则及 Skill;默认保留已有 Skill,覆盖需显式指定 `--force`。
8
+ - 新增 `add <component> [id]`,提取完整示例及辅助文件,保留相对目录与资源引用,输出依赖信息;写入前检查全部文件冲突。
9
+ - MCP 组件资料查询可省略 `version`,默认检测进程工作目录的组件版本,检测不到时使用内置 Skill 对应版本;运行时查询省略版本时使用当前托管版本。
10
+ - `lint` 增加 Select、Combo、PopConfirm 及 Pagination 的常见属性误用检查,支持 `Combo.Check` 与 NextTable 内联分页配置。
11
+ - 补充初始化覆盖保护、跨目录资源引用及冲突时不写入文件的回归测试,同步 MCP 接入说明与许可署名。
12
+
3
13
  ## 0.5.1
4
14
 
5
15
  2026-11-06
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT LICENSE
2
2
 
3
- Copyright (c) 2018-present JDY DESIGN, https://jdy.design/
3
+ Copyright (c) 2018-present Fine Design, https://docs.fanruan.design/index-cn
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining
6
6
  a copy of this software and associated documentation files (the
package/README.md CHANGED
@@ -71,7 +71,7 @@ CLI 内置 `skills/fine-design/SKILL.md`。将以下指令发给 AI 编码助手
71
71
  }
72
72
  ```
73
73
 
74
- MCP 提供组件搜索、API、Design Token、示例、版本对比、代码检查和浏览器运行时查询。客户端可自动发现工具参数。组件查询需传入精确的 `version`,代码检查可以从目标工程检测版本,运行时查询需要联网。
74
+ MCP 提供组件搜索、API、Design Token、示例、版本对比、代码检查和浏览器运行时查询。客户端可自动发现工具参数。组件资料查询可省略 `version`:默认从 MCP 进程工作目录检测组件版本,检测不到时使用内置 Skill 对应的资料版本;已检测但未收录的版本仍会报错。代码检查从扫描目标检测版本。`get_browser_runtime` 省略版本时使用当前托管版本,运行时查询需要联网。
75
75
 
76
76
  ## 命令
77
77
 
@@ -96,13 +96,17 @@ MCP 提供组件搜索、API、Design Token、示例、版本对比、代码检
96
96
  | `lint [files-or-dirs...]` | 扫描常见 API 陷阱与非法导入 |
97
97
  | `diff [fromVer] [toVer]` | 对比版本间的文档、示例和迁移建议,支持 `--component <name>` |
98
98
 
99
- ### 集成与预览
99
+ ### 集成与代码落地
100
100
 
101
101
  | 命令 | 用途 |
102
102
  | --- | --- |
103
+ | `init` | 一键初始化 Agent 规则与配置(`--agent cursor/claude/codex/all`) |
104
+ | `add <component> [id]` | 提取组件示例代码及附属文件到项目目录(支持 `--output` 与 `--force`) |
103
105
  | `mcp` | 启动 stdio MCP 服务 |
104
106
  | `runtime [list]` | 查询在线运行时或生成完整 HTML 页面 |
105
107
 
108
+ `init` 默认保留已有 Skill,覆盖需指定 `--force`。`add` 保留示例文件之间的相对目录关系,跨目录资源会生成相应子目录;已有文件冲突时在写入前报错,覆盖需指定 `--force`。
109
+
106
110
  ## 版本与输出
107
111
 
108
112
  - **组件版本**:`--fd-version` 优先,其次使用 `--project <目录>` 指定的工程。未指定时,`lint` 从扫描目标检测版本,其他组件查询从当前工程检测。未收录的版本会报错。
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@finedesign/cli",
3
- "version": "0.5.1",
4
- "description": "Read-only, versioned Fine Design documentation for coding agents",
3
+ "version": "0.6.0",
4
+ "description": "Versioned Fine Design docs, code checks and agent setup for coding agents",
5
5
  "license": "MIT",
6
6
  "publishConfig": {
7
7
  "registry": "https://registry.npmjs.org/",
package/src/cli.mjs CHANGED
@@ -2,7 +2,7 @@ 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, getComponentInfo, getComponentTokens, diffCatalogs } from './core/catalog.mjs';
5
+ import { queryCatalog, getComponentInfo, getComponentTokens, diffCatalogs, resolveComponentOrThrow } from './core/catalog.mjs';
6
6
  import { validateInput } from './core/contracts.mjs';
7
7
  import { loadCatalog, readIndex } from './core/data.mjs';
8
8
  import { resolveLintVersion, resolveVersion } from './core/version.mjs';
@@ -19,6 +19,8 @@ Commands:
19
19
  doc <component> Read component documentation
20
20
  token [component] [query] Inspect component or global Design Tokens
21
21
  example <component> [id] List examples or read one example's source and asset metadata
22
+ add <component> [id] Add/extract an example component into your project
23
+ init Initialize agent configuration (.cursorrules, Claude Skill, etc.)
22
24
  lint [files-or-dirs...] Scan code for Fine Design API traps and invalid imports
23
25
  diff [fromVer] [toVer] Compare component changes and migrations between versions
24
26
  doctor Inspect detected version, available catalogs and bundled Skill
@@ -29,6 +31,9 @@ Options:
29
31
  --fd-version <version> Exact Fine Design component version
30
32
  --project <directory> Project used to detect the installed version
31
33
  --component <name> Compare only this component (diff command only)
34
+ --agent <cursor|claude|codex|all> Target agent configuration (init command only)
35
+ --output <directory> Destination directory for extracted component (add command only)
36
+ --force Overwrite existing files (init and add commands)
32
37
  --runtime-url <url> Runtime hosting base URL (runtime command only)
33
38
  --format <text|json|markdown|html> Output format (markdown: doc/info/token; html: runtime)
34
39
  --section <heading> Doc section heading (exact or case-insensitive)
@@ -82,6 +87,185 @@ function runDoctor(values) {
82
87
  };
83
88
  }
84
89
 
90
+ function runInit(values) {
91
+ const projectDir = path.resolve(values.project || process.cwd());
92
+ if (!fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) {
93
+ throw new ToolError('INVALID_ARGUMENT', `Project directory does not exist: ${projectDir}`, 2);
94
+ }
95
+ const agent = (values.agent || 'all').toLowerCase();
96
+ const validAgents = ['cursor', 'claude', 'codex', 'all'];
97
+ if (!validAgents.includes(agent)) {
98
+ throw new ToolError('INVALID_ARGUMENT', `Invalid agent "${values.agent}". Allowed: ${validAgents.join(', ')}`, 2);
99
+ }
100
+
101
+ const bundledSkillDir = fileURLToPath(new URL('../skills/fine-design', import.meta.url));
102
+ const created = [];
103
+ const updated = [];
104
+
105
+ const agentInstructions = `# Fine Design Rules
106
+
107
+ 开发或修改 Fine Design 页面时,在目标项目目录运行 CLI。项目已安装 CLI 时用 \`npx fine-design\`,否则用 \`npx -y @finedesign/cli\`。
108
+
109
+ 1. 运行 \`doctor --format json\` 并读取 \`bundledSkillPath\` 指向的 Skill。先确定交付形式。接入现有 React 工程时沿用项目组件版本、壳层和同类页面。
110
+ 2. 交付独立 HTML 或无构建预览时,先单独运行 \`runtime list --format json\`,根据退出码判断清单是否可用。用 \`versions\` 返回的版本解析 UMD 资源,再查组件 API。
111
+ 3. 按目标版本用 \`info\` 查组件 API。\`list --format json\` 从 \`components\` 数组读取组件,\`example <组件>\` 先列示例 ID,按需再读源码。
112
+ 4. 对改动文件运行 \`lint\` 并执行项目已有检查。分别记录工程检查、UMD 清单解析和目标预览中的关键交互结果,标明未验证项。
113
+ `;
114
+
115
+ const cursorMdcContent = `---
116
+ description: Fine Design component library guidelines, API traps and verification rules
117
+ globs: **/*.{tsx,jsx,ts,js,html}
118
+ alwaysApply: false
119
+ ---
120
+
121
+ ${agentInstructions}`;
122
+
123
+ if (agent === 'cursor' || agent === 'all') {
124
+ const cursorRulesFile = path.join(projectDir, '.cursorrules');
125
+ if (!fs.existsSync(cursorRulesFile) || values.force) {
126
+ fs.writeFileSync(cursorRulesFile, agentInstructions, 'utf8');
127
+ created.push('.cursorrules');
128
+ } else {
129
+ const existing = fs.readFileSync(cursorRulesFile, 'utf8');
130
+ if (!existing.includes('fine-design') && !existing.includes('@finedesign/cli')) {
131
+ fs.appendFileSync(cursorRulesFile, `\n\n${agentInstructions}`, 'utf8');
132
+ updated.push('.cursorrules');
133
+ }
134
+ }
135
+ const cursorRulesDir = path.join(projectDir, '.cursor', 'rules');
136
+ fs.mkdirSync(cursorRulesDir, { recursive: true });
137
+ const mdcFile = path.join(cursorRulesDir, 'fine-design.mdc');
138
+ if (!fs.existsSync(mdcFile) || values.force) {
139
+ fs.writeFileSync(mdcFile, cursorMdcContent, 'utf8');
140
+ created.push('.cursor/rules/fine-design.mdc');
141
+ }
142
+ }
143
+
144
+ if (agent === 'claude' || agent === 'all') {
145
+ const claudeSkillsDir = path.join(projectDir, '.claude', 'skills', 'fine-design');
146
+ if (fs.existsSync(bundledSkillDir) && (!fs.existsSync(claudeSkillsDir) || values.force)) {
147
+ fs.mkdirSync(claudeSkillsDir, { recursive: true });
148
+ fs.cpSync(bundledSkillDir, claudeSkillsDir, { recursive: true });
149
+ created.push('.claude/skills/fine-design/');
150
+ }
151
+ const claudeMdFile = path.join(projectDir, 'CLAUDE.md');
152
+ if (!fs.existsSync(claudeMdFile) || values.force) {
153
+ fs.writeFileSync(claudeMdFile, agentInstructions, 'utf8');
154
+ created.push('CLAUDE.md');
155
+ } else {
156
+ const existing = fs.readFileSync(claudeMdFile, 'utf8');
157
+ if (!existing.includes('fine-design') && !existing.includes('@finedesign/cli')) {
158
+ fs.appendFileSync(claudeMdFile, `\n\n${agentInstructions}`, 'utf8');
159
+ updated.push('CLAUDE.md');
160
+ }
161
+ }
162
+ }
163
+
164
+ if (agent === 'codex' || agent === 'all') {
165
+ const codexSkillsDir = path.join(projectDir, '.agents', 'skills', 'fine-design');
166
+ if (fs.existsSync(bundledSkillDir) && (!fs.existsSync(codexSkillsDir) || values.force)) {
167
+ fs.mkdirSync(codexSkillsDir, { recursive: true });
168
+ fs.cpSync(bundledSkillDir, codexSkillsDir, { recursive: true });
169
+ created.push('.agents/skills/fine-design/');
170
+ }
171
+ const agentsMdFile = path.join(projectDir, 'AGENTS.md');
172
+ if (!fs.existsSync(agentsMdFile) || values.force) {
173
+ fs.writeFileSync(agentsMdFile, agentInstructions, 'utf8');
174
+ created.push('AGENTS.md');
175
+ } else {
176
+ const existing = fs.readFileSync(agentsMdFile, 'utf8');
177
+ if (!existing.includes('fine-design') && !existing.includes('@finedesign/cli')) {
178
+ fs.appendFileSync(agentsMdFile, `\n\n${agentInstructions}`, 'utf8');
179
+ updated.push('AGENTS.md');
180
+ }
181
+ }
182
+ }
183
+
184
+ return {
185
+ projectDir,
186
+ agent,
187
+ created: [...new Set(created)],
188
+ updated: [...new Set(updated)]
189
+ };
190
+ }
191
+
192
+ function runAdd(componentArg, exampleArg, values) {
193
+ if (!componentArg) {
194
+ throw new ToolError('INVALID_ARGUMENT', 'Usage: fine-design add <component> [id] [options]', 2);
195
+ }
196
+ const version = resolveVersion(values['fd-version'], values.project);
197
+ const catalog = loadCatalog(version);
198
+ const resolvedComp = resolveComponentOrThrow(catalog, componentArg);
199
+
200
+ let exampleId = exampleArg;
201
+ if (!exampleId) {
202
+ if (resolvedComp.examples?.some((ex) => ex.id === 'basic')) {
203
+ exampleId = 'basic';
204
+ } else if (resolvedComp.examples?.length > 0) {
205
+ exampleId = resolvedComp.examples[0].id;
206
+ } else {
207
+ throw new ToolError('EXAMPLE_NOT_FOUND', `Component "${resolvedComp.title || resolvedComp.id}" has no examples available.`, 4);
208
+ }
209
+ }
210
+
211
+ const example = queryCatalog(catalog, 'get_component_example', {
212
+ version,
213
+ component: resolvedComp.id,
214
+ exampleId,
215
+ includeAssets: true
216
+ });
217
+ if (!example?.files?.length) {
218
+ throw new ToolError('EXAMPLE_NOT_FOUND', `Example "${exampleId}" not found for ${resolvedComp.id}.`, 4);
219
+ }
220
+
221
+ const projectDir = path.resolve(values.project || process.cwd());
222
+ let targetDir;
223
+ if (values.output) {
224
+ targetDir = path.resolve(projectDir, values.output);
225
+ } else {
226
+ const hasSrc = fs.existsSync(path.join(projectDir, 'src'));
227
+ targetDir = hasSrc
228
+ ? path.join(projectDir, 'src', 'components', resolvedComp.id)
229
+ : path.join(projectDir, 'components', resolvedComp.id);
230
+ }
231
+ let sourceDir = path.posix.dirname(example.entry);
232
+ while (sourceDir !== '.' && example.files.some((file) => !file.path.startsWith(`${sourceDir}/`))) {
233
+ sourceDir = path.posix.dirname(sourceDir);
234
+ }
235
+ const prefix = sourceDir === '.' ? '' : `${sourceDir}/`;
236
+ const files = example.files.map((file) => ({ file, destPath: path.join(targetDir, file.path.slice(prefix.length)) }));
237
+ const writtenFiles = [];
238
+
239
+ for (const { destPath } of files) {
240
+ if (fs.existsSync(destPath) && !values.force) {
241
+ throw new ToolError('FILE_EXISTS', `File already exists: ${path.relative(projectDir, destPath)}. Use --force to overwrite.`, 1);
242
+ }
243
+ }
244
+ for (const { file, destPath } of files) {
245
+ fs.mkdirSync(path.dirname(destPath), { recursive: true });
246
+ if (file.encoding === 'base64') {
247
+ fs.writeFileSync(destPath, Buffer.from(file.content, 'base64'));
248
+ } else {
249
+ fs.writeFileSync(destPath, file.content, 'utf8');
250
+ }
251
+ writtenFiles.push(path.relative(projectDir, destPath));
252
+ }
253
+
254
+ const requiredDependencies = (example.dependencies || []).filter(
255
+ (dep) => !['react', 'react-dom', '@fx-ui/fine-design'].includes(dep)
256
+ );
257
+
258
+ return {
259
+ component: resolvedComp.id,
260
+ exampleId,
261
+ version,
262
+ targetDir: path.relative(projectDir, targetDir) || '.',
263
+ writtenFiles,
264
+ dependencies: example.dependencies || [],
265
+ requiredDependencies
266
+ };
267
+ }
268
+
85
269
  export async function main(argv) {
86
270
  let format = 'text';
87
271
  try {
@@ -89,7 +273,8 @@ export async function main(argv) {
89
273
  help: { type: 'boolean' }, version: { type: 'boolean' }, 'fd-version': { type: 'string' }, project: { type: 'string' },
90
274
  format: { type: 'string' }, section: { type: 'string' }, toc: { type: 'boolean' }, summary: { type: 'boolean' },
91
275
  offset: { type: 'string' }, limit: { type: 'string' }, 'include-assets': { type: 'boolean' },
92
- 'runtime-url': { type: 'string' }, component: { type: 'string' }
276
+ 'runtime-url': { type: 'string' }, component: { type: 'string' },
277
+ agent: { type: 'string' }, output: { type: 'string' }, force: { type: 'boolean' }
93
278
  }});
94
279
  format = values.format || 'text';
95
280
  if (!['text', 'json', 'markdown', 'html'].includes(format)) throw new ToolError('INVALID_ARGUMENT', 'Unknown output format.', 2);
@@ -100,6 +285,9 @@ export async function main(argv) {
100
285
  const summaryFlag = Boolean(values.toc || values.summary);
101
286
  if (command !== 'runtime' && (values['runtime-url'] !== undefined)) throw new ToolError('INVALID_ARGUMENT', 'Runtime options are only supported for runtime.', 2);
102
287
  if (command !== 'diff' && values.component !== undefined) throw new ToolError('INVALID_ARGUMENT', '--component is only supported for diff.', 2);
288
+ if (command !== 'init' && values.agent !== undefined) throw new ToolError('INVALID_ARGUMENT', '--agent is only supported for init.', 2);
289
+ if (command !== 'add' && values.output !== undefined) throw new ToolError('INVALID_ARGUMENT', '--output is only supported for add.', 2);
290
+ if (!['init', 'add'].includes(command) && values.force !== undefined) throw new ToolError('INVALID_ARGUMENT', '--force is only supported for init and add.', 2);
103
291
  if (format === 'markdown' && !['doc', 'info', 'token'].includes(command)) {
104
292
  throw new ToolError('INVALID_ARGUMENT', 'Markdown output format is only supported for the doc, info and token commands.', 2);
105
293
  }
@@ -131,6 +319,44 @@ export async function main(argv) {
131
319
  }
132
320
  return;
133
321
  }
322
+ if (command === 'init') {
323
+ if (values.version || args.length > 0 || values.section !== undefined || summaryFlag || values.offset !== undefined || values.limit !== undefined || values['include-assets'] !== undefined || values['fd-version'] !== undefined || !['text', 'json'].includes(format)) {
324
+ throw new ToolError('INVALID_ARGUMENT', 'Usage: fine-design init [--agent <cursor|claude|codex|all>] [--project <dir>] [--force] [--format text|json]', 2);
325
+ }
326
+ const report = runInit(values);
327
+ if (format === 'json') {
328
+ console.log(JSON.stringify(report));
329
+ } else {
330
+ const lines = [
331
+ `Initialized Fine Design agent configuration (${report.agent}) in ${report.projectDir}:`,
332
+ ' Created files:',
333
+ ...(report.created.length ? report.created.map((f) => ` - ${f}`) : [' - none']),
334
+ ' Updated files:',
335
+ ...(report.updated.length ? report.updated.map((f) => ` - ${f}`) : [' - none'])
336
+ ];
337
+ console.log(lines.join('\n'));
338
+ }
339
+ return;
340
+ }
341
+ if (command === 'add') {
342
+ if (values.version || args.length < 1 || args.length > 2 || values.section !== undefined || summaryFlag || values.offset !== undefined || values.limit !== undefined || values['include-assets'] !== undefined || !['text', 'json'].includes(format)) {
343
+ throw new ToolError('INVALID_ARGUMENT', 'Usage: fine-design add <component> [id] [--output <dir>] [--force] [--fd-version <version>] [--format text|json]', 2);
344
+ }
345
+ const report = runAdd(args[0], args[1], values);
346
+ if (format === 'json') {
347
+ console.log(JSON.stringify(report));
348
+ } else {
349
+ const lines = [
350
+ `Added ${report.component} (${report.exampleId}) to ${report.targetDir}:`,
351
+ ...report.writtenFiles.map((f) => ` - ${f}`)
352
+ ];
353
+ if (report.requiredDependencies.length) {
354
+ lines.push('', 'Required dependencies:', ` npm install ${report.requiredDependencies.join(' ')}`);
355
+ }
356
+ console.log(lines.join('\n'));
357
+ }
358
+ return;
359
+ }
134
360
  if (command === 'list') {
135
361
  if (values.version || args.length > 0 || values.section !== undefined || summaryFlag || values.offset !== undefined || values.limit !== undefined || values['include-assets'] !== undefined) {
136
362
  throw new ToolError('INVALID_ARGUMENT', 'Invalid options for list. Use --help for usage.', 2);
@@ -84,7 +84,7 @@ function sourceMetadata(catalog) {
84
84
  };
85
85
  }
86
86
 
87
- function resolveComponentOrThrow(catalog, rawComponent) {
87
+ export function resolveComponentOrThrow(catalog, rawComponent) {
88
88
  const targetName = rawComponent.toLowerCase();
89
89
  const component =
90
90
  catalog.components.find((item) =>
@@ -5,23 +5,23 @@ const version = z.string().min(1).max(80);
5
5
  const component = z.string().min(1).max(100);
6
6
  export const schemas = {
7
7
  search_components: z.object({
8
- version,
8
+ version: version.optional(),
9
9
  query: z.string().max(200),
10
10
  offset: z.number().int().min(0).max(10000).optional(),
11
11
  limit: z.number().int().min(1).max(200).optional()
12
12
  }).strict(),
13
13
  get_component_doc: z.object({
14
- version,
14
+ version: version.optional(),
15
15
  component,
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
19
  get_component_info: z.object({
20
- version,
20
+ version: version.optional(),
21
21
  component
22
22
  }).strict(),
23
23
  get_component_tokens: z.object({
24
- version,
24
+ version: version.optional(),
25
25
  component: component.optional(),
26
26
  query: z.string().max(200).optional()
27
27
  }).strict(),
@@ -38,9 +38,9 @@ export const schemas = {
38
38
  path: z.string().min(1).max(1024).optional()
39
39
  }).strict(),
40
40
  list_browser_runtimes: z.object({ runtimeURL: z.string().max(2048).optional() }).strict(),
41
- get_browser_runtime: z.object({ version, runtimeURL: z.string().max(2048).optional() }).strict(),
41
+ get_browser_runtime: z.object({ version: version.optional(), runtimeURL: z.string().max(2048).optional() }).strict(),
42
42
  get_component_example: z.object({
43
- version,
43
+ version: version.optional(),
44
44
  component,
45
45
  exampleId: z.string().min(1).max(200).optional().describe('Omit to list available example IDs and titles.'),
46
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.')
package/src/core/lint.mjs CHANGED
@@ -186,8 +186,10 @@ function componentName(node, scope) {
186
186
  node = binding?.initializer;
187
187
  scope = binding?.scope;
188
188
  }
189
- if (['MemberExpression', 'JSXMemberExpression'].includes(node?.type) && !node.computed && isFineDesignNamespace(node.object, scope)) {
190
- return node.property.name;
189
+ if (['MemberExpression', 'JSXMemberExpression'].includes(node?.type) && !node.computed) {
190
+ if (isFineDesignNamespace(node.object, scope)) return node.property.name;
191
+ const parent = componentName(node.object, scope);
192
+ if (parent) return `${parent}.${node.property.name}`;
191
193
  }
192
194
  }
193
195
 
@@ -286,7 +288,17 @@ export function lintFiles(catalog, targets = ['.']) {
286
288
  if (type?.type === 'ObjectProperty' && !type.computed) checkButtonType(type, type.value.value);
287
289
  } else if (node.type === 'JSXOpeningElement') {
288
290
  const component = componentName(node.name, scope);
289
- for (const attr of node.attributes.filter((item) => item.type === 'JSXAttribute')) {
291
+ const jsxAttrs = node.attributes.filter((item) => item.type === 'JSXAttribute');
292
+ const attrNames = new Set(jsxAttrs.map((item) => item.name?.name));
293
+
294
+ if (component === 'Pagination' && attrNames.has('sizeSet') && !attrNames.has('showPageSize')) {
295
+ const sizeSetAttr = jsxAttrs.find((item) => item.name?.name === 'sizeSet');
296
+ report(sizeSetAttr, 'pagination-missing-showpagesize', 'warning',
297
+ 'Pagination has "sizeSet" but lacks "showPageSize".',
298
+ 'Provide showPageSize={(size) => String(size)} so the page size selector is displayed.');
299
+ }
300
+
301
+ for (const attr of jsxAttrs) {
290
302
  const name = attr.name.name;
291
303
  const value = (attr.value?.expression || attr.value)?.value;
292
304
  if (component === 'Button' && name === 'type') {
@@ -294,6 +306,49 @@ export function lintFiles(catalog, targets = ['.']) {
294
306
  } else if (component === 'NextTable' && name === 'columns') {
295
307
  report(attr, 'next-table-columns-prop', 'error', 'NextTable does not accept a "columns" prop.',
296
308
  'Declare <NextTable.Column>, <NextTable.HeaderCell>, and <NextTable.Cell dataKey="..."> children instead.');
309
+ } else if (component === 'NextTable' && name === 'pagination' && attr.value?.type === 'JSXExpressionContainer' && attr.value.expression?.type === 'ObjectExpression') {
310
+ const props = attr.value.expression.properties;
311
+ const propMap = new Map();
312
+ for (const prop of props) {
313
+ if (prop.type === 'ObjectProperty' && !prop.computed) {
314
+ propMap.set(prop.key.name ?? prop.key.value, prop);
315
+ }
316
+ }
317
+ if (propMap.has('current')) {
318
+ report(propMap.get('current'), 'pagination-current-prop', 'error',
319
+ 'NextTable pagination object does not accept a "current" property.',
320
+ 'Use "page" instead of "current" to specify the active page.');
321
+ }
322
+ if (propMap.has('pageSize')) {
323
+ report(propMap.get('pageSize'), 'pagination-pagesize-prop', 'error',
324
+ 'NextTable pagination object does not accept a "pageSize" property.',
325
+ 'Use "size" instead of "pageSize" to specify the page size.');
326
+ }
327
+ if (propMap.has('sizeSet') && !propMap.has('showPageSize')) {
328
+ report(propMap.get('sizeSet'), 'pagination-missing-showpagesize', 'warning',
329
+ 'NextTable pagination object has "sizeSet" but lacks "showPageSize".',
330
+ 'Provide showPageSize: (size) => String(size) so the page size selector is displayed.');
331
+ }
332
+ } else if (component === 'Select' && name === 'items') {
333
+ report(attr, 'select-items-prop', 'error',
334
+ 'Select does not accept an "items" prop.',
335
+ 'Use "options" ({ label, value }[]) for Select, or use Combo / Combo.Check if you intended a Combo dropdown with items.');
336
+ } else if ((component === 'Combo' || component === 'Combo.Check') && name === 'options') {
337
+ report(attr, 'combo-options-prop', 'error',
338
+ `${component} does not accept an "options" prop.`,
339
+ `Use "items" ({ text, value }[]) for ${component}.`);
340
+ } else if (component === 'PopConfirm' && name === 'onConfirm') {
341
+ report(attr, 'popconfirm-onconfirm-prop', 'error',
342
+ 'PopConfirm does not accept an "onConfirm" prop.',
343
+ 'Use "onOk" for confirmation callback in PopConfirm.');
344
+ } else if (component === 'Pagination' && name === 'current') {
345
+ report(attr, 'pagination-current-prop', 'error',
346
+ 'Pagination does not accept a "current" prop.',
347
+ 'Use "page" instead of "current" to specify the active page.');
348
+ } else if (component === 'Pagination' && name === 'pageSize') {
349
+ report(attr, 'pagination-pagesize-prop', 'error',
350
+ 'Pagination does not accept a "pageSize" prop.',
351
+ 'Use "size" instead of "pageSize" to specify the page size.');
297
352
  } else if (component === 'Dialog' && name === 'onCloseBtnClick') {
298
353
  report(attr, 'dialog-deprecated-close-btn', 'warning', 'Dialog "onCloseBtnClick" is deprecated and fires alongside "onCancel" when clicking the close button.',
299
354
  'Handle close and cancel solely via "onCancel".');
@@ -55,13 +55,14 @@ export async function listRuntimes(runtimeURL) {
55
55
  }
56
56
 
57
57
  export async function resolveRuntime({ version, runtimeURL }) {
58
- if (!exactVersion.test(version)) throw new ToolError('INVALID_ARGUMENT', 'Specify an exact component version.', 2);
58
+ if (version !== undefined && !exactVersion.test(version)) throw new ToolError('INVALID_ARGUMENT', 'Specify an exact component version.', 2);
59
59
  const current = await readRuntime(runtimeURL);
60
- if (current.manifest.version !== version) throw new ToolError('RUNTIME_VERSION_NOT_FOUND', `Only Fine Design ${current.manifest.version} is currently hosted; ${version} is unavailable. Historical UMD files are not retained.`, 3, { availableVersions: [current.manifest.version] });
60
+ const targetVersion = version || current.manifest.version;
61
+ if (current.manifest.version !== targetVersion) throw new ToolError('RUNTIME_VERSION_NOT_FOUND', `Only Fine Design ${current.manifest.version} is currently hosted; ${targetVersion} is unavailable. Historical UMD files are not retained.`, 3, { availableVersions: [current.manifest.version] });
61
62
  const resources = Object.fromEntries(Object.entries(current.manifest.resources).map(([key, entry]) => [key, { ...entry, url: entry.url || new URL(entry.path, current.manifestURL).href }]));
62
63
  const tags = ['fineDesignCss', 'react', 'reactDOM', 'fineDesign'].map((key) => {
63
64
  const entry = resources[key];
64
65
  return entry.type === 'style' ? `<link rel="stylesheet" href="${entry.url}" integrity="${entry.integrity}" crossorigin="anonymous">` : `<script src="${entry.url}" integrity="${entry.integrity}" crossorigin="anonymous"></script>`;
65
66
  }).join('\n');
66
- return { version, docsAvailable: Object.hasOwn(readIndex().versions, version), manifestURL: current.manifestURL, exampleURL: new URL('index.html', current.runtimeURL).href, resources, tags };
67
+ return { version: targetVersion, docsAvailable: Object.hasOwn(readIndex().versions, targetVersion), manifestURL: current.manifestURL, exampleURL: new URL('index.html', current.runtimeURL).href, resources, tags };
67
68
  }
@@ -1,6 +1,6 @@
1
1
  import fs from 'node:fs';
2
2
  import path from 'node:path';
3
- import { exactVersion } from './data.mjs';
3
+ import { exactVersion, readIndex } from './data.mjs';
4
4
  import { ToolError } from './errors.mjs';
5
5
 
6
6
  export function resolveVersion(explicit, project = process.cwd()) {
@@ -52,3 +52,13 @@ export function resolveLintVersion(explicit, targets) {
52
52
  const [version] = versions;
53
53
  return version;
54
54
  }
55
+
56
+ export function resolveMcpVersion(explicit, project = process.cwd()) {
57
+ if (explicit !== undefined) return explicit;
58
+ try {
59
+ return resolveVersion(undefined, project);
60
+ } catch {
61
+ const index = readIndex();
62
+ return index.skillVersion || Object.keys(index.versions).sort().at(-1);
63
+ }
64
+ }
package/src/mcp.mjs CHANGED
@@ -8,7 +8,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';
11
+ import { resolveLintVersion, resolveMcpVersion } from './core/version.mjs';
12
12
 
13
13
  const aliases = {
14
14
  info: 'get_component_info',
@@ -21,15 +21,15 @@ export async function startMcp() {
21
21
  const packageInfo = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
22
22
  const server = new Server({ name: 'fine-design', version: packageInfo.version }, { capabilities: { tools: {} } });
23
23
  const descriptions = {
24
- search_components: 'Search components, subcomponents and built-in icons; use nextOffset to browse subsequent pages.',
25
- get_component_doc: 'Read component documentation, or pass summary: true to list section headings and example IDs first.',
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.',
24
+ search_components: 'Search components, subcomponents and built-in icons. Version is optional and defaults to the project or latest bundled version; use nextOffset to browse subsequent pages.',
25
+ get_component_doc: 'Read component documentation, or pass summary: true to list section headings and example IDs first. Version is optional.',
26
+ get_component_info: 'Show component overview, exports, aliases and API/props table sections. Version is optional.',
27
+ get_component_tokens: 'Inspect component or global Design Tokens and their default values. Version is optional.',
28
28
  diff_catalogs: 'Compare documentation sections, examples, aliases and migration guidance between versions, optionally for one component.',
29
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.',
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 an exact component version to versioned current UMD URLs and SRI loading tags. 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
33
  };
34
34
  server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: Object.entries(schemas).map(([name, schema]) => ({
35
35
  name, description: descriptions[name], inputSchema: z.toJSONSchema(schema, { target: 'draft-07' }),
@@ -46,9 +46,11 @@ export async function startMcp() {
46
46
  } else if (toolName === 'list_browser_runtimes') {
47
47
  result = await listRuntimes(args.runtimeURL);
48
48
  } else if (toolName === 'get_component_info') {
49
- result = getComponentInfo(loadCatalog(args.version), args);
49
+ const ver = resolveMcpVersion(args.version);
50
+ result = getComponentInfo(loadCatalog(ver), args);
50
51
  } else if (toolName === 'get_component_tokens') {
51
- result = getComponentTokens(loadCatalog(args.version), args);
52
+ const ver = resolveMcpVersion(args.version);
53
+ result = getComponentTokens(loadCatalog(ver), args);
52
54
  } else if (toolName === 'diff_catalogs') {
53
55
  const available = Object.keys(readIndex().versions).sort();
54
56
  const fromVer = args.fromVersion || args.version || available[0];
@@ -60,7 +62,8 @@ export async function startMcp() {
60
62
  const { lintFiles } = await import('./core/lint.mjs');
61
63
  result = lintFiles(loadCatalog(version), targets);
62
64
  } else {
63
- result = queryCatalog(loadCatalog(args.version), toolName, args);
65
+ const ver = resolveMcpVersion(args.version);
66
+ result = queryCatalog(loadCatalog(ver), toolName, { ...args, version: ver });
64
67
  }
65
68
  return { content: [{ type: 'text', text: JSON.stringify(result) }] };
66
69
  } catch (error) {