@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.
- package/CHANGELOG.md +20 -0
- package/README.md +68 -155
- package/data/1.24.9/catalog.json +1 -1
- package/data/1.24.9/manifest.json +2 -2
- package/data/1.25.0/catalog.json +1 -1
- package/data/1.25.0/manifest.json +7 -8
- package/package.json +2 -1
- package/skills/fine-design/SKILL.md +2 -2
- package/skills/fine-design/references/component-guide.md +1 -1
- package/skills/fine-design/references/imports-and-setup.md +8 -8
- package/src/cli.mjs +165 -10
- package/src/core/catalog.mjs +300 -19
- package/src/core/contracts.mjs +8 -1
- package/src/core/html.cjs +152 -0
- package/src/core/lint.mjs +302 -0
- package/src/core/runtime.mjs +62 -0
- package/src/mcp.mjs +7 -3
- package/skills/fine-design/references/browser-runtime-legacy.json +0 -71
|
@@ -2,16 +2,15 @@
|
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"version": "1.25.0",
|
|
4
4
|
"sourceKind": "repository-snapshot",
|
|
5
|
-
"sourceRevision": "
|
|
6
|
-
"sourceDirty":
|
|
7
|
-
"contentHash": "
|
|
8
|
-
"catalogSha256": "
|
|
5
|
+
"sourceRevision": "39a9955314410af35f1b6096076dcbdf2cc45e9a",
|
|
6
|
+
"sourceDirty": false,
|
|
7
|
+
"contentHash": "30d2e3ea566ad4fd5eed2f53b6cae59de2030db49d2f90eb81b20b3d85e66e4e",
|
|
8
|
+
"catalogSha256": "67db385543fa667b5a81b70f4fe35a01a7d8b2bdc8c7a559ced808babd88c7b0",
|
|
9
9
|
"skillFiles": {
|
|
10
|
-
"references/
|
|
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": "
|
|
12
|
+
"references/imports-and-setup.md": "5bd9024770a77ddeb0f4dce94ebd103f327c2513b52f165e371da9c4dbdcd98f",
|
|
14
13
|
"references/theme-and-dark-mode.md": "2eccae4930ea993e7088eee03a4b4a0f1c839033079db5f21f8c60e0fe8168d1",
|
|
15
|
-
"SKILL.md": "
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
--
|
|
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.
|
|
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 (
|
|
86
|
-
|
|
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
|
-
? {
|
|
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'}`
|