@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.
@@ -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
@@ -4,7 +4,11 @@
4
4
  "1.24.9": {
5
5
  "catalog": "1.24.9/catalog.json",
6
6
  "manifest": "1.24.9/manifest.json"
7
+ },
8
+ "1.25.0": {
9
+ "catalog": "1.25.0/catalog.json",
10
+ "manifest": "1.25.0/manifest.json"
7
11
  }
8
12
  },
9
- "skillVersion": "1.24.9"
13
+ "skillVersion": "1.25.0"
10
14
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@finedesign/cli",
3
- "version": "0.1.0",
3
+ "version": "0.2.0-rc.0",
4
4
  "description": "Read-only, versioned Fine Design documentation for coding agents",
5
5
  "license": "MIT",
6
6
  "publishConfig": {
@@ -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: integrated page, standalone React/TSX/HTML, fix, or read-only review. Preserve compatible existing components and explicit user choices.
15
- 2. Confirm the actual Fine Design and React versions. Use matching local docs, public declarations, and demos; in consuming projects, resolve online pages through [docs-slug-map.md](references/docs-slug-map.md). Inspect implementation only when the public contract is insufficient. State gaps instead of guessing APIs or upgrading dependencies to fit examples.
16
- 3. When available, prefer the connected Fine Design MCP tools; otherwise use the local `fine-design` CLI with `--format json` and the exact installed component version. Query only the components and examples needed; if neither is available, use matching local documentation and public declarations.
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
- - Resolve Fine Design, React, and ReactDOM versions from installed packages or the lockfile; a `package.json` range is not an exact version.
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 by path instead of copying its credentials. For a project confirmed to use version 1.24.9:
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 this path when the user wants a standalone preview. Do not silently replace an existing React project with CDN runtime code to bypass an installation failure.
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
- The public UMD runtime replaces package imports. Load in this order:
48
+ ### Select Resources
52
49
 
53
- ```html
54
- <link rel="stylesheet" href="https://docs.fanruan.design/assets/react/fine-design-runtime/fine-design/fine-design.min.css" />
55
- <script src="https://cdn.jsdelivr.net/npm/react@18.3.1/umd/react.production.min.js"></script>
56
- <script src="https://cdn.jsdelivr.net/npm/react-dom@18.3.1/umd/react-dom.production.min.js"></script>
57
- <script src="https://docs.fanruan.design/assets/react/fine-design-runtime/fine-design/fine-design.min.js"></script>
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. The unversioned Fine Design assets do not prove an exact npm version; verify required exports and behavior.
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
- In this repository, the public assets are generated by `npm run build:public-assets`; consuming projects use the published URLs.
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 binary asset metadata
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> Exact doc section
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 Include binary asset content in example output
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' }, offset: { type: 'string' }, 'include-assets': { type: 'boolean' }
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 (!Object.hasOwn(tools, command) || values.version || (command === 'search' && args.length > 1) || (command === 'doc' && args.length !== 1) || (command === 'example' && args.length !== 2) || (values.section !== undefined && command !== 'doc') || (values.offset !== undefined && command !== 'search') || (values['include-assets'] !== undefined && command !== 'example')) throw new ToolError('INVALID_ARGUMENT', 'Invalid command or arguments. Use --help for usage.', 2);
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 = { version, ...(command === 'search' ? { query: args[0] ?? '', ...(values.offset !== undefined && { offset: Number(values.offset) }) } : { component: args[0], ...(command === 'doc' && values.section !== undefined && { section: values.section }), ...(command === 'example' && { exampleId: args[1], ...(values['include-assets'] !== undefined && { includeAssets: values['include-assets'] }) }) }) };
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') console.log(JSON.stringify(result));
48
- else if (command === 'doc') console.log(`${result.markdown || `No documentation available for ${result.component}.`}
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
- else if (command === 'search') console.log(`${result.components.map((item) => `${item.id} (${item.exports.join(', ')}): ${item.description}`).join('\n')}\nTotal: ${result.total}; nextOffset: ${result.nextOffset ?? 'none'}`);
52
- else console.log(JSON.stringify(result, null, 2));
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);
@@ -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 section = component.sections.find((item) => item.heading === args.section);
79
- if (!section)
80
- throw new ToolError('SECTION_NOT_FOUND', 'Unknown section.', 4, { availableSections: component.sections.map((item) => item.heading) });
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 !== 'base64') return file;
106
- const { content, ...metadata } = file;
107
- const bytes = Buffer.from(content, 'base64');
108
- return { ...metadata, size: bytes.length, sha256: sha256(bytes), ...(args.includeAssets ? { content } : {}) };
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
  }
@@ -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({ version, component, section: z.string().min(1).max(200).optional() }).strict(),
9
- get_component_example: z.object({ version, component, exampleId: z.string().min(1).max(200), includeAssets: z.boolean().optional().describe('Include binary asset content as base64; default returns only asset metadata.') }).strict()
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
- return readSnapshot(path.join(dataRoot, version), version).catalog;
102
+ const { catalog } = readSnapshot(path.join(dataRoot, version), version);
103
+ catalogCache.set(cacheKey, catalog);
104
+ return catalog;
99
105
  }