@finedesign/cli 0.2.0-rc.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,16 +2,15 @@
2
2
  "schemaVersion": 1,
3
3
  "version": "1.25.0",
4
4
  "sourceKind": "repository-snapshot",
5
- "sourceRevision": "ad20d2f3533e58956e1d337759292595b2448502",
6
- "sourceDirty": true,
7
- "contentHash": "29b35ec33234226619339aa7bf90b203aa00c40dc05bdffd31c780a1c97eeaab",
8
- "catalogSha256": "df80bea0879f13db73c7fecc12868fda494cccecb19ec13aaa734133f6ceaf48",
5
+ "sourceRevision": "39a9955314410af35f1b6096076dcbdf2cc45e9a",
6
+ "sourceDirty": false,
7
+ "contentHash": "30d2e3ea566ad4fd5eed2f53b6cae59de2030db49d2f90eb81b20b3d85e66e4e",
8
+ "catalogSha256": "67db385543fa667b5a81b70f4fe35a01a7d8b2bdc8c7a559ced808babd88c7b0",
9
9
  "skillFiles": {
10
- "references/browser-runtime-legacy.json": "7e9ab5da90c0797813cd206f30575f53f0305e3e5817af0a46f03d193615b543",
11
- "references/component-guide.md": "fd18509f7b304bb3073736c514c1b43d41284499a5616cb4fcba95bf849094cb",
10
+ "references/component-guide.md": "612948840948e65f250998231eaa16fc41e8e27b9c03b19af32571422ca8185a",
12
11
  "references/docs-slug-map.md": "440ce5cf137fd22eabfcc5b51c3f55b85174aa643773ef0cedd5df542e77bbc2",
13
- "references/imports-and-setup.md": "2f6302a058e2231c61aed20b9d35df8425dbf79cde0c8c970dc5fd48befb24ad",
12
+ "references/imports-and-setup.md": "5bd9024770a77ddeb0f4dce94ebd103f327c2513b52f165e371da9c4dbdcd98f",
14
13
  "references/theme-and-dark-mode.md": "2eccae4930ea993e7088eee03a4b4a0f1c839033079db5f21f8c60e0fe8168d1",
15
- "SKILL.md": "035ce9e23c7c1f78addcb08198f02b3b482c61d8a9b3b939e8b5f12511058750"
14
+ "SKILL.md": "b8ef63aa9aef7cf6cb8f83556b6c09760fc4707f0466d25eb1fac8f2fed6b2a9"
16
15
  }
17
16
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@finedesign/cli",
3
- "version": "0.2.0-rc.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` |
@@ -47,16 +47,16 @@ Use browser/CDN mode for standalone pages, embedded pages and previews without a
47
47
 
48
48
  ### Select Resources
49
49
 
50
- 1. Read the public [runtime manifest](https://docs.fanruan.design/assets/react/fine-design-runtime/manifest.json). In this repository, the local equivalent is generated under `public/assets/react/fine-design-runtime/`. If it contains a `manifest` field, follow that path relative to the discovery URL to read the immutable release manifest.
51
- 2. Resolve each resource's `path` relative to that release manifest; resources with `url` use that exact URL. Read package versions from resource metadata. Do not infer them from the CLI version, a broad peer range or today's website.
52
- 3. If the manifest has not been deployed or cannot be retrieved, use the [legacy resource snapshot](browser-runtime-legacy.json). Its Fine Design version is explicitly unknown: verify required exports and interactions, and do not claim it matches an exact npm version. If exact version matching is required, obtain a matching release instead of guessing. Report inaccessible or changed resources; do not silently switch runtime versions.
53
- 4. Resolve resources once when generating the page and write their exact URLs and `integrity` values into the output. Keep React and ReactDOM as the paired resources in that manifest; do not replace them with `latest`. Newer React releases may not provide UMD files.
50
+ 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.
54
51
 
55
- Runtime hosting and offline CLI catalogs are released separately. A manifest does not make its component version available in the installed CLI. Query that exact version only if supported; otherwise inspect matching public exports and examples. Do not switch discovery to a planned hosting domain until its manifest and cross-origin resources have passed verification.
52
+ 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.
53
+ 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.
54
+ 3. The host retains only the current release files. Old URLs may disappear on upgrade; save matching resources yourself for long-lived standalone pages. Do not claim historical runtime availability from the CLI's offline catalog.
55
+ 4. If the manifest cannot be retrieved, report the failure and use an explicitly selected verified host or previously saved matching resources. The old unversioned website resources have been removed; do not fall back to them or substitute another component version.
56
56
 
57
- Load `fineDesignCss`, then the scripts `react`, `reactDOM`, `fineDesign` in that order. Use `crossorigin="anonymous"` with integrity-checked cross-origin release resources; the host must permit CORS. The legacy snapshot marks resources without CORS as `cors: false`: verify their downloaded SHA-256 when generating the page and use classic script/style loading for those files, without integrity/crossorigin attributes. Do not drop integrity from a selected immutable release to hide an error. Avoid `async` scripts that break dependency order. Reuse existing React globals only when they match the selected runtime; do not load a second React over an existing app. Load optional chart resources only for chart requests.
57
+ Load `fineDesignCss`, then `react`, `reactDOM`, `fineDesign`. Pin exact URLs and integrity in generated HTML and use `crossorigin="anonymous"`; the host must provide CORS. Do not drop SRI from a selected versioned runtime to hide an error. Avoid async scripts and conflicting second React instances. If an embedding host lacks compatible React globals, use a separate document/iframe.
58
58
 
59
- If an embedding host cannot supply compatible React globals, use a separate HTML document/iframe instead of injecting a conflicting runtime into that app.
59
+ Use `--runtime-url <verified-base-url>` only for a clearly selected host. The default public host is `https://fine-design-runtime.pages.dev/`, verified after production deployment; local testing alone does not prove a host is live. Optional chart resources are loaded only for chart requests.
60
60
 
61
61
  ### Mount And Verify
62
62
 
@@ -72,4 +72,4 @@ ReactDOM.createRoot(document.getElementById('root')).render(
72
72
  );
73
73
  ```
74
74
 
75
- The repository's `npm run build:public-assets` builds the component runtime before generating manifests, immutable releases and `index.html`, a runnable browser example. Its mutable discovery manifest is for resource selection; generated business pages should reference an immutable release. Deploy the full output including historical release directories, with CORS enabled for public scripts/styles. Do not relabel an old build using the current package version.
75
+ The repository's `npm run build:public-assets` builds the production component before generating the single latest manifest and browser example under tools. Deploy only the generated runtime directory with CORS; do not relabel a stale component build. Full local release checks are in `tools/fine-design/README.md`.
package/src/cli.mjs CHANGED
@@ -2,27 +2,38 @@ 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
+ import { listRuntimes, resolveRuntime } from './core/runtime.mjs';
10
+ import { lintFiles } from './core/lint.mjs';
11
+ import html from './core/html.cjs';
9
12
 
10
13
  const help = `Usage: fine-design <command> [arguments] [options]
11
14
 
12
15
  Commands:
16
+ list List all components in the target version
13
17
  search [query] Search or browse components
18
+ info <component> Show component overview and API/props sections
14
19
  doc <component> Read component documentation
20
+ token [component] [query] Inspect component or global Design Tokens
15
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
16
24
  doctor Inspect detected version, available catalogs and bundled Skill
25
+ runtime [list] Resolve a versioned online UMD runtime or list published versions
17
26
  mcp Start the stdio MCP server
18
27
 
19
28
  Options:
20
29
  --fd-version <version> Exact Fine Design component version
21
30
  --project <directory> Project used to detect the installed version
22
- --format <text|json|markdown> Output format (default: text; markdown is doc-only)
31
+ --runtime-url <url> Runtime hosting base URL (runtime command only)
32
+ --format <text|json|markdown|html> Output format (markdown: doc/info/token; html: runtime)
23
33
  --section <heading> Doc section heading (exact or case-insensitive)
24
34
  --toc, --summary Show only doc metadata, section headings and example IDs
25
35
  --offset <number> Search pagination offset
36
+ --limit <number> Search page size (1..200, default 20)
26
37
  --include-assets Include binary base64 and oversized JSON fixture content
27
38
  --help Show help
28
39
  --version Show tool version`;
@@ -48,7 +59,7 @@ function runDoctor(values) {
48
59
  }
49
60
  } catch (error) {
50
61
  if (error instanceof ToolError && error.code === 'VERSION_NOT_DETECTED') {
51
- suggestions = error.details?.suggestions || [];
62
+ suggestions = error.context?.suggestions || [];
52
63
  } else {
53
64
  throw error;
54
65
  }
@@ -73,20 +84,30 @@ export async function main(argv) {
73
84
  const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, strict: true, options: {
74
85
  help: { type: 'boolean' }, version: { type: 'boolean' }, 'fd-version': { type: 'string' }, project: { type: 'string' },
75
86
  format: { type: 'string' }, section: { type: 'string' }, toc: { type: 'boolean' }, summary: { type: 'boolean' },
76
- offset: { type: 'string' }, 'include-assets': { type: 'boolean' }
87
+ offset: { type: 'string' }, limit: { type: 'string' }, 'include-assets': { type: 'boolean' },
88
+ 'runtime-url': { type: 'string' }
77
89
  }});
78
90
  format = values.format || 'text';
79
- if (!['text', 'json', 'markdown'].includes(format)) throw new ToolError('INVALID_ARGUMENT', 'Unknown output format.', 2);
91
+ if (!['text', 'json', 'markdown', 'html'].includes(format)) throw new ToolError('INVALID_ARGUMENT', 'Unknown output format.', 2);
80
92
  if (values.help || (!positionals.length && !values.version && !argv.length)) { console.log(help); return; }
81
93
  if (values.version && argv.length === 1) { console.log(JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version); return; }
82
94
  const [command, ...args] = positionals;
83
95
  if (command === 'mcp' && args.length === 0 && argv.length === 1) { await (await import('./mcp.mjs')).startMcp(); return; }
84
96
  const summaryFlag = Boolean(values.toc || values.summary);
85
- if (format === 'markdown' && command !== 'doc') {
86
- throw new ToolError('INVALID_ARGUMENT', 'Markdown output format is only supported for the doc command.', 2);
97
+ if (command !== 'runtime' && (values['runtime-url'] !== undefined)) throw new ToolError('INVALID_ARGUMENT', 'Runtime options are only supported for runtime.', 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);
100
+ }
101
+ if (format === 'html' && (command !== 'runtime' || args.length)) throw new ToolError('INVALID_ARGUMENT', 'HTML output format is only supported for runtime resolution.', 2);
102
+ if (command === 'runtime') {
103
+ const list = args.length === 1 && args[0] === 'list';
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);
105
+ const result = list ? await listRuntimes(values['runtime-url']) : await resolveRuntime({ version: resolveVersion(values['fd-version'], values.project), runtimeURL: values['runtime-url'] });
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}`);
107
+ return;
87
108
  }
88
109
  if (command === 'doctor') {
89
- 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) {
90
111
  throw new ToolError('INVALID_ARGUMENT', 'Invalid options for doctor. Use --help for usage.', 2);
91
112
  }
92
113
  const report = runDoctor(values);
@@ -105,6 +126,133 @@ export async function main(argv) {
105
126
  }
106
127
  return;
107
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
+ }
108
256
  const tools = { search: 'search_components', doc: 'get_component_doc', example: 'get_component_example' };
109
257
  if (
110
258
  !Object.hasOwn(tools, command) ||
@@ -115,17 +263,22 @@ export async function main(argv) {
115
263
  (values.section !== undefined && command !== 'doc') ||
116
264
  ((values.toc !== undefined || values.summary !== undefined) && command !== 'doc') ||
117
265
  (values.section !== undefined && summaryFlag) ||
118
- (values.offset !== undefined && command !== 'search') ||
266
+ ((values.offset !== undefined || values.limit !== undefined) && command !== 'search') ||
119
267
  (values['include-assets'] !== undefined && command !== 'example')
120
268
  ) {
121
269
  throw new ToolError('INVALID_ARGUMENT', 'Invalid command or arguments. Use --help for usage.', 2);
122
270
  }
123
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);
124
273
  const version = resolveVersion(values['fd-version'], values.project);
125
274
  const input = {
126
275
  version,
127
276
  ...(command === 'search'
128
- ? { 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
+ }
129
282
  : {
130
283
  component: args[0],
131
284
  ...(command === 'doc' && values.section !== undefined && { section: values.section }),
@@ -145,6 +298,7 @@ export async function main(argv) {
145
298
  `# ${result.title}${result.subtitle ? ` ${result.subtitle}` : ''} (\`${result.component}\`)`,
146
299
  result.description || '',
147
300
  `Exports: ${result.exports.map((name) => `\`${name}\``).join(', ')}`,
301
+ ...(result.aliases?.length ? [`Aliases: ${result.aliases.map((name) => `\`${name}\``).join(', ')}`] : []),
148
302
  `## Sections\n${result.sections.map((heading) => `- ${heading}`).join('\n') || '- none'}`,
149
303
  `## Examples\n${result.examples.map((item) => `- \`${item.id}\`: ${item.title}`).join('\n') || '- none'}`
150
304
  ].filter(Boolean).join('\n\n'));
@@ -152,6 +306,7 @@ export async function main(argv) {
152
306
  console.log([
153
307
  `${result.component} (${result.exports.join(', ')})${result.subtitle ? ` - ${result.subtitle}` : ''}`,
154
308
  ...(result.description ? [result.description] : []),
309
+ ...(result.aliases?.length ? [`Aliases: ${result.aliases.join(', ')}`] : []),
155
310
  `Docs available: ${result.docsAvailable}`,
156
311
  `Sections: ${result.sections.join(', ') || 'none'}`,
157
312
  `Examples: ${result.examples.map((item) => item.id).join(', ') || 'none'}`