@finedesign/cli 0.9.0 → 0.10.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.1",
4
+ "sourceKind": "repository-snapshot",
5
+ "sourceRevision": "508ca187dd94fd821eb164f4ae045c9a38b805ca",
6
+ "sourceDirty": false,
7
+ "contentHash": "79b401f3998a2d49cae141df1f7e2627df41fe341cf53f155ef687e16377b12c",
8
+ "catalogSha256": "3845f98ba76866a89b609284ae8c0171d6f8ff3621e4ce7d9d82584350c894de",
9
+ "skillFiles": {
10
+ "references/component-guide.md": "e48d32c664034bae5cf3aaf2d8c294f99e3374645e2b8482844e79e82b8548b6",
11
+ "references/docs-slug-map.md": "440ce5cf137fd22eabfcc5b51c3f55b85174aa643773ef0cedd5df542e77bbc2",
12
+ "references/imports-and-setup.md": "cd9c8452d62bebecf2fb6a2ffd74772c673e41c3290f424d96674c3ad327bc74",
13
+ "references/theme-and-dark-mode.md": "2eccae4930ea993e7088eee03a4b4a0f1c839033079db5f21f8c60e0fe8168d1",
14
+ "SKILL.md": "e1024432c8b37d88057cfd851d40d3f1747b8b0354d12f9c4d510810757d62c8"
15
+ }
16
+ }
package/data/index.json CHANGED
@@ -8,7 +8,11 @@
8
8
  "1.25.0": {
9
9
  "catalog": "1.25.0/catalog.json",
10
10
  "manifest": "1.25.0/manifest.json"
11
+ },
12
+ "1.25.1": {
13
+ "catalog": "1.25.1/catalog.json",
14
+ "manifest": "1.25.1/manifest.json"
11
15
  }
12
16
  },
13
- "skillVersion": "1.25.0"
17
+ "skillVersion": "1.25.1"
14
18
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@finedesign/cli",
3
- "version": "0.9.0",
3
+ "version": "0.10.0",
4
4
  "description": "Versioned Fine Design docs, code checks and agent setup for coding agents",
5
5
  "license": "MIT",
6
6
  "publishConfig": {
@@ -49,18 +49,15 @@ Use browser/CDN mode for standalone pages, embedded pages and previews without a
49
49
 
50
50
  ### Select Resources
51
51
 
52
- Run `npx -y @finedesign/cli runtime list --format json` first and check its exit code. Use a version from its `versions` result with `npx -y @finedesign/cli runtime --fd-version <exact-version> --format html > demo.html` for a standalone starting page, or `--format json` for resources (MCP: `list_browser_runtimes` / `get_browser_runtime`). Use `--runtime-url` only 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. If discovery fails, report the actual error instead of guessing asset URLs or repeatedly probing unrelated packages.
52
+ Run `npx -y @finedesign/cli runtime list --format json` first and check its exit code. Use a version from its `versions` result with `npx -y @finedesign/cli runtime --fd-version <exact-version> --format html > demo.html` for a standalone starting page, or `--format json` for resources (MCP: `list_browser_runtimes` / `get_browser_runtime`). Use `--runtime-url` only for an explicitly selected preview.
53
53
 
54
- 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.
55
- 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.
56
- 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.
57
- 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.
54
+ The public npm package `@finedesign/runtime` contains the UMD script, stylesheet and manifest. Discovery reads the latest manifest. For a known published version use `https://cdn.jsdelivr.net/npm/@finedesign/runtime@<exact-version>/manifest.json`. Resolve resource paths relative to that exact manifest and preserve the supplied URLs, hashes and SRI. If a requested version is unavailable, report the error or use matching previously saved resources.
58
55
 
59
56
  For offline or CSP-restricted previews, use `fine-design runtime --fd-version <exact-version> --output ./demo` with a new destination directory. `--dry-run --format json` previews file paths. The export verifies sizes/SHA-256 before writing local resources, preserves SRI and records their remote provenance in `runtime-lock.json`. Initial export needs network access; subsequent pages reference only local resources. The host must still permit page scripts/styles. Existing destinations are rejected rather than overwritten.
60
57
 
61
58
  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.
62
59
 
63
- 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
+ Use `--runtime-url <verified-base-url>` for an explicitly selected alternative host. Use the VanChart skill for chart resources.
64
61
 
65
62
  ### Mount And Verify
66
63
 
@@ -76,4 +73,4 @@ ReactDOM.createRoot(document.getElementById('root')).render(
76
73
  );
77
74
  ```
78
75
 
79
- 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`.
76
+ Run `npm run build:public-assets` to build the production npm runtime tarball. See `tools/fine-design/README.md` for publishing and verification.
package/src/cli.mjs CHANGED
@@ -36,7 +36,7 @@ Options:
36
36
  --output <directory> Destination for an example or offline runtime (add and runtime)
37
37
  --force Update managed files or overwrite examples (init and add)
38
38
  --dry-run Preview changes without writing (init, add and runtime --output)
39
- --runtime-url <url> Runtime hosting base URL (runtime command only)
39
+ --runtime-url <url> Runtime hosting base URL or npm (runtime command only)
40
40
  --format <text|json|markdown|html> Output format (markdown: doc/info/token/figma; html: runtime)
41
41
  --section <heading> Doc section heading (exact or case-insensitive)
42
42
  --toc, --summary Show only doc metadata, section headings and example IDs
@@ -519,7 +519,7 @@ export async function main(argv) {
519
519
  console.log(format === 'json' ? JSON.stringify(report) : `${report.dryRun ? 'Preview' : 'Exported'} Fine Design ${report.version} to ${report.targetDir}:\n${report.plannedFiles.map((name) => ` ${name}`).join('\n')}`);
520
520
  return;
521
521
  }
522
- 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}`);
522
+ 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}${result.exampleURL ? `\nExample: ${result.exampleURL}` : ''}`);
523
523
  return;
524
524
  }
525
525
  if (command === 'doctor') {
@@ -4,31 +4,35 @@ import { exactVersion, readIndex, sha256 } from './data.mjs';
4
4
  import { ToolError } from './errors.mjs';
5
5
  import html from './html.cjs';
6
6
 
7
- export const defaultRuntimeURL = 'https://fine-design-runtime.pages.dev/';
7
+ const defaultRuntimeURL = 'npm';
8
+ const npmRuntime = '@finedesign/runtime';
8
9
  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'] };
9
10
  const requiredResources = ['fineDesignCss', 'react', 'reactDOM', 'fineDesign'];
10
11
  const invalid = (message) => { throw new ToolError('RUNTIME_INVALID', message, 1); };
11
12
 
12
13
  export function validateRuntimeManifest(manifest) {
13
- 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.');
14
+ const packaged = manifest?.package === npmRuntime;
15
+ const expected = packaged ? [...requiredResources] : ['react', 'reactDOM', ...Object.keys(hosted)];
16
+ if (manifest?.schemaVersion !== 1 || !exactVersion.test(manifest.version) || !manifest.resources || Object.keys(manifest.resources).sort().join(',') !== expected.sort().join(',')) invalid('Invalid current runtime manifest.');
14
17
  for (const [key, entry] of Object.entries(manifest.resources)) {
15
18
  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}`);
16
19
  if (hosted[key]) {
17
20
  const [pkg, directory, filename] = hosted[key];
18
- if (entry.package !== pkg || entry.path !== `${directory}/${entry.version}/${filename}` || entry.url) invalid(`Unexpected versioned resource path: ${key}`);
21
+ const expectedPath = packaged ? filename : `${directory}/${entry.version}/${filename}`;
22
+ if (entry.package !== pkg || entry.path !== expectedPath || entry.url) invalid(`Unexpected versioned resource path: ${key}`);
19
23
  } else {
20
24
  const pkg = key === 'react' ? 'react' : 'react-dom';
21
25
  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}`);
22
26
  }
23
27
  }
24
28
  const r = manifest.resources;
25
- 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.');
29
+ if (r.fineDesign.version !== manifest.version || r.fineDesignCss.version !== manifest.version || r.react.version !== r.reactDOM.version || (!packaged && r.vanAnalysis.version !== r.vanAnalysisCss.version)) invalid('Runtime package versions do not match.');
26
30
  return manifest;
27
31
  }
28
32
 
29
- async function readRuntime(value = defaultRuntimeURL) {
33
+ async function readRuntime(value = defaultRuntimeURL, version) {
30
34
  let base;
31
- try { base = new URL(value); } catch { invalid('Invalid runtime URL.'); }
35
+ try { base = new URL(value === 'npm' ? `https://cdn.jsdelivr.net/npm/${npmRuntime}@${version || 'latest'}/` : value); } catch { invalid('Invalid runtime URL.'); }
32
36
  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.');
33
37
  if (!base.pathname.endsWith('/')) base.pathname += '/';
34
38
  const manifestURL = new URL('manifest.json', base);
@@ -50,7 +54,9 @@ async function readRuntime(value = defaultRuntimeURL) {
50
54
  suggestions: ['Check access to the manifest from this environment or pass --runtime-url with a verified host.']
51
55
  });
52
56
  }
53
- return { runtimeURL: base.href, manifestURL: manifestURL.href, manifest: validateRuntimeManifest(manifest) };
57
+ validateRuntimeManifest(manifest);
58
+ if (value === 'npm' && manifest.package !== npmRuntime) invalid('Expected the public npm runtime manifest.');
59
+ return { runtimeURL: base.href, manifestURL: manifestURL.href, manifest };
54
60
  }
55
61
 
56
62
  export async function listRuntimes(runtimeURL) {
@@ -60,15 +66,20 @@ export async function listRuntimes(runtimeURL) {
60
66
 
61
67
  export async function resolveRuntime({ version, runtimeURL }) {
62
68
  if (version !== undefined && !exactVersion.test(version)) throw new ToolError('INVALID_ARGUMENT', 'Specify an exact component version.', 2);
63
- const current = await readRuntime(runtimeURL);
69
+ if (!version && (runtimeURL ?? defaultRuntimeURL) === 'npm') {
70
+ const { versions } = await listRuntimes('npm');
71
+ version = versions[0];
72
+ }
73
+ const current = await readRuntime(runtimeURL, version);
64
74
  const targetVersion = version || current.manifest.version;
65
- if (current.manifest.version !== targetVersion) throw new ToolError('RUNTIME_VERSION_NOT_FOUND', `Only Fine Design ${current.manifest.version} is currently hosted; ${targetVersion} is unavailable. Historical UMD files are not retained.`, 3, { availableVersions: [current.manifest.version] });
75
+ if (current.manifest.version !== targetVersion) throw new ToolError('RUNTIME_VERSION_NOT_FOUND', `The runtime manifest contains Fine Design ${current.manifest.version}; requested ${targetVersion}.`, 3, { availableVersions: [current.manifest.version] });
66
76
  const resources = Object.fromEntries(Object.entries(current.manifest.resources).map(([key, entry]) => [key, { ...entry, url: entry.url || new URL(entry.path, current.manifestURL).href }]));
67
77
  const tags = requiredResources.map((key) => {
68
78
  const entry = resources[key];
69
79
  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>`;
70
80
  }).join('\n');
71
- return { version: targetVersion, docsAvailable: Object.hasOwn(readIndex().versions, targetVersion), manifestURL: current.manifestURL, exampleURL: new URL('index.html', current.runtimeURL).href, resources, tags };
81
+ const example = current.manifest.package === npmRuntime ? {} : { exampleURL: new URL('index.html', current.runtimeURL).href };
82
+ return { version: targetVersion, docsAvailable: Object.hasOwn(readIndex().versions, targetVersion), manifestURL: current.manifestURL, ...example, resources, tags };
72
83
  }
73
84
 
74
85
  export async function exportRuntime(runtime, output, dryRun = false) {