@finedesign/cli 0.1.0 → 0.2.0-rc.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 +10 -0
- package/README.md +42 -30
- package/data/1.25.0/catalog.json +1 -0
- package/data/1.25.0/manifest.json +17 -0
- package/data/index.json +5 -1
- package/package.json +1 -1
- package/skills/fine-design/SKILL.md +3 -3
- package/skills/fine-design/references/browser-runtime-legacy.json +71 -0
- package/skills/fine-design/references/component-guide.md +1 -0
- package/skills/fine-design/references/docs-slug-map.md +12 -0
- package/skills/fine-design/references/imports-and-setup.md +19 -16
- package/skills/fine-design/references/theme-and-dark-mode.md +1 -0
- package/src/cli.mjs +137 -13
- package/src/core/catalog.mjs +63 -8
- package/src/core/contracts.mjs +12 -2
- package/src/core/data.mjs +7 -1
- package/src/core/version.mjs +11 -1
- package/src/mcp.mjs +3 -3
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"version": "1.25.0",
|
|
4
|
+
"sourceKind": "repository-snapshot",
|
|
5
|
+
"sourceRevision": "ad20d2f3533e58956e1d337759292595b2448502",
|
|
6
|
+
"sourceDirty": true,
|
|
7
|
+
"contentHash": "29b35ec33234226619339aa7bf90b203aa00c40dc05bdffd31c780a1c97eeaab",
|
|
8
|
+
"catalogSha256": "df80bea0879f13db73c7fecc12868fda494cccecb19ec13aaa734133f6ceaf48",
|
|
9
|
+
"skillFiles": {
|
|
10
|
+
"references/browser-runtime-legacy.json": "7e9ab5da90c0797813cd206f30575f53f0305e3e5817af0a46f03d193615b543",
|
|
11
|
+
"references/component-guide.md": "fd18509f7b304bb3073736c514c1b43d41284499a5616cb4fcba95bf849094cb",
|
|
12
|
+
"references/docs-slug-map.md": "440ce5cf137fd22eabfcc5b51c3f55b85174aa643773ef0cedd5df542e77bbc2",
|
|
13
|
+
"references/imports-and-setup.md": "2f6302a058e2231c61aed20b9d35df8425dbf79cde0c8c970dc5fd48befb24ad",
|
|
14
|
+
"references/theme-and-dark-mode.md": "2eccae4930ea993e7088eee03a4b4a0f1c839033079db5f21f8c60e0fe8168d1",
|
|
15
|
+
"SKILL.md": "035ce9e23c7c1f78addcb08198f02b3b482c61d8a9b3b939e8b5f12511058750"
|
|
16
|
+
}
|
|
17
|
+
}
|
package/data/index.json
CHANGED
package/package.json
CHANGED
|
@@ -11,9 +11,9 @@ Use `/fine-design` for component pages, fixes, and reviews. This folder guides A
|
|
|
11
11
|
|
|
12
12
|
## Workflow
|
|
13
13
|
|
|
14
|
-
1. Identify the deliverable:
|
|
15
|
-
2.
|
|
16
|
-
3. When available, prefer the connected Fine Design MCP tools; otherwise use the local `fine-design` CLI with `--format json` and the exact
|
|
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
|
+
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.
|
|
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
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.
|
|
19
19
|
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"sourceState": "legacy-unversioned",
|
|
4
|
+
"checkedOn": "2026-11-02",
|
|
5
|
+
"resources": {
|
|
6
|
+
"react": {
|
|
7
|
+
"package": "react",
|
|
8
|
+
"version": "18.3.1",
|
|
9
|
+
"type": "script",
|
|
10
|
+
"global": "React",
|
|
11
|
+
"url": "https://cdn.jsdelivr.net/npm/react@18.3.1/umd/react.production.min.js",
|
|
12
|
+
"cors": true,
|
|
13
|
+
"size": 10751,
|
|
14
|
+
"sha256": "d949f1c3687aedadcedac85261865f29b17cd273997e7f6b2bfc53b2f9d4c4dd",
|
|
15
|
+
"integrity": "sha256-2Unxw2h67a3O2shSYYZfKbF80nOZfn9rK/xTsvnUxN0="
|
|
16
|
+
},
|
|
17
|
+
"reactDOM": {
|
|
18
|
+
"package": "react-dom",
|
|
19
|
+
"version": "18.3.1",
|
|
20
|
+
"type": "script",
|
|
21
|
+
"global": "ReactDOM",
|
|
22
|
+
"url": "https://cdn.jsdelivr.net/npm/react-dom@18.3.1/umd/react-dom.production.min.js",
|
|
23
|
+
"cors": true,
|
|
24
|
+
"size": 131835,
|
|
25
|
+
"sha256": "35f4f974f4b2bcd44da73963347f8952e341f83909e4498227d4e26b98f66f0d",
|
|
26
|
+
"integrity": "sha256-NfT5dPSyvNRNpzljNH+JUuNB+DkJ5EmCJ9Tia5j2bw0="
|
|
27
|
+
},
|
|
28
|
+
"fineDesign": {
|
|
29
|
+
"package": "@fx-ui/fine-design",
|
|
30
|
+
"version": null,
|
|
31
|
+
"type": "script",
|
|
32
|
+
"global": "FineDesign",
|
|
33
|
+
"url": "https://docs.fanruan.design/assets/react/fine-design-runtime/fine-design/fine-design.min.js",
|
|
34
|
+
"cors": false,
|
|
35
|
+
"size": 953541,
|
|
36
|
+
"sha256": "f2d13832e2102c1b14661e7b493cc40deefb074177ea711ffde03a782cad0cbe",
|
|
37
|
+
"integrity": "sha256-8tE4MuIQLBsUZh57STzEDe77B0F36nEf/eA6eCytDL4="
|
|
38
|
+
},
|
|
39
|
+
"fineDesignCss": {
|
|
40
|
+
"package": "@fx-ui/fine-design",
|
|
41
|
+
"version": null,
|
|
42
|
+
"type": "style",
|
|
43
|
+
"url": "https://docs.fanruan.design/assets/react/fine-design-runtime/fine-design/fine-design.min.css",
|
|
44
|
+
"cors": false,
|
|
45
|
+
"size": 534135,
|
|
46
|
+
"sha256": "099aa50dd23f91ebd7bba853dac37087a5e54fbc9609d6563ffc7a1659c57e1d",
|
|
47
|
+
"integrity": "sha256-CZqlDdI/kevXu6hT2sNwh6XlT7yWCdZWP/x6FlnFfh0="
|
|
48
|
+
},
|
|
49
|
+
"vanAnalysis": {
|
|
50
|
+
"package": "@van/analysis",
|
|
51
|
+
"version": null,
|
|
52
|
+
"type": "script",
|
|
53
|
+
"global": "VanNext",
|
|
54
|
+
"url": "https://docs.fanruan.design/assets/react/fine-design-runtime/van-analysis/van-analysis.min.js",
|
|
55
|
+
"cors": false,
|
|
56
|
+
"size": 1050632,
|
|
57
|
+
"sha256": "45ef12733c41ac3e13fe6b4a264d3e7a79403b93b2a88e6aa966598beaaac740",
|
|
58
|
+
"integrity": "sha256-Re8SczxBrD4T/mtKJk0+enlAO5OyqI5qqWZZi+qqx0A="
|
|
59
|
+
},
|
|
60
|
+
"vanAnalysisCss": {
|
|
61
|
+
"package": "@van/analysis",
|
|
62
|
+
"version": null,
|
|
63
|
+
"type": "style",
|
|
64
|
+
"url": "https://docs.fanruan.design/assets/react/fine-design-runtime/van-analysis/van-analysis.min.css",
|
|
65
|
+
"cors": false,
|
|
66
|
+
"size": 20787,
|
|
67
|
+
"sha256": "aebde3aecbe4f89cc459e7ce9e9f978290b538d6e90ed8aa0cbf74cf9227e25e",
|
|
68
|
+
"integrity": "sha256-rr3jrsvk+JzEWefOnp+XgpC1ONbpDtiqDL90z5In4l4="
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
}
|
|
@@ -36,6 +36,7 @@ Use the sections relevant to the task. Selection choices are defaults for new wo
|
|
|
36
36
|
| `Dialog` | Save via `onOk`; handle both `onCancel` and `onCloseBtnClick` |
|
|
37
37
|
| `Tag` | Use semantic `type` or `style`; do not assume a `color` prop |
|
|
38
38
|
| `Avatar` | Character fallback uses `name` |
|
|
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` |
|
|
39
40
|
|
|
40
41
|
The table declaration differs from common `columns` APIs:
|
|
41
42
|
|
|
@@ -15,6 +15,7 @@ Use this map before fetching the overview page. If a name is missing or the curr
|
|
|
15
15
|
| Splitter | `Splitter` | `splitter-cn` | Root export |
|
|
16
16
|
| Affix | `Affix` | `affix-cn` | Root export |
|
|
17
17
|
| Anchor | `Anchor` | `anchor-cn` | Root export |
|
|
18
|
+
| BackTop | `BackTop` | `back-top-cn` | Root export |
|
|
18
19
|
| Breadcrumb | `Breadcrumb` | `breadcrumb-cn` | Root export |
|
|
19
20
|
| Dropdown | `Dropdown` | `dropdown-cn` | Root export |
|
|
20
21
|
| Menu | `Menu` | `menu-cn` | Root export |
|
|
@@ -27,6 +28,8 @@ Use this map before fetching the overview page. If a name is missing or the curr
|
|
|
27
28
|
| Check | `Check` | `check-cn` | Root export |
|
|
28
29
|
| MCascader | `MCascader` | `m-cascader-cn` | Public docs route exists; page title is Cascader |
|
|
29
30
|
| Cascader | `MCascader` preferred | `m-cascader-cn` | Online `cascader-cn` is 404; docs indicate legacy Cascader is being replaced |
|
|
31
|
+
| ColorPicker | `ColorPicker` | `color-picker-cn` | Root export |
|
|
32
|
+
| DatePicker | `DatePicker` | `date-picker-cn` | Low-level date panel root export; standard date input uses `Datetime` |
|
|
30
33
|
| Datetime | `Datetime` | `datetime-cn` | Root export |
|
|
31
34
|
| DatetimeRange | `DatetimeRange` | `datetime-range-cn` | Root export |
|
|
32
35
|
| Form | `Form` | `form-cn` | Root export |
|
|
@@ -68,8 +71,17 @@ Use this map before fetching the overview page. If a name is missing or the curr
|
|
|
68
71
|
| Combo | `Combo` | `combo-cn` | Root export |
|
|
69
72
|
| ComboCheck | `Combo.Check` | `combo-check-cn` | Documented online, but not a root export in `src/index.ts` |
|
|
70
73
|
| DataTable | `DataTable` | `data-table-cn` | Root export |
|
|
74
|
+
| VirtualList | `VirtualList` | `virtual-list-cn` | Root export |
|
|
71
75
|
| VirtualTable | `VirtualTable` | `virtual-table-cn` | Root export |
|
|
72
76
|
|
|
77
|
+
## Root Exports Without Standalone Pages
|
|
78
|
+
|
|
79
|
+
The following public root exports do not have dedicated `/components/<slug>-cn/` pages (`docsAvailable: false` in the CLI catalog). Inspect installed `.d.ts` declarations or query `fine-design doc <Name>` instead of guessing website routes:
|
|
80
|
+
|
|
81
|
+
- Components & primitives: `Segment`, `Label`, `Trigger`, `Message`, `LocaleProvider`
|
|
82
|
+
- Helpers & constants: `theme`, `ConfigProviderContext`, `FormCore`, `CheckedStrategy`, `CheckSize`, `DateUtils`, `getAllCheckedKeys`, `getHalfCheckedKeys`
|
|
83
|
+
- Built-in icons: 56 `*Outlined` / `*Filled` icon components exported from root (indexed under `SvgIcon` in the CLI catalog)
|
|
84
|
+
|
|
73
85
|
## Fallback Rules
|
|
74
86
|
|
|
75
87
|
1. If the component name does not appear here, fetch the overview page and search there.
|
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
## Version And Compatibility
|
|
4
4
|
|
|
5
|
-
-
|
|
5
|
+
- Choose the runtime first: reuse package imports in an existing React project; use browser/CDN scripts for a requested standalone HTML or embedded page. A missing project `.npmrc` alone does not decide the runtime.
|
|
6
|
+
- For package imports, resolve Fine Design, React, and ReactDOM versions from installed packages or the lockfile; a `package.json` range is not an exact version. For browser scripts, use the runtime manifest described below; no local npm installation is required.
|
|
6
7
|
- In the Fine Design repository, use the checked-out docs, exports, and demos. In consuming projects, prefer matching-version docs and verify uncertain APIs against installed public declarations/exports. Current website content and skill defaults must not override that contract.
|
|
7
8
|
- If docs are unavailable, use matching local declarations and examples; inspect only unresolved implementation details. State remaining uncertainty. Do not upgrade dependencies merely to fit an example, or infer full React-major compatibility from a permissive peer range.
|
|
8
9
|
- Reuse the existing installation and package manager. A new project may install `@fx-ui/fine-design` when needed.
|
|
@@ -19,11 +20,7 @@ npm config get registry
|
|
|
19
20
|
npm config get userconfig
|
|
20
21
|
```
|
|
21
22
|
|
|
22
|
-
A missing project `.npmrc` does not prove missing configuration: npm also uses user/global files, environment variables and command-line options. An isolated directory or global install does not inherit another project's `.npmrc`. Reuse an existing authorized configuration
|
|
23
|
-
|
|
24
|
-
```sh
|
|
25
|
-
npm install @fx-ui/fine-design@1.24.9 --userconfig=/absolute/path/to/.npmrc
|
|
26
|
-
```
|
|
23
|
+
A missing project `.npmrc` does not prove missing configuration: npm also uses user/global files, environment variables and command-line options. An isolated directory or global install does not inherit another project's `.npmrc`. Reuse an existing authorized configuration with `--userconfig=/absolute/path/to/.npmrc` instead of copying credentials. Construct the installation command using the project's resolved exact version. For new projects, select a version from the user's requirements and verified compatibility; do not copy a version from this guide or install `latest` by default.
|
|
27
24
|
|
|
28
25
|
For a new project that needs the company source, configure only the required scope; preserve existing settings and the default registry:
|
|
29
26
|
|
|
@@ -46,18 +43,24 @@ Single-file output includes all required code and styles; no unresolved `styles.
|
|
|
46
43
|
|
|
47
44
|
## Standalone HTML
|
|
48
45
|
|
|
49
|
-
Use
|
|
46
|
+
Use browser/CDN mode for standalone pages, embedded pages and previews without a build step. It does not require npm, Node.js or private-registry credentials in the consuming page. Preserve an existing project's package-based setup unless the user selects browser mode.
|
|
50
47
|
|
|
51
|
-
|
|
48
|
+
### Select Resources
|
|
52
49
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
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.
|
|
54
|
+
|
|
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.
|
|
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.
|
|
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.
|
|
60
|
+
|
|
61
|
+
### Mount And Verify
|
|
59
62
|
|
|
60
|
-
Use `window.FineDesign` for matching controls; ordinary document shells and page containers may use HTML. Use plain JavaScript/`React.createElement` unless a JSX transformer is included.
|
|
63
|
+
Use `window.FineDesign` for matching controls; ordinary document shells and page containers may use HTML. Use plain JavaScript/`React.createElement` unless a JSX transformer is included. Check that the chosen runtime exports the required controls and mounting API; display a useful loading/error state if resources fail.
|
|
61
64
|
|
|
62
65
|
Minimal mount after these scripts and a root element:
|
|
63
66
|
|
|
@@ -69,4 +72,4 @@ ReactDOM.createRoot(document.getElementById('root')).render(
|
|
|
69
72
|
);
|
|
70
73
|
```
|
|
71
74
|
|
|
72
|
-
|
|
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.
|
|
@@ -22,6 +22,7 @@ Load the global stylesheet through [imports-and-setup.md](imports-and-setup.md).
|
|
|
22
22
|
| Need | Contract |
|
|
23
23
|
| --- | --- |
|
|
24
24
|
| Dark mode | Use `theme.darkAlgorithm` to generate semantic tokens, not just a dark page background |
|
|
25
|
+
| Class prefix (`prefixCls`) | Prebuilt `dist/fine_design.css` uses the default prefix `'x'`. Do not copy `prefixCls="fd"` from website demos unless the project compiles custom Less with `@fd-prefix: fd` |
|
|
25
26
|
| Brand/status colors | Put seeds such as `colorPrimary`, `colorError`, `colorWarning`, `colorSuccess`, `colorInfo` in `theme.token` |
|
|
26
27
|
| Derived-token exception | Explicit tokens are final overrides; keep neutral surfaces/borders on the neutral scale rather than deriving them all from the brand |
|
|
27
28
|
| Compose algorithms | Arrays run left to right; later output wins. Custom algorithms return `{ ...token, ...overrides }` to retain earlier results |
|
package/src/cli.mjs
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
import fs from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { fileURLToPath } from 'node:url';
|
|
2
4
|
import { parseArgs } from 'node:util';
|
|
3
5
|
import { queryCatalog } from './core/catalog.mjs';
|
|
4
|
-
import { loadCatalog } from './core/data.mjs';
|
|
6
|
+
import { loadCatalog, readIndex } from './core/data.mjs';
|
|
5
7
|
import { resolveVersion } from './core/version.mjs';
|
|
6
8
|
import { ToolError, errorResult } from './core/errors.mjs';
|
|
7
9
|
|
|
@@ -10,46 +12,168 @@ const help = `Usage: fine-design <command> [arguments] [options]
|
|
|
10
12
|
Commands:
|
|
11
13
|
search [query] Search or browse components
|
|
12
14
|
doc <component> Read component documentation
|
|
13
|
-
example <component> <id> Read source files and
|
|
15
|
+
example <component> <id> Read source files and asset metadata
|
|
16
|
+
doctor Inspect detected version, available catalogs and bundled Skill
|
|
14
17
|
mcp Start the stdio MCP server
|
|
15
18
|
|
|
16
19
|
Options:
|
|
17
20
|
--fd-version <version> Exact Fine Design component version
|
|
18
21
|
--project <directory> Project used to detect the installed version
|
|
19
|
-
--format <text|json|markdown> Output format (default: text)
|
|
20
|
-
--section <heading>
|
|
22
|
+
--format <text|json|markdown> Output format (default: text; markdown is doc-only)
|
|
23
|
+
--section <heading> Doc section heading (exact or case-insensitive)
|
|
24
|
+
--toc, --summary Show only doc metadata, section headings and example IDs
|
|
21
25
|
--offset <number> Search pagination offset
|
|
22
|
-
--include-assets
|
|
26
|
+
--include-assets Include binary base64 and oversized JSON fixture content
|
|
23
27
|
--help Show help
|
|
24
28
|
--version Show tool version`;
|
|
25
29
|
|
|
30
|
+
function runDoctor(values) {
|
|
31
|
+
const projectDir = path.resolve(values.project || process.cwd());
|
|
32
|
+
if (!fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) {
|
|
33
|
+
throw new ToolError('INVALID_ARGUMENT', `Project directory does not exist: ${projectDir}`, 2);
|
|
34
|
+
}
|
|
35
|
+
const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
|
|
36
|
+
const index = readIndex();
|
|
37
|
+
const availableVersions = Object.keys(index.versions);
|
|
38
|
+
const bundledSkillPath = fileURLToPath(new URL('../skills/fine-design/SKILL.md', import.meta.url));
|
|
39
|
+
const bundledSkillAvailable = fs.existsSync(bundledSkillPath);
|
|
40
|
+
let detectedVersion = null;
|
|
41
|
+
let versionStatus = 'not-detected';
|
|
42
|
+
let suggestions = [];
|
|
43
|
+
try {
|
|
44
|
+
detectedVersion = resolveVersion(values['fd-version'], projectDir);
|
|
45
|
+
versionStatus = availableVersions.includes(detectedVersion) ? 'supported' : 'unsupported';
|
|
46
|
+
if (versionStatus === 'unsupported') {
|
|
47
|
+
suggestions = [`Detected ${detectedVersion}, which is not bundled in this CLI (${availableVersions.join(', ')}). Upgrade @finedesign/cli or pass a supported --fd-version.`];
|
|
48
|
+
}
|
|
49
|
+
} catch (error) {
|
|
50
|
+
if (error instanceof ToolError && error.code === 'VERSION_NOT_DETECTED') {
|
|
51
|
+
suggestions = error.details?.suggestions || [];
|
|
52
|
+
} else {
|
|
53
|
+
throw error;
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
return {
|
|
57
|
+
toolVersion: pkg.version,
|
|
58
|
+
nodeVersion: process.version,
|
|
59
|
+
projectDir,
|
|
60
|
+
detectedVersion,
|
|
61
|
+
versionStatus,
|
|
62
|
+
availableVersions,
|
|
63
|
+
bundledSkillVersion: index.skillVersion,
|
|
64
|
+
bundledSkillPath,
|
|
65
|
+
bundledSkillAvailable,
|
|
66
|
+
...(suggestions.length ? { suggestions } : {})
|
|
67
|
+
};
|
|
68
|
+
}
|
|
69
|
+
|
|
26
70
|
export async function main(argv) {
|
|
27
71
|
let format = 'text';
|
|
28
72
|
try {
|
|
29
73
|
const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, strict: true, options: {
|
|
30
74
|
help: { type: 'boolean' }, version: { type: 'boolean' }, 'fd-version': { type: 'string' }, project: { type: 'string' },
|
|
31
|
-
format: { type: 'string' }, section: { type: 'string' },
|
|
75
|
+
format: { type: 'string' }, section: { type: 'string' }, toc: { type: 'boolean' }, summary: { type: 'boolean' },
|
|
76
|
+
offset: { type: 'string' }, 'include-assets': { type: 'boolean' }
|
|
32
77
|
}});
|
|
33
78
|
format = values.format || 'text';
|
|
34
79
|
if (!['text', 'json', 'markdown'].includes(format)) throw new ToolError('INVALID_ARGUMENT', 'Unknown output format.', 2);
|
|
35
80
|
if (values.help || (!positionals.length && !values.version && !argv.length)) { console.log(help); return; }
|
|
36
|
-
if (values.version && argv.length === 1) { console.log(JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url))).version); return; }
|
|
81
|
+
if (values.version && argv.length === 1) { console.log(JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version); return; }
|
|
37
82
|
const [command, ...args] = positionals;
|
|
38
83
|
if (command === 'mcp' && args.length === 0 && argv.length === 1) { await (await import('./mcp.mjs')).startMcp(); return; }
|
|
84
|
+
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);
|
|
87
|
+
}
|
|
88
|
+
if (command === 'doctor') {
|
|
89
|
+
if (values.version || args.length > 0 || values.section !== undefined || summaryFlag || values.offset !== undefined || values['include-assets'] !== undefined) {
|
|
90
|
+
throw new ToolError('INVALID_ARGUMENT', 'Invalid options for doctor. Use --help for usage.', 2);
|
|
91
|
+
}
|
|
92
|
+
const report = runDoctor(values);
|
|
93
|
+
if (format === 'json') {
|
|
94
|
+
console.log(JSON.stringify(report));
|
|
95
|
+
} else {
|
|
96
|
+
const lines = [
|
|
97
|
+
`CLI version: ${report.toolVersion} (Node ${report.nodeVersion})`,
|
|
98
|
+
`Project directory: ${report.projectDir}`,
|
|
99
|
+
`Detected Fine Design: ${report.detectedVersion ?? 'none'} (${report.versionStatus})`,
|
|
100
|
+
`Bundled catalogs: ${report.availableVersions.join(', ')}`,
|
|
101
|
+
`Bundled Skill (${report.bundledSkillVersion}): ${report.bundledSkillPath}`
|
|
102
|
+
];
|
|
103
|
+
if (report.suggestions?.length) lines.push(`Suggestions:\n${report.suggestions.map((item) => ` - ${item}`).join('\n')}`);
|
|
104
|
+
console.log(lines.join('\n'));
|
|
105
|
+
}
|
|
106
|
+
return;
|
|
107
|
+
}
|
|
39
108
|
const tools = { search: 'search_components', doc: 'get_component_doc', example: 'get_component_example' };
|
|
40
|
-
if (
|
|
109
|
+
if (
|
|
110
|
+
!Object.hasOwn(tools, command) ||
|
|
111
|
+
values.version ||
|
|
112
|
+
(command === 'search' && args.length > 1) ||
|
|
113
|
+
(command === 'doc' && args.length !== 1) ||
|
|
114
|
+
(command === 'example' && args.length !== 2) ||
|
|
115
|
+
(values.section !== undefined && command !== 'doc') ||
|
|
116
|
+
((values.toc !== undefined || values.summary !== undefined) && command !== 'doc') ||
|
|
117
|
+
(values.section !== undefined && summaryFlag) ||
|
|
118
|
+
(values.offset !== undefined && command !== 'search') ||
|
|
119
|
+
(values['include-assets'] !== undefined && command !== 'example')
|
|
120
|
+
) {
|
|
121
|
+
throw new ToolError('INVALID_ARGUMENT', 'Invalid command or arguments. Use --help for usage.', 2);
|
|
122
|
+
}
|
|
41
123
|
if (values.offset !== undefined && !/^\d+$/.test(values.offset)) throw new ToolError('INVALID_ARGUMENT', 'Offset must be a non-negative integer.', 2);
|
|
42
124
|
const version = resolveVersion(values['fd-version'], values.project);
|
|
43
|
-
const input = {
|
|
125
|
+
const input = {
|
|
126
|
+
version,
|
|
127
|
+
...(command === 'search'
|
|
128
|
+
? { query: args[0] ?? '', ...(values.offset !== undefined && { offset: Number(values.offset) }) }
|
|
129
|
+
: {
|
|
130
|
+
component: args[0],
|
|
131
|
+
...(command === 'doc' && values.section !== undefined && { section: values.section }),
|
|
132
|
+
...(command === 'doc' && summaryFlag && { summary: true }),
|
|
133
|
+
...(command === 'example' && { exampleId: args[1], ...(values['include-assets'] !== undefined && { includeAssets: values['include-assets'] }) })
|
|
134
|
+
})
|
|
135
|
+
};
|
|
44
136
|
const { validateInput } = await import('./core/contracts.mjs');
|
|
45
137
|
validateInput(tools[command], input);
|
|
46
138
|
const result = queryCatalog(loadCatalog(version), tools[command], input);
|
|
47
|
-
if (format === 'json')
|
|
48
|
-
|
|
139
|
+
if (format === 'json') {
|
|
140
|
+
console.log(JSON.stringify(result));
|
|
141
|
+
} else if (command === 'doc') {
|
|
142
|
+
if (result.summary) {
|
|
143
|
+
if (format === 'markdown') {
|
|
144
|
+
console.log([
|
|
145
|
+
`# ${result.title}${result.subtitle ? ` ${result.subtitle}` : ''} (\`${result.component}\`)`,
|
|
146
|
+
result.description || '',
|
|
147
|
+
`Exports: ${result.exports.map((name) => `\`${name}\``).join(', ')}`,
|
|
148
|
+
`## Sections\n${result.sections.map((heading) => `- ${heading}`).join('\n') || '- none'}`,
|
|
149
|
+
`## Examples\n${result.examples.map((item) => `- \`${item.id}\`: ${item.title}`).join('\n') || '- none'}`
|
|
150
|
+
].filter(Boolean).join('\n\n'));
|
|
151
|
+
} else {
|
|
152
|
+
console.log([
|
|
153
|
+
`${result.component} (${result.exports.join(', ')})${result.subtitle ? ` - ${result.subtitle}` : ''}`,
|
|
154
|
+
...(result.description ? [result.description] : []),
|
|
155
|
+
`Docs available: ${result.docsAvailable}`,
|
|
156
|
+
`Sections: ${result.sections.join(', ') || 'none'}`,
|
|
157
|
+
`Examples: ${result.examples.map((item) => item.id).join(', ') || 'none'}`
|
|
158
|
+
].join('\n'));
|
|
159
|
+
}
|
|
160
|
+
} else if (format === 'markdown') {
|
|
161
|
+
console.log(result.markdown || `No documentation available for ${result.component}.`);
|
|
162
|
+
} else {
|
|
163
|
+
console.log(`${result.markdown || `No documentation available for ${result.component}.`}
|
|
49
164
|
|
|
50
165
|
${result.sections ? `Sections: ${result.sections.join(', ') || 'none'}\n` : ''}Examples: ${result.examples.map((item) => item.id).join(', ') || 'none'}`);
|
|
51
|
-
|
|
52
|
-
else
|
|
166
|
+
}
|
|
167
|
+
} else if (command === 'search') {
|
|
168
|
+
const lines = [
|
|
169
|
+
...(result.components.length ? [result.components.map((item) => `${item.id} (${item.exports.join(', ')}): ${item.description}`).join('\n')] : []),
|
|
170
|
+
`Total: ${result.total}; nextOffset: ${result.nextOffset ?? 'none'}`,
|
|
171
|
+
...(result.suggestions || [])
|
|
172
|
+
];
|
|
173
|
+
console.log(lines.join('\n'));
|
|
174
|
+
} else {
|
|
175
|
+
console.log(JSON.stringify(result, null, 2));
|
|
176
|
+
}
|
|
53
177
|
} catch (error) {
|
|
54
178
|
const normalized = error instanceof TypeError && error.code?.startsWith('ERR_PARSE_ARGS') ? new ToolError('INVALID_ARGUMENT', error.message, 2) : error;
|
|
55
179
|
const result = errorResult(normalized);
|
package/src/core/catalog.mjs
CHANGED
|
@@ -2,6 +2,9 @@ import { ToolError } from './errors.mjs';
|
|
|
2
2
|
import { validateInput } from './contracts.mjs';
|
|
3
3
|
import { sha256 } from './data.mjs';
|
|
4
4
|
|
|
5
|
+
const MAX_INLINE_JSON_BYTES = 16 * 1024;
|
|
6
|
+
const CHART_QUERY_PATTERN = /chart|vanchart|图表|折线|柱状|饼图|散点|雷达|漏斗|仪表盘|热力图|词云/i;
|
|
7
|
+
|
|
5
8
|
export function queryCatalog(catalog, tool, args) {
|
|
6
9
|
args = validateInput(tool, args);
|
|
7
10
|
if (args.version !== catalog.version) throw new ToolError('VERSION_NOT_SUPPORTED', 'Requested Fine Design version is not available.', 3, { requestedVersion: args.version, availableVersions: [catalog.version] });
|
|
@@ -28,6 +31,9 @@ export function queryCatalog(catalog, tool, args) {
|
|
|
28
31
|
.toLowerCase();
|
|
29
32
|
return terms.every((term) => text.includes(term));
|
|
30
33
|
});
|
|
34
|
+
const chartHint = matches.length === 0 && CHART_QUERY_PATTERN.test(args.query)
|
|
35
|
+
? ['Charts are provided by the standalone VanChart skill (/van-chart) and @van/analysis runtime; see /docs/chart/skills-cn.']
|
|
36
|
+
: undefined;
|
|
31
37
|
return {
|
|
32
38
|
...source,
|
|
33
39
|
total: matches.length,
|
|
@@ -54,7 +60,8 @@ export function queryCatalog(catalog, tool, args) {
|
|
|
54
60
|
examples: examples.map(({ id, title }) => ({ id, title }))
|
|
55
61
|
})
|
|
56
62
|
),
|
|
57
|
-
nextOffset: matches.length > (args.offset || 0) + 20 ? (args.offset || 0) + 20 : null
|
|
63
|
+
nextOffset: matches.length > (args.offset || 0) + 20 ? (args.offset || 0) + 20 : null,
|
|
64
|
+
...(chartHint ? { suggestions: chartHint } : {})
|
|
58
65
|
};
|
|
59
66
|
}
|
|
60
67
|
const component = catalog.components.find((item) =>
|
|
@@ -65,6 +72,9 @@ export function queryCatalog(catalog, tool, args) {
|
|
|
65
72
|
if (!component)
|
|
66
73
|
throw new ToolError('COMPONENT_NOT_FOUND', `Unknown component: ${args.component}.`, 4, { suggestions: ['Use search to find a component.'] });
|
|
67
74
|
if (tool === 'get_component_doc') {
|
|
75
|
+
if (args.section && args.summary) {
|
|
76
|
+
throw new ToolError('INVALID_ARGUMENT', 'Cannot combine section and summary.', 2);
|
|
77
|
+
}
|
|
68
78
|
const examples = component.examples.map(
|
|
69
79
|
({ id, title, entry, dependencies, unresolved }) => ({
|
|
70
80
|
id,
|
|
@@ -74,10 +84,37 @@ export function queryCatalog(catalog, tool, args) {
|
|
|
74
84
|
unresolved
|
|
75
85
|
})
|
|
76
86
|
);
|
|
87
|
+
if (args.summary) {
|
|
88
|
+
return {
|
|
89
|
+
...source,
|
|
90
|
+
component: component.id,
|
|
91
|
+
title: component.title,
|
|
92
|
+
subtitle: component.subtitle,
|
|
93
|
+
description: component.description,
|
|
94
|
+
exports: component.exports,
|
|
95
|
+
aliases: component.aliases,
|
|
96
|
+
docsAvailable: component.docsAvailable,
|
|
97
|
+
sourcePath: component.sourcePath,
|
|
98
|
+
summary: true,
|
|
99
|
+
sections: component.sections.map(({ heading }) => heading),
|
|
100
|
+
examples
|
|
101
|
+
};
|
|
102
|
+
}
|
|
77
103
|
if (args.section) {
|
|
78
|
-
const
|
|
79
|
-
|
|
80
|
-
|
|
104
|
+
const normalizedSection = args.section.trim().toLowerCase();
|
|
105
|
+
const section = component.sections.find((item) => item.heading === args.section)
|
|
106
|
+
|| component.sections.find((item) => item.heading.trim().toLowerCase() === normalizedSection);
|
|
107
|
+
if (!section) {
|
|
108
|
+
const availableSections = component.sections.map((item) => item.heading);
|
|
109
|
+
const similar = availableSections.filter((heading) => {
|
|
110
|
+
const lower = heading.toLowerCase();
|
|
111
|
+
return lower.includes(normalizedSection) || normalizedSection.includes(lower);
|
|
112
|
+
});
|
|
113
|
+
throw new ToolError('SECTION_NOT_FOUND', 'Unknown section.', 4, {
|
|
114
|
+
availableSections,
|
|
115
|
+
...(similar.length ? { suggestions: [`Closest sections: ${similar.join(', ')}`] } : {})
|
|
116
|
+
});
|
|
117
|
+
}
|
|
81
118
|
return {
|
|
82
119
|
...source,
|
|
83
120
|
component: component.id,
|
|
@@ -102,10 +139,28 @@ export function queryCatalog(catalog, tool, args) {
|
|
|
102
139
|
if (!example)
|
|
103
140
|
throw new ToolError('EXAMPLE_NOT_FOUND', 'Unknown example.', 4, { availableExamples: component.examples.map((item) => item.id) });
|
|
104
141
|
const files = example.files.map((file) => {
|
|
105
|
-
if (file.encoding
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
142
|
+
if (file.encoding === 'base64') {
|
|
143
|
+
const { content, ...metadata } = file;
|
|
144
|
+
const bytes = Buffer.from(content, 'base64');
|
|
145
|
+
return { ...metadata, size: bytes.length, sha256: sha256(bytes), ...(args.includeAssets ? { content } : {}) };
|
|
146
|
+
}
|
|
147
|
+
if (file.encoding === 'utf8' && file.path !== example.entry && file.path.endsWith('.json')) {
|
|
148
|
+
const bytes = Buffer.from(file.content, 'utf8');
|
|
149
|
+
if (bytes.length > MAX_INLINE_JSON_BYTES) {
|
|
150
|
+
const { content, ...metadata } = file;
|
|
151
|
+
if (args.includeAssets) {
|
|
152
|
+
return { ...metadata, size: bytes.length, sha256: sha256(bytes), content };
|
|
153
|
+
}
|
|
154
|
+
return {
|
|
155
|
+
...metadata,
|
|
156
|
+
size: bytes.length,
|
|
157
|
+
sha256: sha256(bytes),
|
|
158
|
+
truncated: true,
|
|
159
|
+
preview: `${content.slice(0, 512)}...`
|
|
160
|
+
};
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
return file;
|
|
109
164
|
});
|
|
110
165
|
return { ...source, component: component.id, ...example, files };
|
|
111
166
|
}
|
package/src/core/contracts.mjs
CHANGED
|
@@ -5,8 +5,18 @@ 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({ version, query: z.string().max(200), offset: z.number().int().min(0).max(10000).optional() }).strict(),
|
|
8
|
-
get_component_doc: z.object({
|
|
9
|
-
|
|
8
|
+
get_component_doc: z.object({
|
|
9
|
+
version,
|
|
10
|
+
component,
|
|
11
|
+
section: z.string().min(1).max(200).optional(),
|
|
12
|
+
summary: z.boolean().optional().describe('Return only metadata, section headings and example IDs without full markdown.')
|
|
13
|
+
}).strict(),
|
|
14
|
+
get_component_example: z.object({
|
|
15
|
+
version,
|
|
16
|
+
component,
|
|
17
|
+
exampleId: z.string().min(1).max(200),
|
|
18
|
+
includeAssets: z.boolean().optional().describe('Include binary asset content as base64 and full oversized JSON fixture content; default returns metadata/preview for large assets.')
|
|
19
|
+
}).strict()
|
|
10
20
|
};
|
|
11
21
|
|
|
12
22
|
export function validateInput(tool, input) {
|
package/src/core/data.mjs
CHANGED
|
@@ -85,7 +85,11 @@ export function readIndex(root = dataRoot) {
|
|
|
85
85
|
return index;
|
|
86
86
|
}
|
|
87
87
|
|
|
88
|
+
const catalogCache = new Map();
|
|
89
|
+
|
|
88
90
|
export function loadCatalog(version) {
|
|
91
|
+
const cacheKey = `${dataRoot}:${version}`;
|
|
92
|
+
if (catalogCache.has(cacheKey)) return catalogCache.get(cacheKey);
|
|
89
93
|
const index = readIndex();
|
|
90
94
|
const entry = index.versions[version];
|
|
91
95
|
if (!Object.hasOwn(index.versions, version)) {
|
|
@@ -95,5 +99,7 @@ export function loadCatalog(version) {
|
|
|
95
99
|
}
|
|
96
100
|
safeFile(dataRoot, entry.catalog);
|
|
97
101
|
safeFile(dataRoot, entry.manifest);
|
|
98
|
-
|
|
102
|
+
const { catalog } = readSnapshot(path.join(dataRoot, version), version);
|
|
103
|
+
catalogCache.set(cacheKey, catalog);
|
|
104
|
+
return catalog;
|
|
99
105
|
}
|