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.

Author: antfubot

packages/devframe/src/adapters/build.ts

@@ -5,7 +5,7 @@ import { existsSync } from 'node:fs'
 import fs from 'node:fs/promises'
 import process from 'node:process'
 import { colors as c } from 'devframe/utils/colors'
-import { createRemoteAssetsStore, remoteAssetsCacheDir, remoteAssetsCacheRoot, resolveInstalledRemoteAssets } from 'devframe/utils/remote-assets'
+import { resolveStaticAssetsSource } from 'devframe/utils/remote-assets'
 import { structuredCloneStringify } from 'devframe/utils/structured-clone'
 import { dirname, resolve } from 'pathe'
 import {
@@ -70,28 +70,17 @@ export async function createBuild(d: DevframeDefinition, options: CreateBuildOpt
 
   const host = createH3DevframeHost({ origin: 'http://localhost', appName: d.id })
 
-  // Copy author's SPA into the output root. A remote-assets source copies
-  // from the locally installed assets package when present, otherwise every
-  // listed file is materialized from the provider — a static deploy must be
-  // self-contained.
-  if (typeof distSource === 'string') {
-    console.log(c.cyan`[devframe] copying SPA from ${distSource} -> ${outDir}`)
-    await fs.cp(distSource, outDir, { recursive: true })
+  // A static deploy must be self-contained: a local dir (or a remote source
+  // backed by a locally installed package) is copied; an uninstalled remote
+  // source materializes every listed file from the provider.
+  const resolved = resolveStaticAssetsSource(distSource, host.getStorageDir('project'))
+  if (typeof resolved === 'string') {
+    console.log(c.cyan`[devframe] copying SPA from ${resolved} -> ${outDir}`)
+    await fs.cp(resolved, outDir, { recursive: true })
   }
   else {
-    const installed = resolveInstalledRemoteAssets(distSource)
-    if (installed) {
-      console.log(c.cyan`[devframe] copying SPA from ${installed} -> ${outDir}`)
-      await fs.cp(installed, outDir, { recursive: true })
-    }
-    else {
-      console.log(c.cyan`[devframe] materializing SPA from ${distSource.package}@${distSource.version} -> ${outDir}`)
-      const cacheRoot = remoteAssetsCacheRoot(host.getStorageDir('project'))
-      const store = createRemoteAssetsStore(distSource, {
-        cacheDir: remoteAssetsCacheDir(cacheRoot, distSource),
-      })
-      await store.materialize(outDir)
-    }
+    console.log(c.cyan`[devframe] materializing SPA from ${resolved.assets.package}@${resolved.assets.version} -> ${outDir}`)
+    await resolved.materialize(outDir)
   }
 
   const ctx = await createHostContext({

packages/devframe/src/adapters/initiate.ts

@@ -9,7 +9,7 @@ import type { InstanceShellInternals, StartedServer } from '../node/instance-she
 import type { DevframeDefinition, DevframeSetupInfo, DevframeSseOptions, DevframeWsOptions, McpRouteOptions } from '../types/devframe'
 import type { StaticAssetsSource } from '../types/remote-assets'
 import process from 'node:process'
-import { remoteAssetsCacheRoot, resolveStaticAssetsSource } from 'devframe/utils/remote-assets'
+import { resolveStaticAssetsSource } from 'devframe/utils/remote-assets'
 import { mountStaticHandler } from 'devframe/utils/serve-static'
 import { H3 } from 'h3'
 import { resolve } from 'pathe'
@@ -332,9 +332,7 @@ export function initDevframe(
       app.use(joinURL(base, DEVFRAME_CONNECTION_META_FILENAME), () => meta)
 
       if (distDir) {
-        const source = resolveStaticAssetsSource(distDir, {
-          cacheRoot: remoteAssetsCacheRoot(context.host.getStorageDir('project')),
-        })
+        const source = resolveStaticAssetsSource(distDir, context.host.getStorageDir('project'))
         mountStaticHandler(app, base, typeof source === 'string' ? resolve(source) : source)
       }
     },

packages/devframe/src/node/host-views.ts

@@ -1,6 +1,6 @@
 import type { DevframeNodeContext, DevframeViewHost as DevframeViewHostType, StaticAssetsSource } from 'devframe/types'
 import { existsSync } from 'node:fs'
-import { remoteAssetsCacheRoot, resolveStaticAssetsSource } from 'devframe/utils/remote-assets'
+import { resolveStaticAssetsSource } from 'devframe/utils/remote-assets'
 import { diagnostics } from './diagnostics'
 
 export class DevframeViewHost implements DevframeViewHostType {
@@ -18,9 +18,7 @@ export class DevframeViewHost implements DevframeViewHostType {
     // Local directories must exist up front; remote declarations resolve to
     // a locally installed package when present, otherwise to a lazy CDN
     // back-proxy store — nothing to check on disk yet.
-    const resolved = resolveStaticAssetsSource(source, {
-      cacheRoot: remoteAssetsCacheRoot(this.context.host.getStorageDir('project')),
-    })
+    const resolved = resolveStaticAssetsSource(source, this.context.host.getStorageDir('project'))
     if (typeof resolved === 'string' && !existsSync(resolved)) {
       throw diagnostics.DF0008({ distDir: resolved })
     }

packages/devframe/src/types/remote-assets.ts

@@ -84,46 +84,22 @@ export type StaticAssetsSource = string | RemoteAssets
 
 /**
  * A resolved, servable handle over a {@link RemoteAssets} declaration —
- * created by `createRemoteAssetsStore()` (`devframe/utils/remote-assets`)
+ * produced by `resolveStaticAssetsSource()` (`devframe/utils/remote-assets`)
  * and consumed by the static-serving engine (`devframe/utils/serve-static`).
  */
 export interface RemoteAssetsStore {
-  readonly kind: 'remote-assets-store'
   /** The declaration this store serves (with defaults applied). */
   readonly assets: RemoteAssets & { path: string }
-  /** Version-locked cache directory files are persisted under. */
-  readonly cacheDir: string
   /**
-   * Resolve a request path (relative to the mount base) and open the file:
-   * from the cache when present, otherwise streamed through the provider
-   * while being written into the cache. Returns `null` for a miss (404)
-   * and throws on provider/network failure.
+   * Resolve a request path (relative to the mount base, SPA fallback to
+   * `index.html`) and return a `Response`: streamed from the cache when
+   * present, otherwise through the provider while being written into the
+   * cache. `null` on a miss (404); throws on provider/network failure.
    */
-  serve: (urlPath: string, options?: RemoteAssetsServeOptions) => Promise<RemoteAssetsServedFile | null>
+  serve: (urlPath: string) => Promise<Response | null>
   /**
    * Download every listed file under `assets.path` into `targetDir`
    * (paths relative to `assets.path`). Requires a provider file listing.
    */
   materialize: (targetDir: string) => Promise<void>
 }
-
-/** Request-resolution options for {@link RemoteAssetsStore.serve}. */
-export interface RemoteAssetsServeOptions {
-  /** Default: `['index.html']`. */
-  indexNames?: string[]
-  /** SPA fallback to `indexNames[0]` on miss. Default: `true`. */
-  single?: boolean
-}
-
-/** An opened file ready to respond with. */
-export interface RemoteAssetsServedFile {
-  /** Response headers (`Content-Type`, `Content-Length` when known, …). */
-  headers: Record<string, string>
-  /** Response body. Call at most once. */
-  stream: () => ReadableStream<Uint8Array>
-  /**
-   * Release the file when the body will never be read (HEAD requests) —
-   * an in-flight provider download keeps filling the cache.
-   */
-  cancel: () => void
-}