@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,62 @@
|
|
|
1
|
+
import { exactVersion, readIndex } from './data.mjs';
|
|
2
|
+
import { ToolError } from './errors.mjs';
|
|
3
|
+
|
|
4
|
+
export const defaultRuntimeURL = 'https://fine-design-runtime.pages.dev/';
|
|
5
|
+
const hosted = { fineDesign: ['@fx-ui/fine-design', 'fine-design', 'fine-design.min.js'], fineDesignCss: ['@fx-ui/fine-design', 'fine-design', 'fine-design.min.css'], vanAnalysis: ['@van/analysis', 'van-analysis', 'van-analysis.min.js'], vanAnalysisCss: ['@van/analysis', 'van-analysis', 'van-analysis.min.css'] };
|
|
6
|
+
const invalid = (message) => { throw new ToolError('RUNTIME_INVALID', message, 1); };
|
|
7
|
+
|
|
8
|
+
export function validateRuntimeManifest(manifest) {
|
|
9
|
+
if (manifest?.schemaVersion !== 1 || !exactVersion.test(manifest.version) || !manifest.resources || Object.keys(manifest.resources).sort().join(',') !== ['react', 'reactDOM', ...Object.keys(hosted)].sort().join(',')) invalid('Invalid current runtime manifest.');
|
|
10
|
+
for (const [key, entry] of Object.entries(manifest.resources)) {
|
|
11
|
+
if (!entry || !exactVersion.test(entry.version) || !/^[a-f0-9]{64}$/.test(entry.sha256) || entry.integrity !== `sha256-${Buffer.from(entry.sha256, 'hex').toString('base64')}` || !Number.isSafeInteger(entry.size) || entry.size <= 0 || entry.type !== (key.endsWith('Css') ? 'style' : 'script')) invalid(`Invalid runtime resource: ${key}`);
|
|
12
|
+
if (hosted[key]) {
|
|
13
|
+
const [pkg, directory, filename] = hosted[key];
|
|
14
|
+
if (entry.package !== pkg || entry.path !== `${directory}/${entry.version}/${filename}` || entry.url) invalid(`Unexpected versioned resource path: ${key}`);
|
|
15
|
+
} else {
|
|
16
|
+
const pkg = key === 'react' ? 'react' : 'react-dom';
|
|
17
|
+
if (entry.package !== pkg || entry.path || entry.url !== `https://cdn.jsdelivr.net/npm/${pkg}@${entry.version}/umd/${pkg}.production.min.js`) invalid(`Unexpected React runtime: ${key}`);
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
const r = manifest.resources;
|
|
21
|
+
if (r.fineDesign.version !== manifest.version || r.fineDesignCss.version !== manifest.version || r.react.version !== r.reactDOM.version || r.vanAnalysis.version !== r.vanAnalysisCss.version) invalid('Runtime package versions do not match.');
|
|
22
|
+
return manifest;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
async function readRuntime(value = defaultRuntimeURL) {
|
|
26
|
+
let base;
|
|
27
|
+
try { base = new URL(value); } catch { invalid('Invalid runtime URL.'); }
|
|
28
|
+
if ((base.protocol !== 'https:' && !(base.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(base.hostname))) || base.username || base.password || base.search || base.hash) invalid('Use an HTTPS runtime URL without credentials, query or fragment; HTTP is allowed on loopback.');
|
|
29
|
+
if (!base.pathname.endsWith('/')) base.pathname += '/';
|
|
30
|
+
const manifestURL = new URL('manifest.json', base);
|
|
31
|
+
let manifest;
|
|
32
|
+
try {
|
|
33
|
+
const response = await fetch(manifestURL, { redirect: 'error', signal: AbortSignal.timeout(15000), headers: { Accept: 'application/json' } });
|
|
34
|
+
if (!response.ok) throw new Error(`HTTP ${response.status}`);
|
|
35
|
+
if (!/application\/json/i.test(response.headers.get('content-type') || '')) throw new Error('Expected JSON MIME type');
|
|
36
|
+
const chunks = []; let size = 0;
|
|
37
|
+
for await (const chunk of response.body) {
|
|
38
|
+
size += chunk.length;
|
|
39
|
+
if (size > 1024 * 1024) throw new Error('Runtime metadata exceeds 1 MB');
|
|
40
|
+
chunks.push(chunk);
|
|
41
|
+
}
|
|
42
|
+
manifest = JSON.parse(Buffer.concat(chunks).toString('utf8'));
|
|
43
|
+
} catch (error) { throw new ToolError('RUNTIME_UNAVAILABLE', `Cannot read ${manifestURL}: ${error.message}. No other version was selected.`, 1); }
|
|
44
|
+
return { runtimeURL: base.href, manifestURL: manifestURL.href, manifest: validateRuntimeManifest(manifest) };
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export async function listRuntimes(runtimeURL) {
|
|
48
|
+
const current = await readRuntime(runtimeURL);
|
|
49
|
+
return { runtimeURL: current.runtimeURL, schemaVersion: 1, versions: [current.manifest.version] };
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
export async function resolveRuntime({ version, runtimeURL }) {
|
|
53
|
+
if (!exactVersion.test(version)) throw new ToolError('INVALID_ARGUMENT', 'Specify an exact component version.', 2);
|
|
54
|
+
const current = await readRuntime(runtimeURL);
|
|
55
|
+
if (current.manifest.version !== version) throw new ToolError('RUNTIME_VERSION_NOT_FOUND', `Only Fine Design ${current.manifest.version} is currently hosted; ${version} is unavailable. Historical UMD files are not retained.`, 3, { availableVersions: [current.manifest.version] });
|
|
56
|
+
const resources = Object.fromEntries(Object.entries(current.manifest.resources).map(([key, entry]) => [key, { ...entry, url: entry.url || new URL(entry.path, current.manifestURL).href }]));
|
|
57
|
+
const tags = ['fineDesignCss', 'react', 'reactDOM', 'fineDesign'].map((key) => {
|
|
58
|
+
const entry = resources[key];
|
|
59
|
+
return entry.type === 'style' ? `<link rel="stylesheet" href="${entry.url}" integrity="${entry.integrity}" crossorigin="anonymous">` : `<script src="${entry.url}" integrity="${entry.integrity}" crossorigin="anonymous"></script>`;
|
|
60
|
+
}).join('\n');
|
|
61
|
+
return { version, docsAvailable: Object.hasOwn(readIndex().versions, version), manifestURL: current.manifestURL, exampleURL: new URL('index.html', current.runtimeURL).href, resources, tags };
|
|
62
|
+
}
|
package/src/core/version.mjs
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import fs from 'node:fs';
|
|
2
2
|
import path from 'node:path';
|
|
3
|
+
import { exactVersion } from './data.mjs';
|
|
3
4
|
import { ToolError } from './errors.mjs';
|
|
4
5
|
|
|
5
6
|
export function resolveVersion(explicit, project = process.cwd()) {
|
|
@@ -12,9 +13,18 @@ export function resolveVersion(explicit, project = process.cwd()) {
|
|
|
12
13
|
const filename = path.join(directory, 'node_modules', '@fx-ui', 'fine-design', 'package.json');
|
|
13
14
|
if (fs.existsSync(filename)) {
|
|
14
15
|
const installed = JSON.parse(fs.readFileSync(filename, 'utf8'));
|
|
15
|
-
if (installed.name === '@fx-ui/fine-design' && typeof installed.version === 'string' &&
|
|
16
|
+
if (installed.name === '@fx-ui/fine-design' && typeof installed.version === 'string' && exactVersion.test(installed.version)) return installed.version;
|
|
16
17
|
throw new ToolError('VERSION_NOT_DETECTED', 'Installed Fine Design package has no valid exact version.', 3, { suggestions: ['Specify --fd-version with an exact supported version.'] });
|
|
17
18
|
}
|
|
19
|
+
const selfFilename = path.join(directory, 'package.json');
|
|
20
|
+
if (fs.existsSync(selfFilename) && fs.statSync(selfFilename).isFile()) {
|
|
21
|
+
let selfPkg = null;
|
|
22
|
+
try { selfPkg = JSON.parse(fs.readFileSync(selfFilename, 'utf8')); } catch { selfPkg = null; }
|
|
23
|
+
if (selfPkg?.name === '@fx-ui/fine-design') {
|
|
24
|
+
if (typeof selfPkg.version === 'string' && exactVersion.test(selfPkg.version)) return selfPkg.version;
|
|
25
|
+
throw new ToolError('VERSION_NOT_DETECTED', 'Workspace Fine Design package has no valid exact version.', 3, { suggestions: ['Specify --fd-version with an exact supported version.'] });
|
|
26
|
+
}
|
|
27
|
+
}
|
|
18
28
|
const parent = path.dirname(directory);
|
|
19
29
|
if (parent === directory) break;
|
|
20
30
|
directory = parent;
|
package/src/mcp.mjs
CHANGED
|
@@ -7,24 +7,28 @@ import { queryCatalog } from './core/catalog.mjs';
|
|
|
7
7
|
import { loadCatalog } from './core/data.mjs';
|
|
8
8
|
import { schemas, validateInput } from './core/contracts.mjs';
|
|
9
9
|
import { errorResult } from './core/errors.mjs';
|
|
10
|
+
import { listRuntimes, resolveRuntime } from './core/runtime.mjs';
|
|
10
11
|
|
|
11
12
|
export async function startMcp() {
|
|
12
13
|
const packageInfo = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
|
|
13
14
|
const server = new Server({ name: 'fine-design', version: packageInfo.version }, { capabilities: { tools: {} } });
|
|
14
15
|
const descriptions = {
|
|
15
|
-
search_components: 'Search components; use nextOffset to browse subsequent pages.',
|
|
16
|
-
get_component_doc: 'Read component documentation
|
|
17
|
-
get_component_example: 'Read example source files, dependencies and
|
|
16
|
+
search_components: 'Search components, subcomponents and built-in icons; use nextOffset to browse subsequent pages.',
|
|
17
|
+
get_component_doc: 'Read component documentation, or pass summary: true to list section headings and example IDs first.',
|
|
18
|
+
get_component_example: 'Read example source files, dependencies and asset metadata. Set includeAssets to include binary base64 and oversized JSON fixture content.',
|
|
19
|
+
list_browser_runtimes: 'Read the one currently hosted UMD version from its online manifest. Requires network access.',
|
|
20
|
+
get_browser_runtime: 'Resolve an exact component version to versioned current UMD URLs and SRI loading tags. Requires network access; never falls back to another version.'
|
|
18
21
|
};
|
|
19
22
|
server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: Object.entries(schemas).map(([name, schema]) => ({
|
|
20
23
|
name, description: descriptions[name], inputSchema: z.toJSONSchema(schema, { target: 'draft-07' }),
|
|
21
|
-
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint:
|
|
24
|
+
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: name === 'get_browser_runtime' || name === 'list_browser_runtimes' }
|
|
22
25
|
})) }));
|
|
23
26
|
server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
|
24
27
|
try {
|
|
25
28
|
const { name, arguments: input } = request.params;
|
|
26
29
|
const args = validateInput(name, input);
|
|
27
|
-
|
|
30
|
+
const result = name === 'get_browser_runtime' ? await resolveRuntime(args) : name === 'list_browser_runtimes' ? await listRuntimes(args.runtimeURL) : queryCatalog(loadCatalog(args.version), name, args);
|
|
31
|
+
return { content: [{ type: 'text', text: JSON.stringify(result) }] };
|
|
28
32
|
} catch (error) {
|
|
29
33
|
return { isError: true, content: [{ type: 'text', text: JSON.stringify(errorResult(error)) }] };
|
|
30
34
|
}
|