feat(assets): port Nuxt DevTools' Assets tab as a framework-neutral plugin

Adds @devframes/plugin-assets, a Preact SPA that browses, previews,
uploads, renames, and deletes the files in a managed directory
(default <cwd>/public). Full RPC surface (list/capabilities/read-text/
read-image-meta/upload/rename/delete/mkdir/write-text/open-in-editor/
reveal-in-folder), a live chokidar-backed change broadcast, real byte
serving via ctx.views.hostStatic(), and binary uploads over devframe's
streaming-channel primitive. Preact ports the same @antfu/design class
vocabulary every other plugin uses.

Core changes in support of this:
- DevframeDefinition.capabilities.build now actually does something:
  createCac skips the build subcommand when it's false, and
  createBuild throws DF0042 for the same case unless {force: true} is
  passed. The assets plugin uses this by default since a static export
  can never carry real bytes or write actions.
- Wired into alias.ts/tsconfig.base.json/turbo.json/vitest.config.ts
  and dogfooded in examples/minimal-vite-devframe-hub.

Co-authored-by: opencode <noreply@opencode.ai>

Author: antfubot

alias.ts

@@ -105,6 +105,12 @@ export const alias = {
   '@devframes/plugin-messages/cli': p('messages/src/cli.ts'),
   '@devframes/plugin-messages/vite': p('messages/src/vite.ts'),
   '@devframes/plugin-messages': p('messages/src/index.ts'),
+  '@devframes/plugin-assets/client': p('assets/src/client/index.ts'),
+  '@devframes/plugin-assets/node': p('assets/src/node/index.ts'),
+  '@devframes/plugin-assets/rpc': p('assets/src/rpc/index.ts'),
+  '@devframes/plugin-assets/cli': p('assets/src/cli.ts'),
+  '@devframes/plugin-assets/vite': p('assets/src/vite.ts'),
+  '@devframes/plugin-assets': p('assets/src/index.ts'),
 }
 
 // update tsconfig.base.json — CSS aliases exist for Vite resolution only;

docs/.vitepress/config.ts

@@ -70,6 +70,7 @@ function pluginsItems(prefix: string) {
     { text: 'Git', link: `${prefix}/plugins/git` },
     { text: 'Terminals', link: `${prefix}/plugins/terminals` },
     { text: 'Code Server', link: `${prefix}/plugins/code-server` },
+    { text: 'Assets', link: `${prefix}/plugins/assets` },
   ] satisfies DefaultTheme.NavItemWithLink[]
 }
 

docs/errors/DF0042.md

@@ -0,0 +1,32 @@
+---
+outline: deep
+---
+
+# DF0042: Static Build Disabled By The Definition
+
+## Message
+
+> "`{id}`" declares `capabilities.build: false` — its static export is not meaningful (writes are excluded and any live-served data won't be there).
+
+## Cause
+
+`createBuild` runs unconditionally when called directly, but a definition can opt out of static export via `capabilities.build: false` — typically because the devframe is inherently live (it manages real files on disk, spawns a process, etc.) and a `mode: 'build'` export would only ever produce a broken, write-less shell of the tool. `createCac` already skips registering the `build` subcommand for such a definition; this diagnostic covers the remaining path — a caller invoking `createBuild()` directly, bypassing the CLI.
+
+## Example
+
+```ts
+// ✗ Bad — builds a devframe that opted out of static export
+await createBuild(assetsDevframe) // throws DF0042
+
+// ✓ Good — the degraded export is still useful to you
+await createBuild(assetsDevframe, { force: true })
+```
+
+## Fix
+
+- Pass `{ force: true }` to `createBuild()` if the degraded export is still useful to you.
+- Otherwise, drop `capabilities.build: false` on the definition if a static export should be supported after all.
+
+## Source
+
+- [`packages/devframe/src/adapters/build.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/build.ts) — `createBuild()` throws this when `capabilities.build` is `false` and `force` isn't set.

docs/plugins/assets.md

@@ -0,0 +1,84 @@
+---
+outline: deep
+---
+
+# Assets
+
+Browse, preview, upload, rename, and delete the files in a directory, built as a **Preact** SPA — a framework-neutral port of Nuxt DevTools' Assets tab.
+
+Package: `@devframes/plugin-assets` · framework: **Preact**
+
+## What it does
+
+Search and filter by extension, switch between a thumbnail grid (grouped by folder) and a file tree, and open a details panel with a live preview (image, video, audio, font, or text), file metadata, and ready-to-copy usage snippets (`<img>`, CSS `background-image`, `@font-face`, a download link). Drag-and-drop files to upload them, or select multiple assets to delete them together. A live file watcher keeps every connected client's listing in sync with changes made outside the UI.
+
+The standalone server requires devframe's trust handshake by default because it can read, write, and delete real files. Uploads, renames, deletes, and folder creation are enabled by default — pass `{ write: false }` (or `--read-only` on the standalone CLI) for a browse-only deployment.
+
+## Standalone
+
+```sh
+pnpx @devframes/plugin-assets             # manages <cwd>/public
+pnpx @devframes/plugin-assets --read-only # disable upload / rename / delete / mkdir
+```
+
+## Mount into a Vite host
+
+```ts
+// vite.config.ts
+import { assetsVitePlugin } from '@devframes/plugin-assets/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [
+    assetsVitePlugin(),
+  ],
+})
+```
+
+## Programmatic
+
+`createAssetsDevframe(options)` returns a definition you can deploy through any adapter:
+
+```ts
+import { createAssetsDevframe } from '@devframes/plugin-assets'
+
+export default createAssetsDevframe({
+  dir: 'static', // defaults to `<cwd>/public`
+  write: true,
+  uploadExtensions: ['png', 'jpg', 'svg', 'webp'], // defaults to Nuxt DevTools' own allow-list, or '*' for any
+})
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `dir` | `<cwd>/public` | Directory this devframe manages. |
+| `write` | `true` | Enable upload, rename, delete, and folder creation from the UI. |
+| `uploadExtensions` | Nuxt DevTools' allow-list | Extensions `upload` accepts, or `'*'` for any. |
+| `build` | `false` | Register the `build` CLI subcommand. See [why it's off by default](#static-export) below. |
+
+## RPC surface
+
+All functions are namespaced `devframes:plugin:assets:*`:
+
+| Function | Type | Notes |
+|----------|------|-------|
+| `list` | `query`, `snapshot: true` | Every file under the managed directory, with type, size, and last-modified time. |
+| `capabilities` | `query`, `snapshot: true` | Whether write actions are enabled, and the upload allow-list — lets the UI gate itself proactively. |
+| `read-image-meta` | `query` | Width, height, and orientation for an image asset. |
+| `read-text` | `query` | Truncated text content, for preview or editing. |
+| `upload` | `action` | Allocates a streaming upload slot; the client pipes the file's bytes over the paired channel. |
+| `rename` | `action` | Renames an asset within its folder, preserving its extension. |
+| `delete` | `action` | Deletes one or more assets in a single call. |
+| `mkdir` | `action` | Creates a folder, including missing parents. |
+| `write-text` | `action` | Overwrites a text asset's content in place (the details panel's inline editor). |
+| `open-in-editor` / `reveal-in-folder` | `action` | Launch the asset in your editor, or reveal its containing folder in the OS file manager. Always registered, regardless of `write`. |
+
+`upload` / `rename` / `delete` / `mkdir` / `write-text` are registered only when `write` is enabled.
+
+## Static export
+
+Every devframe's `build` CLI subcommand is disabled here by default (`capabilities: { build: false }`). Real byte serving for previews goes through `ctx.views.hostStatic()`, which only mounts real files under a live adapter (`cli` / `vite` / `embedded`) — a static export can never copy those bytes, and every write action is inherently excluded from a static dump. Rather than ship a broken, preview-less, write-less shell of the tool, the `build` command is simply not registered. Pass `{ build: true }` to `createAssetsDevframe()` (and `{ force: true }` if calling `createBuild()` directly) if that degraded export is still useful to you — the file listing itself still bakes into the static RPC dump.
+
+## Source
+
+[`plugins/assets`](https://github.com/devframes/devframe/tree/main/plugins/assets)

docs/plugins/index.md

@@ -17,10 +17,11 @@ Each plugin is built with a **different UI framework**. That is deliberate: devf
 | [Git](./git) | React (Next.js) | A repository dashboard — status, a commit graph, branches, and diffs, with optional staging and committing. |
 | [Terminals](./terminals) | Svelte | Stream read-only command output and run fully interactive PTY shells in the browser. |
 | [Code Server](./code-server) | Vue | Launch VS Code in the browser (code-server, `code serve-web`, or a tunnel) on demand and embed it in an auto-authenticated iframe. |
+| [Assets](./assets) | Preact | Browse, preview, upload, rename, and delete the files in a managed directory. |
 
 ## One client, any framework
 
-The collection spans Vue, Solid, React, and Svelte, yet every plugin shares the same node-side surface: register RPC functions, publish shared state, and connect from the browser with `connectDevframe`. Whatever renders the UI, it talks to the backend through the same protocol — the framework-free Vite hub example drives it with a handful of DOM calls.
+The collection spans Vue, Solid, React, Svelte, and Preact, yet every plugin shares the same node-side surface: register RPC functions, publish shared state, and connect from the browser with `connectDevframe`. Whatever renders the UI, it talks to the backend through the same protocol — the framework-free Vite hub example drives it with a handful of DOM calls.
 
 This is the framework-agnostic promise in practice. The browser bundle is the author's to choose; devframe handles the transport, the data model, the adapters, and the agent surface underneath.
 
@@ -32,6 +33,7 @@ Most plugins publish a `bin`, so the quickest path is `pnpx`:
 pnpx @devframes/plugin-inspect      # the Devframe Inspector, standalone
 pnpx @devframes/plugin-og           # inspect Open Graph metadata and social cards
 pnpx @devframes/plugin-git          # the Git dashboard against the current repo
+pnpx @devframes/plugin-assets       # manage the files under <cwd>/public
 ```
 
 Each also exports a `create…Devframe` factory (or, for the Accessibility Inspector, a ready-made definition) you can drive through any adapter — see the individual pages for the factory name, options, and host-mount snippets.

examples/minimal-vite-devframe-hub/package.json

@@ -16,6 +16,7 @@
     "@devframes/json-render": "workspace:*",
     "@devframes/json-render-ui": "workspace:*",
     "@devframes/plugin-a11y": "workspace:*",
+    "@devframes/plugin-assets": "workspace:*",
     "@devframes/plugin-code-server": "workspace:*",
     "@devframes/plugin-data-inspector": "workspace:*",
     "@devframes/plugin-git": "workspace:*",

examples/minimal-vite-devframe-hub/vite.config.ts

@@ -1,6 +1,7 @@
 import { mountDevframe } from '@devframes/hub/node'
 import { toJsonRenderDockEntry } from '@devframes/json-render/hub'
 import a11yDevframe, { a11yAgentBundlePath } from '@devframes/plugin-a11y'
+import assetsDevframe from '@devframes/plugin-assets'
 import codeServerDevframe from '@devframes/plugin-code-server'
 import dataInspectorDevframe from '@devframes/plugin-data-inspector'
 import { registerDataSource } from '@devframes/plugin-data-inspector/registry'
@@ -72,6 +73,7 @@ export default defineConfig({
         a11yDevframe,
         messagesDevframe,
         ogDevframe,
+        assetsDevframe,
       ],
       // Attach the a11y inspector's in-page agent as its dock's client script.
       // The hub client runtime (booted in src/client/main.ts) imports it into

packages/devframe/src/adapters/__tests__/build.test.ts

@@ -0,0 +1,63 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { defineDevframe } from '../../types/devframe'
+import { createBuild } from '../build'
+
+function makeTmpDist(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'devframe-build-test-'))
+  writeFileSync(join(dir, 'index.html'), '<!doctype html><title>test</title>', 'utf-8')
+  return dir
+}
+
+function baseDevframe(overrides: Partial<ReturnType<typeof defineDevframe>> = {}) {
+  const distDir = makeTmpDist()
+  return defineDevframe({
+    id: 'devframe-build-test',
+    name: 'Devframe Build Test',
+    version: '0.0.0',
+    packageName: 'devframe-build-test',
+    homepage: 'https://example.test',
+    description: 'Test devframe.',
+    cli: { distDir },
+    setup: () => {},
+    ...overrides,
+  })
+}
+
+describe('adapters/build', () => {
+  it('rejects a definition with capabilities.build: false by default', async () => {
+    const outDir = mkdtempSync(join(tmpdir(), 'devframe-build-test-out-'))
+    try {
+      await expect(
+        createBuild(baseDevframe({ capabilities: { build: false } }), { outDir }),
+      ).rejects.toThrow(/capabilities\.build: false/)
+    }
+    finally {
+      rmSync(outDir, { recursive: true, force: true })
+    }
+  })
+
+  it('proceeds past capabilities.build: false when force is set', async () => {
+    const outDir = mkdtempSync(join(tmpdir(), 'devframe-build-test-out-'))
+    try {
+      await expect(
+        createBuild(baseDevframe({ capabilities: { build: false } }), { outDir, force: true }),
+      ).resolves.toBeUndefined()
+    }
+    finally {
+      rmSync(outDir, { recursive: true, force: true })
+    }
+  })
+
+  it('proceeds normally when capabilities.build is unset', async () => {
+    const outDir = mkdtempSync(join(tmpdir(), 'devframe-build-test-out-'))
+    try {
+      await expect(createBuild(baseDevframe(), { outDir })).resolves.toBeUndefined()
+    }
+    finally {
+      rmSync(outDir, { recursive: true, force: true })
+    }
+  })
+})

packages/devframe/src/adapters/__tests__/cac.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest'
+import { defineDevframe } from '../../types/devframe'
+import { createCac } from '../cac'
+
+function baseDevframe(overrides: Partial<ReturnType<typeof defineDevframe>> = {}) {
+  return defineDevframe({
+    id: 'devframe-test',
+    name: 'Devframe Test',
+    version: '0.0.0',
+    packageName: 'devframe-test',
+    homepage: 'https://example.test',
+    description: 'Test devframe.',
+    setup: () => {},
+    ...overrides,
+  })
+}
+
+describe('adapters/cac', () => {
+  it('registers the build subcommand by default', () => {
+    const { cli } = createCac(baseDevframe())
+    expect(cli.commands.map(c => c.name)).toContain('build')
+  })
+
+  it('skips the build subcommand when capabilities.build is false', () => {
+    const { cli } = createCac(baseDevframe({ capabilities: { build: false } }))
+    expect(cli.commands.map(c => c.name)).not.toContain('build')
+  })
+
+  it('still registers build when capabilities.build is true or a record', () => {
+    const truthy = createCac(baseDevframe({ capabilities: { build: true } }))
+    expect(truthy.cli.commands.map(c => c.name)).toContain('build')
+
+    const record = createCac(baseDevframe({ capabilities: { build: { dump: true } } }))
+    expect(record.cli.commands.map(c => c.name)).toContain('build')
+  })
+
+  it('always registers the dev and mcp commands regardless of capabilities.build', () => {
+    const { cli } = createCac(baseDevframe({ capabilities: { build: false } }))
+    const names = cli.commands.map(c => c.name)
+    expect(names).toContain('mcp')
+    // The dev command is registered as the catch-all `[...args]` command,
+    // which cac surfaces with an empty `name`.
+    expect(cli.commands.some(c => c.rawName === '[...args]')).toBe(true)
+  })
+})

packages/devframe/src/adapters/build.ts

@@ -12,6 +12,7 @@ import {
   DEVFRAME_RPC_DUMP_MANIFEST_FILENAME,
 } from '../constants'
 import { createHostContext } from '../node/context'
+import { diagnostics } from '../node/diagnostics'
 import { createH3DevframeHost } from '../node/host-h3'
 import { collectStaticRpcDump } from '../rpc/dump/static'
 import { strictJsonStringify } from '../rpc/serialization'
@@ -34,6 +35,13 @@ export interface CreateBuildOptions {
    * minified. Set `true` when you need to diff / read the dumps by hand.
    */
   pretty?: boolean
+  /**
+   * Proceed even when the definition declares `capabilities.build: false`.
+   * `createCac` already skips registering the `build` subcommand for such
+   * a definition — this only matters for a caller invoking `createBuild`
+   * directly, bypassing the CLI.
+   */
+  force?: boolean
 }
 
 /**
@@ -50,6 +58,9 @@ export interface CreateBuildOptions {
  *     works at `/`, `/devframe/`, or any base, no rewriting required.
  */
 export async function createBuild(d: DevframeDefinition, options: CreateBuildOptions = {}): Promise<void> {
+  if (d.capabilities?.build === false && !options.force)
+    throw diagnostics.DF0042({ id: d.id })
+
   const outDir = resolve(options.outDir ?? 'dist-static')
   const distDir = options.distDir ?? d.cli?.distDir
   if (!distDir)