@devframes/plugin-assets 0.7.15

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Anthony Fu <https://github.com/antfu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# `@devframes/plugin-assets`
+
+Browse, preview, upload, rename, and delete the files in a directory — a framework-neutral port of Nuxt DevTools' Assets tab, built as a **Vue** SPA on `@antfu/design`.
+
+```sh
+pnpx @devframes/plugin-assets
+```
+
+Manages `<cwd>/public` by default. The package exports `createAssetsDevframe()` for custom definitions and `assetsVitePlugin()` from `@devframes/plugin-assets/vite` for Vite hosts. Pass `{ dir }` to manage a different directory, `{ baseURL }` to match where the host serves it, or `{ write: false }` (`--read-only` on the standalone CLI) for a browse-only deployment.
+
+Asset previews load files by their public URL, served by the host the plugin is mounted into (Vite/Nuxt/etc. already serve `public/` at `/`) — the plugin doesn't serve the bytes itself. The standalone CLI is its own host, so it serves the directory for you.
+
+The standalone server requires devframe's trust handshake by default because it can read, write, and delete real files. The `build` CLI subcommand is disabled by default — see the docs page for why.

package/bin.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import process from 'node:process'
+import { createAssetsCli } from './dist/cli.mjs'
+
+async function main() {
+  await createAssetsCli().parse()
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/dist/cli.d.mts

@@ -0,0 +1,5 @@
+import { CacHandle } from "devframe/adapters/cac";
+//#region src/cli.d.ts
+declare function createAssetsCli(): CacHandle;
+//#endregion
+export { createAssetsCli };

package/dist/cli.mjs

@@ -0,0 +1,8 @@
+import { n as createAssetsDevframe } from "./src-DuJ-iEes.mjs";
+import { createCac } from "devframe/adapters/cac";
+//#region src/cli.ts
+function createAssetsCli() {
+	return createCac(createAssetsDevframe({ serveStatic: true }));
+}
+//#endregion
+export { createAssetsCli };

package/dist/client/index.d.mts

@@ -0,0 +1,6 @@
+import { i as CodeSnippet, n as AssetInfo, r as AssetType, t as AssetImageMeta } from "../types-DPDOYVFh.mjs";
+import { DevframeRpcClientOptions } from "devframe/client";
+//#region src/client/index.d.ts
+declare function connectAssets(options?: DevframeRpcClientOptions): Promise<import("devframe/client").DevframeRpcClient>;
+//#endregion
+export { type AssetImageMeta, type AssetInfo, type AssetType, type CodeSnippet, connectAssets };

package/dist/client/index.mjs

@@ -0,0 +1,7 @@
+import { connectDevframe } from "devframe/client";
+//#region src/client/index.ts
+function connectAssets(options) {
+	return connectDevframe(options);
+}
+//#endregion
+export { connectAssets };

package/dist/index.d.mts

@@ -0,0 +1,80 @@
+import { a as DEFAULT_ALLOWED_UPLOAD_EXTENSIONS, i as CodeSnippet, n as AssetInfo, r as AssetType, t as AssetImageMeta } from "./types-DPDOYVFh.mjs";
+import { DevframeDefinition } from "devframe/types";
+//#region src/index.d.ts
+interface AssetsDevframeOptions {
+  id?: string;
+  name?: string;
+  icon?: string;
+  /**
+   * Directory this devframe manages. Defaults to `<cwd>/public` — the
+   * conventional static-asset folder for Nuxt, Vite, and most static-site
+   * frameworks. Pass an absolute path, or one relative to the devframe's
+   * own `cwd`.
+   */
+  dir?: string;
+  /**
+   * URL base the **host** serves the managed directory at, used to build
+   * each asset's `publicPath`. Defaults to `/` — Vite, Nuxt, and most
+   * frameworks serve their `public/` folder at the site root. Set this to
+   * match a non-root deployment base (e.g. Nuxt's `app.baseURL`).
+   */
+  baseURL?: string;
+  /**
+   * Serve the managed directory's bytes from this devframe itself.
+   * Defaults to `false`: when mounted into a host (Vite/Nuxt/…) that host
+   * already serves `public/` at {@link baseURL}, so the plugin references
+   * those URLs instead of standing up its own route. The standalone CLI
+   * sets this to `true` (it is its own host), serving the directory under
+   * a dedicated base so it doesn't collide with the SPA at `/`.
+   */
+  serveStatic?: boolean;
+  basePath?: string;
+  distDir?: string;
+  /** Preferred standalone CLI port (default 9015). */
+  port?: number;
+  /**
+   * Enable upload, rename, delete, and folder creation from the UI.
+   * Enabled by default — set `false` (or pass `--read-only` on the
+   * standalone CLI) for a browse-only deployment.
+   */
+  write?: boolean;
+  /**
+   * Extensions `upload` accepts, or `'*'` to accept any file. Defaults to
+   * the same allow-list Nuxt DevTools ships.
+   */
+  uploadExtensions?: readonly string[] | '*';
+  /**
+   * Watch the managed directory in dev mode and push live listing updates.
+   * Enabled by default. Set `false` to skip the file watcher — useful when a
+   * host mounts the devframe in a short-lived or repeatedly-recreated
+   * context (tests, some SSR dev servers) where a background watcher isn't
+   * wanted.
+   */
+  watch?: boolean;
+  /**
+   * Require the trust handshake on the standalone server. Enabled by
+   * default — this devframe can read, write, and delete real files.
+   */
+  auth?: boolean;
+  /**
+   * Register the `build` CLI subcommand. Disabled by default: a static
+   * export can only ever list file metadata from a baked snapshot — there
+   * is no live host serving the files, and every write action is inherently
+   * excluded from a static dump — so the command would produce a broken,
+   * write-less shell of the tool. Opt back in if that degraded export is
+   * still useful to you.
+   */
+  build?: boolean;
+}
+/**
+ * Create the assets manager devframe — a framework-neutral port of Nuxt
+ * DevTools' Assets tab. Mount it into any host via devframe's adapters, or
+ * run it standalone with the bundled CLI (`devframe-assets`).
+ *
+ * @experimental This plugin is experimental and may change without a major
+ * version bump until it stabilizes.
+ */
+declare function createAssetsDevframe(options?: AssetsDevframeOptions): DevframeDefinition;
+declare const assetsDevframe: DevframeDefinition;
+//#endregion
+export { type AssetImageMeta, type AssetInfo, type AssetType, AssetsDevframeOptions, type CodeSnippet, DEFAULT_ALLOWED_UPLOAD_EXTENSIONS, createAssetsDevframe, assetsDevframe as default };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { n as createAssetsDevframe, r as DEFAULT_ALLOWED_UPLOAD_EXTENSIONS, t as assetsDevframe } from "./src-DuJ-iEes.mjs";
+export { DEFAULT_ALLOWED_UPLOAD_EXTENSIONS, createAssetsDevframe, assetsDevframe as default };

package/dist/node/index.d.mts

@@ -0,0 +1,96 @@
+import { n as AssetInfo, r as AssetType } from "../types-DPDOYVFh.mjs";
+import { DevframeNodeContext, RpcStreamingChannel } from "devframe/types";
+//#region src/node/context.d.ts
+interface AssetsConfig {
+  /** Directory this devframe manages. */
+  dir: string;
+  /** Whether upload / rename / delete / mkdir are registered. */
+  write: boolean;
+  /** Extensions `upload` accepts, or `'*'` to accept any. */
+  uploadExtensions: readonly string[] | '*';
+  /**
+   * URL base the managed directory is served at. Normally the host
+   * (Vite / Nuxt / …) serves `public/` at `/`, so asset `publicPath`s are
+   * `joinURL(baseURL, path)` and the plugin serves nothing itself.
+   */
+  baseURL: string;
+  /** The upload streaming channel, created once in `setupAssets` when `write` is enabled. */
+  uploadChannel?: RpcStreamingChannel<Uint8Array>;
+}
+interface AssetsContext extends AssetsConfig {
+  /** Resolve a root-relative path to an absolute one, rejecting escapes. */
+  resolvePath: (relativePath: string) => string;
+}
+/**
+ * Record the managed directory and write policy for a context. Called from
+ * the devframe's `setup` before any RPC handler runs.
+ */
+declare function configureAssets(ctx: DevframeNodeContext, config: AssetsConfig): void;
+/**
+ * Per-`DevframeNodeContext` assets state. Each RPC function pulls its
+ * managed directory and path resolver from here instead of re-reading
+ * `configureAssets`'s config on every call.
+ */
+declare function getAssetsContext(ctx: DevframeNodeContext): AssetsContext;
+//#endregion
+//#region src/node/paths.d.ts
+/**
+ * Resolve a client-supplied, root-relative path against the managed
+ * directory, rejecting anything that would escape it (`..` traversal, a
+ * rogue absolute path, etc.). Every RPC handler that touches the
+ * filesystem goes through this — never trust a path from the wire.
+ */
+declare function resolveAssetPath(root: string, relativePath: string): string;
+//#endregion
+//#region src/node/scanner.d.ts
+/** Classifies a path by extension, driving preview and icon choice. */
+declare function guessAssetType(path: string): AssetType;
+/** Recursively lists every file under `dir`, sorted alphabetically by path. */
+declare function scanAssets(dir: string, baseURL: string): Promise<AssetInfo[]>;
+//#endregion
+//#region src/node/index.d.ts
+interface SetupAssetsOptions {
+  /** Directory this devframe manages. */
+  dir: string;
+  /** Whether upload / rename / delete / mkdir are registered. */
+  write: boolean;
+  /** Extensions `upload` accepts, or `'*'` to accept any. */
+  uploadExtensions: readonly string[] | '*';
+  /**
+   * URL base the managed directory is served at — the base every asset's
+   * `publicPath` is resolved against.
+   */
+  baseURL: string;
+  /**
+   * Whether this devframe should serve the managed directory's bytes
+   * itself. Left `false` when mounted into a host (Vite / Nuxt / …) that
+   * already serves `public/` at {@link baseURL}; set `true` only for the
+   * standalone CLI, which is its own host.
+   */
+  serveStatic: boolean;
+  /** Start the live file watcher (dev mode only). */
+  watch: boolean;
+}
+/**
+ * Register the assets RPC surface on a devframe node context: ensures the
+ * managed directory exists, registers the read RPCs (always) and write
+ * RPCs (when enabled), and starts a live file watcher in dev mode.
+ *
+ * Raw asset bytes (for `<img>`/`<video>`/download previews) are served by
+ * the **host** the plugin is attached to — Vite, Nuxt, or any framework
+ * already serves its `public/` dir at {@link SetupAssetsOptions.baseURL}.
+ * The plugin only serves them itself when `serveStatic` is set (the
+ * standalone CLI, which is its own host).
+ *
+ * Called from the definition's `setup(ctx)` and reusable by host adapters
+ * that wire their own context.
+ */
+declare function setupAssets(ctx: DevframeNodeContext, options: SetupAssetsOptions): Promise<void>;
+/**
+ * Stop the live file watcher started by {@link setupAssets}. Test harnesses
+ * wrap their dev-server `close()` with this — see `test/_utils.ts` — so a
+ * leaked chokidar watcher doesn't keep the process alive.
+ */
+declare function disposeAssetsWatcher(ctx: DevframeNodeContext): Promise<void>;
+//#endregion
+export { SetupAssetsOptions, configureAssets, disposeAssetsWatcher, getAssetsContext, guessAssetType, resolveAssetPath, scanAssets, setupAssets };

package/dist/node/index.mjs

@@ -0,0 +1,3 @@
+import { n as setupAssets, t as disposeAssetsWatcher } from "../node-qqFgpP7-.mjs";
+import { b as getAssetsContext, m as scanAssets, p as guessAssetType, x as resolveAssetPath, y as configureAssets } from "../rpc-lfFykVQ_.mjs";
+export { configureAssets, disposeAssetsWatcher, getAssetsContext, guessAssetType, resolveAssetPath, scanAssets, setupAssets };

package/dist/node-qqFgpP7-.mjs

@@ -0,0 +1,75 @@
+import { _ as UPLOAD_CHANNEL, i as writeFunctions, n as readFunctions, t as alwaysFunctions, y as configureAssets } from "./rpc-lfFykVQ_.mjs";
+import { existsSync } from "node:fs";
+import fsp from "node:fs/promises";
+import { watch } from "chokidar";
+import { debounce } from "perfect-debounce";
+//#region src/constants.ts
+/** Broadcast whenever a file is added, removed, or changed under the managed directory. */
+const CHANGED_EVENT = "devframes:plugin:assets:changed";
+/** Preferred standalone CLI port. */
+const DEFAULT_PORT = 9015;
+//#endregion
+//#region src/node/watcher.ts
+/**
+* Watch the managed directory and broadcast {@link CHANGED_EVENT} (debounced)
+* whenever a file is added, removed, or changed, so connected UIs refresh
+* their listing live. Returns a disposer; call it when the devframe shuts
+* down (tests in particular — a leaked watcher keeps the process alive).
+*/
+function watchAssetsDir(ctx, dir) {
+	const notify = debounce(async () => {
+		await ctx.rpc.broadcast({
+			method: CHANGED_EVENT,
+			args: []
+		});
+	}, 300);
+	const watcher = watch(dir, {
+		ignoreInitial: true,
+		depth: 32
+	});
+	watcher.on("add", () => void notify()).on("unlink", () => void notify()).on("addDir", () => void notify()).on("unlinkDir", () => void notify()).on("change", () => void notify());
+	return () => watcher.close();
+}
+//#endregion
+//#region src/node/index.ts
+const watchers = /* @__PURE__ */ new WeakMap();
+/**
+* Register the assets RPC surface on a devframe node context: ensures the
+* managed directory exists, registers the read RPCs (always) and write
+* RPCs (when enabled), and starts a live file watcher in dev mode.
+*
+* Raw asset bytes (for `<img>`/`<video>`/download previews) are served by
+* the **host** the plugin is attached to — Vite, Nuxt, or any framework
+* already serves its `public/` dir at {@link SetupAssetsOptions.baseURL}.
+* The plugin only serves them itself when `serveStatic` is set (the
+* standalone CLI, which is its own host).
+*
+* Called from the definition's `setup(ctx)` and reusable by host adapters
+* that wire their own context.
+*/
+async function setupAssets(ctx, options) {
+	if (!existsSync(options.dir)) await fsp.mkdir(options.dir, { recursive: true });
+	const uploadChannel = options.write ? ctx.rpc.streaming.create(UPLOAD_CHANNEL) : void 0;
+	configureAssets(ctx, {
+		...options,
+		uploadChannel
+	});
+	if (options.serveStatic) ctx.views.hostStatic(options.baseURL, options.dir);
+	for (const fn of readFunctions) ctx.rpc.register(fn);
+	for (const fn of alwaysFunctions) ctx.rpc.register(fn);
+	if (options.write) for (const fn of writeFunctions) ctx.rpc.register(fn);
+	if (ctx.mode === "dev" && options.watch) watchers.set(ctx, watchAssetsDir(ctx, options.dir));
+}
+/**
+* Stop the live file watcher started by {@link setupAssets}. Test harnesses
+* wrap their dev-server `close()` with this — see `test/_utils.ts` — so a
+* leaked chokidar watcher doesn't keep the process alive.
+*/
+async function disposeAssetsWatcher(ctx) {
+	const dispose = watchers.get(ctx);
+	if (!dispose) return;
+	watchers.delete(ctx);
+	await dispose();
+}
+//#endregion
+export { setupAssets as n, DEFAULT_PORT as r, disposeAssetsWatcher as t };