feat(devframe): remote client assets — serve SPA dists through a caching CDN back-proxy (#236)

* feat(devframe): remote client assets — serve SPA dists through a caching CDN back-proxy

Every static-assets seam (cli.distDir, hostStatic, mountStatic, the
serve-static engine) now accepts a version-locked RemoteAssets
declaration ({ package, version }) alongside a local directory, so a
plugin's browser bundle can live in its own npm package instead of
shipping inside the node tarball.

Resolution order per request: a locally installed copy of the assets
package (resolved from the declaration's resolveFrom, warning on
minor/patch skew and rejecting a major mismatch), the per-file cache
under <project storage>/.remote-assets/<pkg>@<version>/, then the CDN
provider (jsdelivr by default, unpkg or a custom mirror via provider) —
streaming through to the browser while teeing into the cache. Request
paths resolve against the provider's file listing (correct 404s and SPA
fallback), degrading to per-file probing when the listing is
unreachable. HTML navigations that cannot be satisfied get a styled
error page pointing at the local-install fix; static builds materialize
the full file set so their output stays self-contained.

New diagnostics DF0058–DF0063 cover listing/fetch/cache/materialization
failures and version skew, each with a docs page.

* refactor(devframe): shrink remote-assets surface and LOC

Collapse the remote-assets module's public API from eight exports to one
(resolveStaticAssetsSource) — cache-path helpers, createRemoteAssetsStore,
resolveInstalledRemoteAssets, and the store options interfaces are now
private, and the error page moves into serve-static as an internal helper.

resolveStaticAssetsSource takes the project storage dir directly (dropping
the options object), so every call site loses the cacheRoot plumbing; the
build adapter reuses it too instead of hand-rolling install/materialize.

RemoteAssetsStore.serve now returns a web Response, letting serve-static
drop the RemoteAssetsServedFile / RemoteAssetsServeOptions types and the
bespoke miss/stream/cancel handling. Net ~370 fewer lines.

* test(devframe): normalize path separators in remote-assets install tests

The installed-package resolution returns pathe (forward-slash) paths, but
the tests built the expected distDir with node:path — backslashes on
Windows — so the equality assertions failed only on windows-latest.
Compare both sides normalized to forward slashes.

* feat(devframe): validate remote-assets package name and version

A remote source's `package` and `version` are interpolated into CDN URLs
and the on-disk cache path, so `resolveStaticAssetsSource` now rejects a
value that isn't a valid npm package name / exact semver version (new
`DF0065`) — closing off malformed URLs and cache-path traversal (e.g. a
`..` version segment).

Author: antfu

alias.ts

@@ -30,6 +30,7 @@ export const alias = {
   'devframe/utils/launch-editor': r('devframe/src/utils/launch-editor.ts'),
   'devframe/utils/nanoid': r('devframe/src/utils/nanoid.ts'),
   'devframe/utils/open': r('devframe/src/utils/open.ts'),
+  'devframe/utils/remote-assets': r('devframe/src/utils/remote-assets.ts'),
   'devframe/utils/simple-schema': r('devframe/src/utils/simple-schema.ts'),
   'devframe/utils/serve-static': r('devframe/src/utils/serve-static.ts'),
   'devframe/utils/shared-state': r('devframe/src/utils/shared-state.ts'),

docs/errors/DF0059.md

@@ -0,0 +1,39 @@
+---
+outline: deep
+---
+
+# DF0059: Remote Assets File Listing Failed
+
+## Message
+
+> Failed to fetch the file listing for "`{package}`@`{version}`" from `{provider}`: `{reason}`
+
+## Cause
+
+A remote-assets source (`{ package, version }` passed where a static mount accepts a dist directory) resolves request paths against the CDN provider's file-listing API — `data.jsdelivr.com` for jsDelivr, `?meta` for unpkg, or a custom provider's `listFiles`. That listing request failed, typically because the provider is unreachable (offline machine, blocked domain) or returned an error status.
+
+## Example
+
+```ts
+defineDevframe({
+  cli: {
+    distDir: {
+      package: '@devframes/plugin-git-client',
+      version: '1.2.3',
+    },
+  },
+})
+```
+
+Starting this devframe without network access to `data.jsdelivr.com` reports `DF0059` on the first request.
+
+## Fix
+
+Requests keep working in a degraded probe mode (each candidate path is tried against the provider directly). To resolve it:
+
+- Check network access to the configured provider, or switch providers (`provider: 'unpkg'` or a custom mirror).
+- Install the assets package locally (`npm install <package>`) — a locally installed copy is served with zero network and needs no listing.
+
+## Source
+
+- [`packages/devframe/src/utils/remote-assets.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/utils/remote-assets.ts) — `createRemoteAssetsStore()` reports this (once per store) when the provider's file listing cannot be fetched or parsed.

docs/errors/DF0060.md

@@ -0,0 +1,37 @@
+---
+outline: deep
+---
+
+# DF0060: Remote Asset Fetch Failed
+
+## Message
+
+> Failed to fetch a remote asset of "`{package}`" (`{url}`): `{reason}`
+
+## Cause
+
+A file of a remote-assets source was requested that is neither in the locally installed assets package nor in the on-disk cache, and streaming it through the CDN provider failed — the network request errored, the provider returned a non-OK status, or the source is `offline: true` while the file is missing from the cache.
+
+## Example
+
+```ts
+defineDevframe({
+  cli: {
+    distDir: {
+      package: '@devframes/plugin-git-client',
+      version: '1.2.3',
+    },
+  },
+})
+```
+
+Opening the tool's UI with `cdn.jsdelivr.net` unreachable throws `DF0060` for each uncached file; HTML navigations respond with a styled error page carrying this code.
+
+## Fix
+
+- Install the assets package locally (`npm install <package>`) to serve it with zero network — the recommended path for offline and air-gapped machines.
+- Otherwise check network access to the configured provider, or point `provider` at a reachable mirror.
+
+## Source
+
+- [`packages/devframe/src/utils/remote-assets.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/utils/remote-assets.ts) — `createRemoteAssetsStore()`'s `serve()` throws this when a provider fetch fails, returns a non-OK status, or an `offline` store misses its cache.

docs/errors/DF0061.md

@@ -0,0 +1,43 @@
+---
+outline: deep
+---
+
+# DF0061: Installed Assets Package Major Version Mismatch
+
+## Message
+
+> The locally installed "`{package}`@`{installed}`" is a different major version than the required "`{required}`".
+
+## Cause
+
+A remote-assets source found a locally installed copy of its assets package (resolved from the declaration's `resolveFrom` module), but the installed version differs from the declared one by a **major** version. Assets and node code are published in lockstep; across a major boundary the served UI can be incompatible with its node backend, so devframe refuses to serve it.
+
+## Example
+
+```ts
+defineDevframe({
+  cli: {
+    distDir: {
+      package: '@devframes/plugin-git-client',
+      version: '2.0.0',
+      resolveFrom: import.meta.url,
+    },
+  },
+})
+```
+
+With `@devframes/plugin-git-client@1.9.0` installed locally, mounting this devframe throws `DF0061`.
+
+## Fix
+
+Install the assets package at the version its node package declares (they are published in lockstep):
+
+```sh
+npm install @devframes/plugin-git-client@2.0.0
+```
+
+Or uninstall the stale local copy so the assets stream from the CDN back-proxy at the exact declared version.
+
+## Source
+
+- [`packages/devframe/src/utils/remote-assets.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/utils/remote-assets.ts) — `resolveInstalledRemoteAssets()` throws this when the installed package's major version differs from the declared one.

docs/errors/DF0062.md

@@ -0,0 +1,31 @@
+---
+outline: deep
+---
+
+# DF0062: Installed Assets Package Version Skew
+
+## Message
+
+> The locally installed "`{package}`@`{installed}`" differs from the required "`{required}`" — serving the installed one.
+
+## Cause
+
+A remote-assets source found a locally installed copy of its assets package whose version differs from the declared one within the same major version. The local install wins — it keeps offline and air-gapped setups working — but the served assets are not byte-identical to the declared release, so the skew is surfaced.
+
+## Example
+
+With the node package declaring `version: '1.2.3'` and `@devframes/plugin-git-client@1.2.4` installed locally, the installed `1.2.4` assets are served and `DF0062` is reported.
+
+## Fix
+
+Install the exact declared version to serve byte-identical assets:
+
+```sh
+npm install @devframes/plugin-git-client@1.2.3
+```
+
+A major-version mismatch is rejected instead — see [DF0061](./DF0061.md).
+
+## Source
+
+- [`packages/devframe/src/utils/remote-assets.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/utils/remote-assets.ts) — `resolveInstalledRemoteAssets()` reports this when the installed version differs from the declared one within the same major.

docs/errors/DF0063.md

@@ -0,0 +1,23 @@
+---
+outline: deep
+---
+
+# DF0063: Remote Asset Cache Write Failed
+
+## Message
+
+> Failed to persist a remote asset into the cache at "`{filepath}`": `{reason}`
+
+## Cause
+
+A remote asset streamed through the CDN back-proxy to the browser, but writing the teed copy into the local cache directory (`<project storage>/.remote-assets/<package>@<version>/…`) failed — usually a permissions problem, a full disk, or a removed `node_modules`.
+
+The response itself was served; only caching failed, so the same file will stream through the provider again on the next request.
+
+## Fix
+
+Check that the project storage directory (conventionally `node_modules/.<app>/devframe/`) is writable and has free space.
+
+## Source
+
+- [`packages/devframe/src/utils/remote-assets.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/utils/remote-assets.ts) — `createRemoteAssetsStore()`'s background cache write reports this when persisting a fetched file fails.

docs/errors/DF0064.md

@@ -0,0 +1,30 @@
+---
+outline: deep
+---
+
+# DF0064: Remote Assets Materialization Failed
+
+## Message
+
+> Failed to materialize the remote assets of "`{package}`@`{version}`": `{reason}`
+
+## Cause
+
+A static build (`createBuild`) with a remote-assets `distDir` needs every asset file up front — the output must be self-contained. Materialization walks the provider's file listing and downloads each file, and one of those steps failed: the provider has no `listFiles` (custom providers may omit it), the listing request failed, or an individual file download errored.
+
+## Example
+
+```sh
+my-tool build
+```
+
+Running a static build on a machine without network access to the CDN provider — and without the assets package installed locally — throws `DF0064`.
+
+## Fix
+
+- Install the assets package locally (`npm install <package>@<version>`) — builds copy from the local install and touch no network.
+- Otherwise ensure the provider and its file-listing API are reachable during the build, or configure a custom provider that implements `listFiles`.
+
+## Source
+
+- [`packages/devframe/src/utils/remote-assets.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/utils/remote-assets.ts) — `createRemoteAssetsStore()`'s `materialize()` throws this when the file listing is unavailable or a download fails.

docs/errors/DF0065.md

@@ -0,0 +1,45 @@
+---
+outline: deep
+---
+
+# DF0065: Invalid Remote Assets Package Or Version
+
+## Message
+
+> Invalid remote-assets `{field}` "`{value}`".
+
+## Cause
+
+A remote-assets source's `package` and `version` are interpolated into CDN URLs (`https://cdn.jsdelivr.net/npm/<package>@<version>/…`) and into the on-disk cache path (`.remote-assets/<package>@<version>/`). To keep those safe and well-formed, the `package` must be a valid npm package name and the `version` an exact semver version — a value carrying path separators, `@`, whitespace, or traversal segments (`..`) is rejected.
+
+## Example
+
+```ts
+defineDevframe({
+  cli: {
+    distDir: {
+      package: '@devframes/plugin-git-client',
+      version: '../etc', // ✗ not a semver version
+    },
+  },
+})
+```
+
+## Fix
+
+Use a valid npm package name and an exact version:
+
+```ts
+defineDevframe({
+  cli: {
+    distDir: {
+      package: '@devframes/plugin-git-client',
+      version: '1.2.3',
+    },
+  },
+})
+```
+
+## Source
+
+- [`packages/devframe/src/utils/remote-assets.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/utils/remote-assets.ts) — `resolveStaticAssetsSource()` validates a remote source before resolving it.

examples/files-inspector/tests/_utils.ts

@@ -60,6 +60,8 @@ export async function startInspectorServer(
   { cwd }: { cwd: string },
 ): Promise<InspectorServer> {
   const distDir = devframe.cli!.distDir!
+  if (typeof distDir !== 'string')
+    throw new TypeError('these tests serve the local dist directory — build the SPA first')
   const basePath = devframe.basePath!
   const host = '127.0.0.1'
   const port = await getPort({ host, random: true })

examples/next-runtime-snapshot/tests/_utils.ts

@@ -24,6 +24,8 @@ export interface SnapshotServer extends StartedServer {
  */
 export async function startSnapshotServer(): Promise<SnapshotServer> {
   const distDir = devframe.cli!.distDir!
+  if (typeof distDir !== 'string')
+    throw new TypeError('these tests serve the local dist directory — build the SPA first')
   const basePath = devframe.basePath!
   const host = '127.0.0.1'
   const port = await getPort({ host, random: true })