@finedesign/cli 0.5.1 → 0.6.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,15 +2,15 @@
2
2
  "schemaVersion": 1,
3
3
  "version": "1.25.0",
4
4
  "sourceKind": "repository-snapshot",
5
- "sourceRevision": "a88c1a76dc006929aa6ab9ce4f9de4ad0e926d0c",
5
+ "sourceRevision": "0b3a8ab99f46f33a91bf5f2dea1942d1fbb7fe14",
6
6
  "sourceDirty": false,
7
- "contentHash": "c2edf1d31c61e83fa7996dca770a5e9ef87a5e67ce5fd55ccd4922a6e6bfe450",
8
- "catalogSha256": "4b911bc129ea5a13070e2fcfac3a2f8d61087beb2758d2ae50b46e99180bba18",
7
+ "contentHash": "f029a01c0366f98240ca9e0367fef4805cf0d472ca0bb80f5f7d15e84d22497e",
8
+ "catalogSha256": "53c62b06f8479ac04100829a85f9fc4034fc894c92a66c0f7101470c43d89e8a",
9
9
  "skillFiles": {
10
10
  "references/component-guide.md": "612948840948e65f250998231eaa16fc41e8e27b9c03b19af32571422ca8185a",
11
11
  "references/docs-slug-map.md": "440ce5cf137fd22eabfcc5b51c3f55b85174aa643773ef0cedd5df542e77bbc2",
12
- "references/imports-and-setup.md": "9a404ad7243f0fa734d34c5fd0106287ededf36bbc1693812917ce9cb9780e40",
12
+ "references/imports-and-setup.md": "51936c71ddd17b13f89bc034745fe995c15a3f9a4da3d91e56cc628f998ec2cf",
13
13
  "references/theme-and-dark-mode.md": "2eccae4930ea993e7088eee03a4b4a0f1c839033079db5f21f8c60e0fe8168d1",
14
- "SKILL.md": "512ecee9c5208436cda70c56cd691354ab83e2d85115c4bc6f3c1e0658e458ba"
14
+ "SKILL.md": "59598c10f0a3fc3c7ae77baa0754c84bc032501c715f59afe323f3819fc67529"
15
15
  }
16
16
  }
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.1",
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/",
@@ -9,19 +9,22 @@ user-invocable: true
9
9
 
10
10
  Use `/fine-design` for component pages, fixes, and reviews. This folder guides AI; generated code must run without resolving skill files.
11
11
 
12
+ Run `npx -y @finedesign/cli doctor --format json` in the target project and read its `bundledSkillPath` when available. Use `npx fine-design` if the project already has the CLI installed. The public CLI is separate from the private `@fx-ui/fine-design` component package; a missing local command or private package does not prove the CLI is unavailable. Report the actual command and error if it fails.
13
+
12
14
  ## Workflow
13
15
 
14
16
  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
17
  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
18
  3. Query only the components needed at the exact target version. Prefer connected Fine Design MCP tools when matching-version data is available, or use the local CLI with `--format json`. Start with `info <component>` or `doc <component> --toc`. Fetch `example <component> <id>` source only when needed. Use `search` for unknown component names and `token` for theming. Check the installed CLI's help for supported commands. If the version is unknown or unsupported, consult matching local declarations/docs or verify browser exports and behavior. Resolve website pages through [docs-slug-map.md](references/docs-slug-map.md).
17
19
  4. Use the relevant sections of [component-guide.md](references/component-guide.md) for component selection and API traps. Consult other references only for the conditions below.
18
- 5. Run the existing build/type check (plus `fine-design lint <file>` when available) and verify the affected interaction with local test data. Report verified and unverified behavior. Reviews remain read-only.
20
+ 5. Run the existing build/type check (plus `fine-design lint <file>` when available) and verify the affected interaction with local test data. Report official lint, independent browser checks, and target preview checks separately, including unverified steps. Reviews remain read-only.
19
21
 
20
22
  ## Core Contracts
21
23
 
22
24
  - Use target-version public APIs and package-root imports from `@fx-ui/fine-design`; deep imports require an explicit request. Standalone HTML uses the public UMD exports.
23
25
  - Match the chosen component's schema, exports, and events. Keep filters, rows, and forms in the same stored value domain, and connect confirmations to actual mutations.
24
26
  - Runnable single-file output includes its styles/runtime setup and has no missing local helpers, assets, or CSS modules.
27
+ - If the requested Fine Design runtime is unavailable, report the failed command and cause without guessing. A native HTML substitute is not a Fine Design component implementation; label it as an alternative and do not claim official lint passed. If real components are mandatory, stop and report the blocker instead of substituting them.
25
28
 
26
29
  ## Read Only When Needed
27
30
 
@@ -12,7 +12,7 @@
12
12
 
13
13
  ## Component Installation And Registry
14
14
 
15
- The public `@finedesign/cli` package does not require company-registry credentials. Installing the component library `@fx-ui/fine-design` is separate. CLI documentation queries can use an explicit supported `--fd-version` without installing the component library.
15
+ The public `@finedesign/cli` package does not require company-registry credentials. Run `npx -y @finedesign/cli doctor --format json`; installing the component library `@fx-ui/fine-design` is separate. CLI documentation queries can use an explicit supported `--fd-version` without installing the component library. A missing local executable or a failed private-package lookup does not establish that the public CLI is unavailable. Report the actual command, exit code and error; distinguish registry, authentication and network failures without guessing.
16
16
 
17
17
  If component installation fails, inspect the effective configuration from the consuming project:
18
18
 
@@ -49,7 +49,7 @@ Use browser/CDN mode for standalone pages, embedded pages and previews without a
49
49
 
50
50
  ### Select Resources
51
51
 
52
- With CLI `0.2.0` or newer, use `fine-design runtime list --format json` and `fine-design runtime --fd-version <exact-version> --format json` (MCP: `list_browser_runtimes` / `get_browser_runtime`). Use `fine-design runtime --fd-version <exact-version> --format html > demo.html` for a runnable standalone example (add `--runtime-url` for an explicitly selected preview). Only the currently hosted version is available; offline documentation may include more versions. An unavailable version is an error, not a reason to change the requested version.
52
+ Run `npx -y @finedesign/cli runtime list --format json` first and check its exit code. Use a version from its `versions` result with `npx -y @finedesign/cli runtime --fd-version <exact-version> --format html > demo.html` for a standalone starting page, or `--format json` for resources (MCP: `list_browser_runtimes` / `get_browser_runtime`). Use `--runtime-url` only for an explicitly selected preview. Only the currently hosted version is available; offline documentation may include more versions. An unavailable version is an error, not a reason to change the requested version. If discovery fails, report the actual error instead of guessing asset URLs or repeatedly probing unrelated packages.
53
53
 
54
54
  1. Read the public [runtime manifest](https://fine-design-runtime.pages.dev/manifest.json). In this repository it is generated under `tools/fine-design/public/assets/react/fine-design-runtime/`. The manifest directly contains `version` and `resources`; there is no discovery pointer or historical version index.
55
55
  2. Resolve resource `path` relative to that manifest; `url` is used exactly. Hosted paths include the precise package version, such as `fine-design/1.25.0/fine-design.min.js`. There is no hash directory or releaseId. Resource SHA-256 and SRI still verify the exact bytes.
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,10 @@ 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 Update managed files or overwrite examples (init and add)
37
+ --dry-run Preview changes without writing (init and add)
32
38
  --runtime-url <url> Runtime hosting base URL (runtime command only)
33
39
  --format <text|json|markdown|html> Output format (markdown: doc/info/token; html: runtime)
34
40
  --section <heading> Doc section heading (exact or case-insensitive)
@@ -68,13 +74,21 @@ function runDoctor(values) {
68
74
  throw error;
69
75
  }
70
76
  }
77
+ const catalog = versionStatus === 'supported' ? loadCatalog(detectedVersion) : null;
71
78
  return {
72
79
  toolVersion: pkg.version,
73
80
  nodeVersion: process.version,
74
81
  projectDir,
75
82
  detectedVersion,
83
+ versionSource: detectedVersion === null ? null : values['fd-version'] !== undefined ? 'explicit' : 'project',
76
84
  versionStatus,
77
85
  availableVersions,
86
+ catalogSource: catalog ? {
87
+ sourceKind: catalog.sourceKind,
88
+ sourceRevision: catalog.sourceRevision,
89
+ sourceDirty: catalog.sourceDirty,
90
+ contentHash: catalog.contentHash
91
+ } : null,
78
92
  bundledSkillVersion: index.skillVersion,
79
93
  bundledSkillPath,
80
94
  bundledSkillAvailable,
@@ -82,6 +96,209 @@ function runDoctor(values) {
82
96
  };
83
97
  }
84
98
 
99
+ function runInit(values) {
100
+ const projectDir = path.resolve(values.project || process.cwd());
101
+ if (!fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) {
102
+ throw new ToolError('INVALID_ARGUMENT', `Project directory does not exist: ${projectDir}`, 2);
103
+ }
104
+ const agent = (values.agent || 'all').toLowerCase();
105
+ const validAgents = ['cursor', 'claude', 'codex', 'all'];
106
+ if (!validAgents.includes(agent)) {
107
+ throw new ToolError('INVALID_ARGUMENT', `Invalid agent "${values.agent}". Allowed: ${validAgents.join(', ')}`, 2);
108
+ }
109
+
110
+ const bundledSkillDir = fileURLToPath(new URL('../skills/fine-design', import.meta.url));
111
+ const created = [];
112
+ const updated = [];
113
+ const skipped = [];
114
+ const warnings = [];
115
+
116
+ const agentInstructions = `# Fine Design Rules
117
+
118
+ 开发或修改 Fine Design 页面时,在目标项目目录运行 CLI。项目已安装 CLI 时用 \`npx fine-design\`,否则用 \`npx -y @finedesign/cli\`。
119
+
120
+ 1. 运行 \`doctor --format json\` 并读取 \`bundledSkillPath\` 指向的 Skill。先确定交付形式。接入现有 React 工程时沿用项目组件版本、壳层和同类页面。
121
+ 2. 交付独立 HTML 或无构建预览时,先单独运行 \`runtime list --format json\`,根据退出码判断清单是否可用。用 \`versions\` 返回的版本解析 UMD 资源,再查组件 API。
122
+ 3. 按目标版本用 \`info\` 查组件 API。\`list --format json\` 从 \`components\` 数组读取组件,\`example <组件>\` 先列示例 ID,按需再读源码。
123
+ 4. 对改动文件运行 \`lint\` 并执行项目已有检查。分别记录工程检查、UMD 清单解析和目标预览中的关键交互结果,标明未验证项。
124
+ 5. CLI 与私有组件包是独立的;本地命令缺失或私有包查询失败不能证明公开 CLI 不存在。失败时记录实际命令、退出码和错误。真实组件不可用时,原生页面只能标为替代实现,不能声称通过官方 lint;若必须使用真实组件则报告阻碍。
125
+ `;
126
+
127
+ const cursorMdcContent = `---
128
+ description: Fine Design component library guidelines, API traps and verification rules
129
+ globs: **/*.{tsx,jsx,ts,js,html}
130
+ alwaysApply: false
131
+ ---
132
+
133
+ ${agentInstructions}`;
134
+
135
+ const startMarker = '<!-- fine-design:start -->';
136
+ const endMarker = '<!-- fine-design:end -->';
137
+ const managedInstructions = `${startMarker}\n${agentInstructions.trimEnd()}\n${endMarker}`;
138
+ function write(relative, content, overwrite = false) {
139
+ const filename = path.join(projectDir, relative);
140
+ const exists = fs.existsSync(filename);
141
+ if (exists && !overwrite) {
142
+ skipped.push(relative);
143
+ return;
144
+ }
145
+ (exists ? updated : created).push(relative);
146
+ if (!values['dry-run']) {
147
+ fs.mkdirSync(path.dirname(filename), { recursive: true });
148
+ fs.writeFileSync(filename, content);
149
+ }
150
+ }
151
+ function writeInstructions(relative) {
152
+ const filename = path.join(projectDir, relative);
153
+ if (!fs.existsSync(filename)) return write(relative, `${managedInstructions}\n`);
154
+ const existing = fs.readFileSync(filename, 'utf8');
155
+ const start = existing.indexOf(startMarker);
156
+ const end = existing.indexOf(endMarker);
157
+ if (start !== -1 || end !== -1) {
158
+ if (start === -1 || end < start || existing.indexOf(startMarker, start + startMarker.length) !== -1 || existing.indexOf(endMarker, end + endMarker.length) !== -1) {
159
+ skipped.push(relative);
160
+ warnings.push(`${relative}: invalid Fine Design markers; update manually.`);
161
+ } else if (values.force) {
162
+ write(relative, existing.slice(0, start) + managedInstructions + existing.slice(end + endMarker.length), true);
163
+ } else skipped.push(relative);
164
+ } else if (existing.includes('fine-design') || existing.includes('@finedesign/cli')) {
165
+ skipped.push(relative);
166
+ warnings.push(`${relative}: existing Fine Design instructions have no markers; update manually.`);
167
+ } else {
168
+ write(relative, `${existing}\n\n${managedInstructions}\n`, true);
169
+ }
170
+ }
171
+ function writeSkill(relative) {
172
+ const target = path.join(projectDir, relative);
173
+ if (fs.existsSync(target) && !values.force) {
174
+ skipped.push(`${relative}/`);
175
+ return;
176
+ }
177
+ function copyFiles(source, destination) {
178
+ for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
179
+ const src = path.join(source, entry.name);
180
+ const dest = path.join(destination, entry.name);
181
+ if (entry.isDirectory()) copyFiles(src, dest);
182
+ else if (entry.isFile()) write(dest, fs.readFileSync(src), values.force);
183
+ }
184
+ }
185
+ if (fs.existsSync(bundledSkillDir)) copyFiles(bundledSkillDir, relative);
186
+ }
187
+
188
+ if (agent === 'cursor' || agent === 'all') {
189
+ writeInstructions('.cursorrules');
190
+ write('.cursor/rules/fine-design.mdc', cursorMdcContent, values.force);
191
+ }
192
+
193
+ if (agent === 'claude' || agent === 'all') {
194
+ writeSkill('.claude/skills/fine-design');
195
+ writeInstructions('CLAUDE.md');
196
+ }
197
+
198
+ if (agent === 'codex' || agent === 'all') {
199
+ writeSkill('.agents/skills/fine-design');
200
+ writeInstructions('AGENTS.md');
201
+ }
202
+
203
+ return {
204
+ projectDir,
205
+ agent,
206
+ created: [...new Set(created)],
207
+ updated: [...new Set(updated)],
208
+ skipped,
209
+ warnings,
210
+ dryRun: Boolean(values['dry-run'])
211
+ };
212
+ }
213
+
214
+ function runAdd(componentArg, exampleArg, values) {
215
+ if (!componentArg) {
216
+ throw new ToolError('INVALID_ARGUMENT', 'Usage: fine-design add <component> [id] [options]', 2);
217
+ }
218
+ const version = resolveVersion(values['fd-version'], values.project);
219
+ const catalog = loadCatalog(version);
220
+ const resolvedComp = resolveComponentOrThrow(catalog, componentArg);
221
+
222
+ let exampleId = exampleArg;
223
+ if (!exampleId) {
224
+ if (resolvedComp.examples?.some((ex) => ex.id === 'basic')) {
225
+ exampleId = 'basic';
226
+ } else if (resolvedComp.examples?.length > 0) {
227
+ exampleId = resolvedComp.examples[0].id;
228
+ } else {
229
+ throw new ToolError('EXAMPLE_NOT_FOUND', `Component "${resolvedComp.title || resolvedComp.id}" has no examples available.`, 4);
230
+ }
231
+ }
232
+
233
+ const example = queryCatalog(catalog, 'get_component_example', {
234
+ version,
235
+ component: resolvedComp.id,
236
+ exampleId,
237
+ includeAssets: true
238
+ });
239
+ if (!example?.files?.length) {
240
+ throw new ToolError('EXAMPLE_NOT_FOUND', `Example "${exampleId}" not found for ${resolvedComp.id}.`, 4);
241
+ }
242
+
243
+ const projectDir = path.resolve(values.project || process.cwd());
244
+ let targetDir;
245
+ if (values.output) {
246
+ targetDir = path.resolve(projectDir, values.output);
247
+ } else {
248
+ const hasSrc = fs.existsSync(path.join(projectDir, 'src'));
249
+ targetDir = hasSrc
250
+ ? path.join(projectDir, 'src', 'components', resolvedComp.id)
251
+ : path.join(projectDir, 'components', resolvedComp.id);
252
+ }
253
+ let sourceDir = path.posix.dirname(example.entry);
254
+ while (sourceDir !== '.' && example.files.some((file) => !file.path.startsWith(`${sourceDir}/`))) {
255
+ sourceDir = path.posix.dirname(sourceDir);
256
+ }
257
+ const prefix = sourceDir === '.' ? '' : `${sourceDir}/`;
258
+ const files = example.files.map((file) => ({ file, destPath: path.join(targetDir, file.path.slice(prefix.length)) }));
259
+ const writtenFiles = [];
260
+ const created = [];
261
+ const updated = [];
262
+ const conflicts = [];
263
+
264
+ for (const { destPath } of files) {
265
+ const relative = path.relative(projectDir, destPath);
266
+ if (!fs.existsSync(destPath)) created.push(relative);
267
+ else if (values.force) updated.push(relative);
268
+ else conflicts.push(relative);
269
+ }
270
+ if (conflicts.length && !values['dry-run']) {
271
+ throw new ToolError('FILE_EXISTS', `File already exists: ${conflicts[0]}. Use --force to overwrite.`, 1);
272
+ }
273
+ for (const { file, destPath } of values['dry-run'] ? [] : files) {
274
+ fs.mkdirSync(path.dirname(destPath), { recursive: true });
275
+ if (file.encoding === 'base64') {
276
+ fs.writeFileSync(destPath, Buffer.from(file.content, 'base64'));
277
+ } else {
278
+ fs.writeFileSync(destPath, file.content, 'utf8');
279
+ }
280
+ writtenFiles.push(path.relative(projectDir, destPath));
281
+ }
282
+
283
+ const requiredDependencies = (example.dependencies || []).filter(
284
+ (dep) => !['react', 'react-dom', '@fx-ui/fine-design'].includes(dep)
285
+ );
286
+
287
+ return {
288
+ component: resolvedComp.id,
289
+ exampleId,
290
+ version,
291
+ targetDir: path.relative(projectDir, targetDir) || '.',
292
+ writtenFiles,
293
+ created,
294
+ updated,
295
+ conflicts,
296
+ dryRun: Boolean(values['dry-run']),
297
+ dependencies: example.dependencies || [],
298
+ requiredDependencies
299
+ };
300
+ }
301
+
85
302
  export async function main(argv) {
86
303
  let format = 'text';
87
304
  try {
@@ -89,7 +306,8 @@ export async function main(argv) {
89
306
  help: { type: 'boolean' }, version: { type: 'boolean' }, 'fd-version': { type: 'string' }, project: { type: 'string' },
90
307
  format: { type: 'string' }, section: { type: 'string' }, toc: { type: 'boolean' }, summary: { type: 'boolean' },
91
308
  offset: { type: 'string' }, limit: { type: 'string' }, 'include-assets': { type: 'boolean' },
92
- 'runtime-url': { type: 'string' }, component: { type: 'string' }
309
+ 'runtime-url': { type: 'string' }, component: { type: 'string' },
310
+ agent: { type: 'string' }, output: { type: 'string' }, force: { type: 'boolean' }, 'dry-run': { type: 'boolean' }
93
311
  }});
94
312
  format = values.format || 'text';
95
313
  if (!['text', 'json', 'markdown', 'html'].includes(format)) throw new ToolError('INVALID_ARGUMENT', 'Unknown output format.', 2);
@@ -100,6 +318,10 @@ export async function main(argv) {
100
318
  const summaryFlag = Boolean(values.toc || values.summary);
101
319
  if (command !== 'runtime' && (values['runtime-url'] !== undefined)) throw new ToolError('INVALID_ARGUMENT', 'Runtime options are only supported for runtime.', 2);
102
320
  if (command !== 'diff' && values.component !== undefined) throw new ToolError('INVALID_ARGUMENT', '--component is only supported for diff.', 2);
321
+ if (command !== 'init' && values.agent !== undefined) throw new ToolError('INVALID_ARGUMENT', '--agent is only supported for init.', 2);
322
+ if (command !== 'add' && values.output !== undefined) throw new ToolError('INVALID_ARGUMENT', '--output is only supported for add.', 2);
323
+ if (!['init', 'add'].includes(command) && values.force !== undefined) throw new ToolError('INVALID_ARGUMENT', '--force is only supported for init and add.', 2);
324
+ if (!['init', 'add'].includes(command) && values['dry-run'] !== undefined) throw new ToolError('INVALID_ARGUMENT', '--dry-run is only supported for init and add.', 2);
103
325
  if (format === 'markdown' && !['doc', 'info', 'token'].includes(command)) {
104
326
  throw new ToolError('INVALID_ARGUMENT', 'Markdown output format is only supported for the doc, info and token commands.', 2);
105
327
  }
@@ -122,8 +344,9 @@ export async function main(argv) {
122
344
  const lines = [
123
345
  `CLI version: ${report.toolVersion} (Node ${report.nodeVersion})`,
124
346
  `Project directory: ${report.projectDir}`,
125
- `Detected Fine Design: ${report.detectedVersion ?? 'none'} (${report.versionStatus})`,
347
+ `Fine Design version: ${report.detectedVersion ?? 'none'} (${report.versionStatus}${report.versionSource ? `, ${report.versionSource}` : ''})`,
126
348
  `Bundled catalogs: ${report.availableVersions.join(', ')}`,
349
+ ...(report.catalogSource ? [`Catalog source: ${report.catalogSource.sourceKind} ${report.catalogSource.sourceRevision}${report.catalogSource.sourceDirty ? ' (dirty)' : ''}`] : []),
127
350
  `Bundled Skill (${report.bundledSkillVersion}): ${report.bundledSkillPath}`
128
351
  ];
129
352
  if (report.suggestions?.length) lines.push(`Suggestions:\n${report.suggestions.map((item) => ` - ${item}`).join('\n')}`);
@@ -131,6 +354,50 @@ export async function main(argv) {
131
354
  }
132
355
  return;
133
356
  }
357
+ if (command === 'init') {
358
+ 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)) {
359
+ throw new ToolError('INVALID_ARGUMENT', 'Usage: fine-design init [--agent <cursor|claude|codex|all>] [--project <dir>] [--force] [--dry-run] [--format text|json]', 2);
360
+ }
361
+ const report = runInit(values);
362
+ if (format === 'json') {
363
+ console.log(JSON.stringify(report));
364
+ } else {
365
+ const lines = [
366
+ `${report.dryRun ? 'Preview' : 'Initialized'} Fine Design agent configuration (${report.agent}) in ${report.projectDir}:`,
367
+ ' Created files:',
368
+ ...(report.created.length ? report.created.map((f) => ` - ${f}`) : [' - none']),
369
+ ' Updated files:',
370
+ ...(report.updated.length ? report.updated.map((f) => ` - ${f}`) : [' - none']),
371
+ ' Skipped files:',
372
+ ...(report.skipped.length ? report.skipped.map((f) => ` - ${f}`) : [' - none']),
373
+ ...report.warnings.map((warning) => ` Warning: ${warning}`)
374
+ ];
375
+ console.log(lines.join('\n'));
376
+ }
377
+ return;
378
+ }
379
+ if (command === 'add') {
380
+ 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)) {
381
+ throw new ToolError('INVALID_ARGUMENT', 'Usage: fine-design add <component> [id] [--output <dir>] [--force] [--dry-run] [--fd-version <version>] [--format text|json]', 2);
382
+ }
383
+ const report = runAdd(args[0], args[1], values);
384
+ if (format === 'json') {
385
+ console.log(JSON.stringify(report));
386
+ } else {
387
+ const lines = [
388
+ `${report.dryRun ? 'Preview' : 'Added'} ${report.component} (${report.exampleId}) to ${report.targetDir}:`,
389
+ ...report.created.map((f) => ` Create: ${f}`),
390
+ ...report.updated.map((f) => ` Overwrite: ${f}`),
391
+ ...report.conflicts.map((f) => ` Conflict: ${f}`),
392
+ ...(report.conflicts.length ? [' No files will be written unless conflicts are resolved or --force is used.'] : [])
393
+ ];
394
+ if (report.requiredDependencies.length) {
395
+ lines.push('', 'Required dependencies:', ` npm install ${report.requiredDependencies.join(' ')}`);
396
+ }
397
+ console.log(lines.join('\n'));
398
+ }
399
+ return;
400
+ }
134
401
  if (command === 'list') {
135
402
  if (values.version || args.length > 0 || values.section !== undefined || summaryFlag || values.offset !== undefined || values.limit !== undefined || values['include-assets'] !== undefined) {
136
403
  throw new ToolError('INVALID_ARGUMENT', 'Invalid options for list. Use --help for usage.', 2);
@@ -263,7 +530,7 @@ export async function main(argv) {
263
530
  });
264
531
  return [` - ${exports.join('/')} (${id})`, ...details].join('\n');
265
532
  }),
266
- ...(result.migrations.length ? ['Recommended migrations:', ...result.migrations.map((m) => ` - ${m.legacy} -> ${m.recommended}: ${m.note}`)] : [])
533
+ ...(result.migrations.length ? ['Recommended migrations (general guidance, not specific to these versions):', ...result.migrations.map((m) => ` - ${m.legacy} -> ${m.recommended}: ${m.note}`)] : [])
267
534
  ].join('\n'));
268
535
  }
269
536
  return;
@@ -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) =>
@@ -484,6 +484,7 @@ export function diffCatalogs(fromCatalog, toCatalog, component) {
484
484
  addedComponents,
485
485
  removedComponents,
486
486
  updatedComponents,
487
+ migrationScope: 'general',
487
488
  migrations: [
488
489
  { components: ['table', 'data-table', 'next-table'], legacy: 'Table / DataTable', recommended: 'NextTable', note: 'Use <NextTable> with declarative <NextTable.Column>, <NextTable.HeaderCell>, and <NextTable.Cell dataKey="..."> children.' },
489
490
  { components: ['cascader', 'm-cascader'], legacy: 'Cascader', recommended: 'MCascader', note: 'Legacy Cascader has no online docs page; prefer MCascader for new pages.' },
@@ -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
+ }