@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.
- package/CHANGELOG.md +20 -0
- package/README.md +50 -150
- package/data/1.25.0/catalog.json +1 -0
- package/data/1.25.0/manifest.json +16 -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/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 +152 -14
- package/src/core/catalog.mjs +63 -8
- package/src/core/contracts.mjs +14 -2
- package/src/core/data.mjs +7 -1
- package/src/core/html.cjs +32 -0
- package/src/core/runtime.mjs +62 -0
- package/src/core/version.mjs +11 -1
- package/src/mcp.mjs +9 -5
|
@@ -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
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
|
|
|
@@ -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
|
+
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.
|
|
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 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
|
|
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
|
-
--
|
|
20
|
-
--
|
|
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
|
|
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' },
|
|
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 (
|
|
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 = {
|
|
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')
|
|
48
|
-
|
|
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
|
-
|
|
52
|
-
else
|
|
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);
|
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,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({
|
|
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
|
+
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
|
-
|
|
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 };
|