@finedesign/cli 0.1.0 → 0.2.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,16 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "version": "1.25.0",
4
+ "sourceKind": "repository-snapshot",
5
+ "sourceRevision": "cd0e18216c5c827cadb64a71a947a643394d15ac",
6
+ "sourceDirty": false,
7
+ "contentHash": "c64aec628caee0ee14cbaeb68bbe7e0d3bea0362590d94ac8f3da983f054a348",
8
+ "catalogSha256": "8dd9a17aafcb42a07667d9ee50e9398a7f229fa1855efbf86a466baf819ee661",
9
+ "skillFiles": {
10
+ "references/component-guide.md": "fd18509f7b304bb3073736c514c1b43d41284499a5616cb4fcba95bf849094cb",
11
+ "references/docs-slug-map.md": "440ce5cf137fd22eabfcc5b51c3f55b85174aa643773ef0cedd5df542e77bbc2",
12
+ "references/imports-and-setup.md": "5bd9024770a77ddeb0f4dce94ebd103f327c2513b52f165e371da9c4dbdcd98f",
13
+ "references/theme-and-dark-mode.md": "2eccae4930ea993e7088eee03a4b4a0f1c839033079db5f21f8c60e0fe8168d1",
14
+ "SKILL.md": "035ce9e23c7c1f78addcb08198f02b3b482c61d8a9b3b939e8b5f12511058750"
15
+ }
16
+ }
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",
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
 
@@ -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
+ 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.
51
+
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
+
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
+
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
+
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 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`.
@@ -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,55 +1,193 @@
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';
9
+ import { listRuntimes, resolveRuntime } from './core/runtime.mjs';
10
+ import html from './core/html.cjs';
7
11
 
8
12
  const help = `Usage: fine-design <command> [arguments] [options]
9
13
 
10
14
  Commands:
11
15
  search [query] Search or browse components
12
16
  doc <component> Read component documentation
13
- example <component> <id> Read source files and binary asset metadata
17
+ example <component> <id> Read source files and asset metadata
18
+ doctor Inspect detected version, available catalogs and bundled Skill
19
+ runtime [list] Resolve a versioned online UMD runtime or list published versions
14
20
  mcp Start the stdio MCP server
15
21
 
16
22
  Options:
17
23
  --fd-version <version> Exact Fine Design component version
18
24
  --project <directory> Project used to detect the installed version
19
- --format <text|json|markdown> Output format (default: text)
20
- --section <heading> Exact doc section
25
+ --runtime-url <url> Runtime hosting base URL (runtime command only)
26
+ --format <text|json|markdown|html> Output format (markdown: doc; html: runtime)
27
+ --section <heading> Doc section heading (exact or case-insensitive)
28
+ --toc, --summary Show only doc metadata, section headings and example IDs
21
29
  --offset <number> Search pagination offset
22
- --include-assets Include binary asset content in example output
30
+ --include-assets Include binary base64 and oversized JSON fixture content
23
31
  --help Show help
24
32
  --version Show tool version`;
25
33
 
34
+ function runDoctor(values) {
35
+ const projectDir = path.resolve(values.project || process.cwd());
36
+ if (!fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) {
37
+ throw new ToolError('INVALID_ARGUMENT', `Project directory does not exist: ${projectDir}`, 2);
38
+ }
39
+ const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
40
+ const index = readIndex();
41
+ const availableVersions = Object.keys(index.versions);
42
+ const bundledSkillPath = fileURLToPath(new URL('../skills/fine-design/SKILL.md', import.meta.url));
43
+ const bundledSkillAvailable = fs.existsSync(bundledSkillPath);
44
+ let detectedVersion = null;
45
+ let versionStatus = 'not-detected';
46
+ let suggestions = [];
47
+ try {
48
+ detectedVersion = resolveVersion(values['fd-version'], projectDir);
49
+ versionStatus = availableVersions.includes(detectedVersion) ? 'supported' : 'unsupported';
50
+ if (versionStatus === 'unsupported') {
51
+ suggestions = [`Detected ${detectedVersion}, which is not bundled in this CLI (${availableVersions.join(', ')}). Upgrade @finedesign/cli or pass a supported --fd-version.`];
52
+ }
53
+ } catch (error) {
54
+ if (error instanceof ToolError && error.code === 'VERSION_NOT_DETECTED') {
55
+ suggestions = error.context?.suggestions || [];
56
+ } else {
57
+ throw error;
58
+ }
59
+ }
60
+ return {
61
+ toolVersion: pkg.version,
62
+ nodeVersion: process.version,
63
+ projectDir,
64
+ detectedVersion,
65
+ versionStatus,
66
+ availableVersions,
67
+ bundledSkillVersion: index.skillVersion,
68
+ bundledSkillPath,
69
+ bundledSkillAvailable,
70
+ ...(suggestions.length ? { suggestions } : {})
71
+ };
72
+ }
73
+
26
74
  export async function main(argv) {
27
75
  let format = 'text';
28
76
  try {
29
77
  const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, strict: true, options: {
30
78
  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' }
79
+ format: { type: 'string' }, section: { type: 'string' }, toc: { type: 'boolean' }, summary: { type: 'boolean' },
80
+ offset: { type: 'string' }, 'include-assets': { type: 'boolean' },
81
+ 'runtime-url': { type: 'string' }
32
82
  }});
33
83
  format = values.format || 'text';
34
- if (!['text', 'json', 'markdown'].includes(format)) throw new ToolError('INVALID_ARGUMENT', 'Unknown output format.', 2);
84
+ if (!['text', 'json', 'markdown', 'html'].includes(format)) throw new ToolError('INVALID_ARGUMENT', 'Unknown output format.', 2);
35
85
  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; }
86
+ if (values.version && argv.length === 1) { console.log(JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version); return; }
37
87
  const [command, ...args] = positionals;
38
88
  if (command === 'mcp' && args.length === 0 && argv.length === 1) { await (await import('./mcp.mjs')).startMcp(); return; }
89
+ const summaryFlag = Boolean(values.toc || values.summary);
90
+ if (command !== 'runtime' && (values['runtime-url'] !== undefined)) throw new ToolError('INVALID_ARGUMENT', 'Runtime options are only supported for runtime.', 2);
91
+ if (format === 'markdown' && command !== 'doc') {
92
+ throw new ToolError('INVALID_ARGUMENT', 'Markdown output format is only supported for the doc command.', 2);
93
+ }
94
+ if (format === 'html' && (command !== 'runtime' || args.length)) throw new ToolError('INVALID_ARGUMENT', 'HTML output format is only supported for runtime resolution.', 2);
95
+ if (command === 'runtime') {
96
+ const list = args.length === 1 && args[0] === 'list';
97
+ if ((!list && args.length) || values.version || values.section !== undefined || summaryFlag || values.offset !== 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);
98
+ const result = list ? await listRuntimes(values['runtime-url']) : await resolveRuntime({ version: resolveVersion(values['fd-version'], values.project), runtimeURL: values['runtime-url'] });
99
+ 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}`);
100
+ return;
101
+ }
102
+ if (command === 'doctor') {
103
+ if (values.version || args.length > 0 || values.section !== undefined || summaryFlag || values.offset !== undefined || values['include-assets'] !== undefined) {
104
+ throw new ToolError('INVALID_ARGUMENT', 'Invalid options for doctor. Use --help for usage.', 2);
105
+ }
106
+ const report = runDoctor(values);
107
+ if (format === 'json') {
108
+ console.log(JSON.stringify(report));
109
+ } else {
110
+ const lines = [
111
+ `CLI version: ${report.toolVersion} (Node ${report.nodeVersion})`,
112
+ `Project directory: ${report.projectDir}`,
113
+ `Detected Fine Design: ${report.detectedVersion ?? 'none'} (${report.versionStatus})`,
114
+ `Bundled catalogs: ${report.availableVersions.join(', ')}`,
115
+ `Bundled Skill (${report.bundledSkillVersion}): ${report.bundledSkillPath}`
116
+ ];
117
+ if (report.suggestions?.length) lines.push(`Suggestions:\n${report.suggestions.map((item) => ` - ${item}`).join('\n')}`);
118
+ console.log(lines.join('\n'));
119
+ }
120
+ return;
121
+ }
39
122
  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);
123
+ if (
124
+ !Object.hasOwn(tools, command) ||
125
+ values.version ||
126
+ (command === 'search' && args.length > 1) ||
127
+ (command === 'doc' && args.length !== 1) ||
128
+ (command === 'example' && args.length !== 2) ||
129
+ (values.section !== undefined && command !== 'doc') ||
130
+ ((values.toc !== undefined || values.summary !== undefined) && command !== 'doc') ||
131
+ (values.section !== undefined && summaryFlag) ||
132
+ (values.offset !== undefined && command !== 'search') ||
133
+ (values['include-assets'] !== undefined && command !== 'example')
134
+ ) {
135
+ throw new ToolError('INVALID_ARGUMENT', 'Invalid command or arguments. Use --help for usage.', 2);
136
+ }
41
137
  if (values.offset !== undefined && !/^\d+$/.test(values.offset)) throw new ToolError('INVALID_ARGUMENT', 'Offset must be a non-negative integer.', 2);
42
138
  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'] }) }) }) };
139
+ const input = {
140
+ version,
141
+ ...(command === 'search'
142
+ ? { query: args[0] ?? '', ...(values.offset !== undefined && { offset: Number(values.offset) }) }
143
+ : {
144
+ component: args[0],
145
+ ...(command === 'doc' && values.section !== undefined && { section: values.section }),
146
+ ...(command === 'doc' && summaryFlag && { summary: true }),
147
+ ...(command === 'example' && { exampleId: args[1], ...(values['include-assets'] !== undefined && { includeAssets: values['include-assets'] }) })
148
+ })
149
+ };
44
150
  const { validateInput } = await import('./core/contracts.mjs');
45
151
  validateInput(tools[command], input);
46
152
  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}.`}
153
+ if (format === 'json') {
154
+ console.log(JSON.stringify(result));
155
+ } else if (command === 'doc') {
156
+ if (result.summary) {
157
+ if (format === 'markdown') {
158
+ console.log([
159
+ `# ${result.title}${result.subtitle ? ` ${result.subtitle}` : ''} (\`${result.component}\`)`,
160
+ result.description || '',
161
+ `Exports: ${result.exports.map((name) => `\`${name}\``).join(', ')}`,
162
+ `## Sections\n${result.sections.map((heading) => `- ${heading}`).join('\n') || '- none'}`,
163
+ `## Examples\n${result.examples.map((item) => `- \`${item.id}\`: ${item.title}`).join('\n') || '- none'}`
164
+ ].filter(Boolean).join('\n\n'));
165
+ } else {
166
+ console.log([
167
+ `${result.component} (${result.exports.join(', ')})${result.subtitle ? ` - ${result.subtitle}` : ''}`,
168
+ ...(result.description ? [result.description] : []),
169
+ `Docs available: ${result.docsAvailable}`,
170
+ `Sections: ${result.sections.join(', ') || 'none'}`,
171
+ `Examples: ${result.examples.map((item) => item.id).join(', ') || 'none'}`
172
+ ].join('\n'));
173
+ }
174
+ } else if (format === 'markdown') {
175
+ console.log(result.markdown || `No documentation available for ${result.component}.`);
176
+ } else {
177
+ console.log(`${result.markdown || `No documentation available for ${result.component}.`}
49
178
 
50
179
  ${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));
180
+ }
181
+ } else if (command === 'search') {
182
+ const lines = [
183
+ ...(result.components.length ? [result.components.map((item) => `${item.id} (${item.exports.join(', ')}): ${item.description}`).join('\n')] : []),
184
+ `Total: ${result.total}; nextOffset: ${result.nextOffset ?? 'none'}`,
185
+ ...(result.suggestions || [])
186
+ ];
187
+ console.log(lines.join('\n'));
188
+ } else {
189
+ console.log(JSON.stringify(result, null, 2));
190
+ }
53
191
  } catch (error) {
54
192
  const normalized = error instanceof TypeError && error.code?.startsWith('ERR_PARSE_ARGS') ? new ToolError('INVALID_ARGUMENT', error.message, 2) : error;
55
193
  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,20 @@ 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
+ list_browser_runtimes: z.object({ runtimeURL: z.string().max(2048).optional() }).strict(),
15
+ get_browser_runtime: z.object({ version, runtimeURL: z.string().max(2048).optional() }).strict(),
16
+ get_component_example: z.object({
17
+ version,
18
+ component,
19
+ exampleId: z.string().min(1).max(200),
20
+ includeAssets: z.boolean().optional().describe('Include binary asset content as base64 and full oversized JSON fixture content; default returns metadata/preview for large assets.')
21
+ }).strict()
10
22
  };
11
23
 
12
24
  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
  }
@@ -0,0 +1,32 @@
1
+ function exampleHTML(resources, prefix) {
2
+ const url = (entry) => entry.url || `${prefix}${entry.path}`;
3
+ const css = resources.fineDesignCss;
4
+ const scripts = ['react', 'reactDOM', 'fineDesign'].map((name) => {
5
+ const entry = resources[name];
6
+ return `<script src="${url(entry)}" integrity="${entry.integrity}" crossorigin="anonymous" onerror="(window.runtimeLoadErrors ||= []).push(this.src)"></script>`;
7
+ }).join('\n');
8
+ return `<!doctype html>
9
+ <html lang="zh-CN"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
10
+ <title>Fine Design 浏览器示例</title>
11
+ <link rel="stylesheet" href="${url(css)}" integrity="${css.integrity}" crossorigin="anonymous" onerror="(window.runtimeLoadErrors ||= []).push(this.href)">
12
+ <body style="margin:48px"><h1>Fine Design</h1><p>浏览器接入示例</p>
13
+ <p id="error" role="alert" hidden>资源加载失败,请检查网络或资源地址。</p><div id="root"></div>
14
+ ${scripts}
15
+ <script>
16
+ try {
17
+ if (window.runtimeLoadErrors || !window.FineDesign || !window.ReactDOM || typeof ReactDOM.createRoot !== 'function') throw new Error('Missing runtime');
18
+ const h = React.createElement;
19
+ function App() {
20
+ const [count, setCount] = React.useState(0);
21
+ return h(FineDesign.Button, { type: 'primary', onClick: () => setCount(count + 1) }, '已点击 ' + count + ' 次');
22
+ }
23
+ ReactDOM.createRoot(document.getElementById('root')).render(h(App));
24
+ } catch (error) {
25
+ const message = document.getElementById('error');
26
+ message.hidden = false;
27
+ message.textContent = window.runtimeLoadErrors ? '资源加载失败:' + window.runtimeLoadErrors.join(',') : '页面启动失败:' + error.message;
28
+ }
29
+ </script></body></html>\n`;
30
+ }
31
+
32
+ module.exports = { exampleHTML };