@devframes/plugin-assets 0.9.8 → 0.9.9

package/README.md

@@ -1,13 +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`.
+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 — mount it into a Vite host with `devframeVite()` from `@devframes/vite/single`. Pass `{ dir }` to manage a different directory, `{ baseURL }` to match where the host framework serves it, or `{ write: false }` (`--read-only` on the standalone CLI) for a browse-only deployment.
+Manages `<cwd>/public` by default. The package exports `createAssetsDevframe()` for custom definitions; mount it into a Vite host with `devframeVite()` from `@devframes/vite/single`. Pass `{ dir }` to manage a different directory, `{ baseURL }` to match where the host framework 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 framework the devframe is mounted into (Vite/Nuxt/etc. already serve `public/` at `/`) — the devframe doesn't serve the bytes itself. The standalone CLI serves the directory for you.
+Asset previews load files by their public URL, served by the host framework the devframe is mounted into (Vite/Nuxt/etc. already serve `public/` at `/`), so the devframe doesn't serve the bytes itself. The standalone CLI 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.
+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/dist/cli.mjs

@@ -1,4 +1,4 @@
-import { t as createAssetsDevframe } from "./src-CPYq9rfy.mjs";
+import { t as createAssetsDevframe } from "./src-BpDib51Z.mjs";
 import { createCac } from "devframe/adapters/cac";
 //#region src/cli.ts
 function createAssetsCli() {

package/dist/client/index.d.mts

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

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as DEFAULT_ALLOWED_UPLOAD_EXTENSIONS, i as CodeSnippet, n as AssetInfo, r as AssetType, t as AssetImageMeta } from "./types-BrE0klRv.mjs";
+import { a as DEFAULT_ALLOWED_UPLOAD_EXTENSIONS, i as CodeSnippet, n as AssetInfo, r as AssetType, t as AssetImageMeta } from "./types-BKiX3RbA.mjs";
 import { DevframeDefinition } from "devframe";
 //#region src/index.d.ts
 interface AssetsDevframeOptions {
@@ -6,7 +6,7 @@ interface AssetsDevframeOptions {
   name?: string;
   icon?: string;
   /**
-   * Directory this devframe manages. Defaults to `<cwd>/public` — the
+   * 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`.
@@ -14,7 +14,7 @@ interface AssetsDevframeOptions {
   dir?: string;
   /**
    * URL base the **host** serves the managed directory at, used to build
-   * each asset's `publicPath`. Defaults to `/` — Vite, Nuxt, and most
+   * 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`).
    */
@@ -34,7 +34,7 @@ interface AssetsDevframeOptions {
   port?: number;
   /**
    * Enable upload, rename, delete, and folder creation from the UI.
-   * Enabled by default — set `false` (or pass `--read-only` on the
+   * Enabled by default; set `false` (or pass `--read-only` on the
    * standalone CLI) for a browse-only deployment.
    */
   write?: boolean;
@@ -45,7 +45,7 @@ interface AssetsDevframeOptions {
   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
+   * 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.
@@ -53,21 +53,21 @@ interface AssetsDevframeOptions {
   watch?: boolean;
   /**
    * Require the trust handshake on the standalone server. Enabled by
-   * default — this devframe can read, write, and delete real files.
+   * default, because 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
+   * 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,
+   * 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
+ * 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`).
  *

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { n as DEFAULT_ALLOWED_UPLOAD_EXTENSIONS, t as createAssetsDevframe } from "./src-CPYq9rfy.mjs";
+import { n as DEFAULT_ALLOWED_UPLOAD_EXTENSIONS, t as createAssetsDevframe } from "./src-BpDib51Z.mjs";
 export { DEFAULT_ALLOWED_UPLOAD_EXTENSIONS, createAssetsDevframe, createAssetsDevframe as default };

package/dist/node/index.d.mts

@@ -1,4 +1,4 @@
-import { n as AssetInfo, r as AssetType } from "../types-BrE0klRv.mjs";
+import { n as AssetInfo, r as AssetType } from "../types-BKiX3RbA.mjs";
 import { DevframeNodeContext, RpcStreamingChannel } from "devframe";
 //#region src/node/context.d.ts
 interface AssetsConfig {
@@ -18,7 +18,12 @@ interface AssetsConfig {
   uploadChannel?: RpcStreamingChannel<Uint8Array>;
 }
 interface AssetsContext extends AssetsConfig {
-  /** Resolve a root-relative path to an absolute one, rejecting escapes. */
+  /**
+   * Resolve a root-relative path to an absolute one, rejecting lexical
+   * escapes. Symlink-aware containment for reads and mutations lives in
+   * `node/paths` (`resolveAssetReadPath` / `assertAssetMutationPath`), which
+   * the RPC handlers call directly with {@link AssetsContext.dir}.
+   */
   resolvePath: (relativePath: string) => string;
 }
 /**
@@ -36,9 +41,10 @@ declare function getAssetsContext(ctx: DevframeNodeContext): AssetsContext;
 //#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.
+ * directory, rejecting anything that would escape it lexically (`..`
+ * traversal, a rogue absolute path). The first guard every RPC handler runs;
+ * symlink-aware containment is layered on by {@link resolveAssetReadPath}
+ * (reads) and {@link assertAssetMutationPath} (mutations).
  */
 declare function resolveAssetPath(root: string, relativePath: string): string;
 //#endregion
@@ -57,7 +63,7 @@ interface SetupAssetsOptions {
   /** Extensions `upload` accepts, or `'*'` to accept any. */
   uploadExtensions: readonly string[] | '*';
   /**
-   * URL base the managed directory is served at — the base every asset's
+   * URL base the managed directory is served at, the base every asset's
    * `publicPath` is resolved against.
    */
   baseURL: string;
@@ -77,7 +83,7 @@ interface SetupAssetsOptions {
  * 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
+ * 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).
@@ -88,7 +94,7 @@ interface SetupAssetsOptions {
 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
+ * 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>;

package/dist/node/index.mjs

@@ -1,3 +1,3 @@
-import { n as setupAssets, t as disposeAssetsWatcher } from "../node-Cit_U9yi.mjs";
-import { _ as getAssetsContext, d as scanAssets, g as configureAssets, u as guessAssetType, v as resolveAssetPath } from "../rpc-BOraEthN.mjs";
+import { n as setupAssets, t as disposeAssetsWatcher } from "../node-Diynhcd3.mjs";
+import { _ as getAssetsContext, d as scanAssets, g as configureAssets, u as guessAssetType, v as resolveAssetPath } from "../rpc-Pau8tZGm.mjs";
 export { configureAssets, disposeAssetsWatcher, getAssetsContext, guessAssetType, resolveAssetPath, scanAssets, setupAssets };

package/dist/{node-Cit_U9yi.mjs → node-Diynhcd3.mjs}

@@ -1,4 +1,4 @@
-import { g as configureAssets, m as UPLOAD_CHANNEL, r as writeFunctions, t as readFunctions } from "./rpc-BOraEthN.mjs";
+import { g as configureAssets, m as UPLOAD_CHANNEL, r as writeFunctions, t as readFunctions } from "./rpc-Pau8tZGm.mjs";
 import process from "node:process";
 import { existsSync } from "node:fs";
 import fsp from "node:fs/promises";
@@ -15,7 +15,7 @@ const DEFAULT_PORT = 9015;
 * 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).
+* down (tests in particular, since a leaked watcher keeps the process alive).
 */
 function watchAssetsDir(ctx, dir) {
 	const notify = debounce(async () => {
@@ -26,6 +26,12 @@ function watchAssetsDir(ctx, dir) {
 	}, 300);
 	const watcher = watch(dir, {
 		ignoreInitial: true,
+		/**
+		* Directories can nest arbitrarily deep (icon sets, generated builds
+		* dropped into the managed dir, …); chokidar's default depth is
+		* unlimited, but pin a generous cap so a runaway symlink loop can't
+		* spin the watcher forever.
+		*/
 		depth: 32
 	});
 	watcher.on("add", () => void notify()).on("unlink", () => void notify()).on("addDir", () => void notify()).on("unlinkDir", () => void notify()).on("change", () => void notify());
@@ -43,7 +49,7 @@ const watchers = /* @__PURE__ */ new WeakMap();
 * 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
+* 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).
@@ -65,7 +71,7 @@ async function setupAssets(ctx, options) {
 }
 /**
 * Stop the live file watcher started by {@link setupAssets}. Test harnesses
-* wrap their dev-server `close()` with this — see `test/_utils.ts` — so a
+* 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) {

package/dist/rpc/index.d.mts

@@ -8,7 +8,7 @@ interface AssetsCapabilities {
 /**
  * Lets the UI know upfront whether upload / rename / delete / mkdir are
  * available, so it can hide or disable those affordances proactively
- * instead of letting the user hit a "method not found" error — the same
+ * instead of letting the user hit a "method not found" error, the same
  * `canWrite`-gating idea the git plugin's `GitStatus.canWrite` follows.
  */
 declare const capabilities: {
@@ -273,7 +273,7 @@ interface RenameArgs {
   /** Root-relative path of the asset to rename. */
   path: string;
   /**
-   * New base name, without an extension — the original extension is
+   * New base name, without an extension; the original extension is
    * always preserved (mirrors Nuxt DevTools' rename dialog exactly). Any
    * extension included here is treated as part of the base name, not
    * stripped.
@@ -371,7 +371,7 @@ declare const rename: {
 declare const UPLOAD_CHANNEL = "devframes:plugin:assets:upload";
 /**
  * Allocates an upload and returns a streaming id. Actual bytes flow over
- * the `upload` channel opened in `setupAssets` — see the client-side
+ * the `upload` channel opened in `setupAssets`; see the client-side
  * `useUpload` hook for the matching `rpc.streaming.upload()` call.
  */
 declare const upload: {
@@ -419,7 +419,7 @@ declare const upload: {
 };
 //#endregion
 //#region src/rpc/index.d.ts
-/** Read-only RPC — always registered. */
+/** Read-only RPC, always registered. */
 declare const readFunctions: readonly [{
   name: "devframes:plugin:assets:list";
   type?: "query" | undefined;
@@ -575,7 +575,7 @@ declare const readFunctions: readonly [{
     uploadExtensions: string[] | "*";
   }>>> | undefined;
 }];
-/** Mutating RPC — registered only when write actions are enabled. */
+/** Mutating RPC, registered only when write actions are enabled. */
 declare const writeFunctions: readonly [{
   name: "devframes:plugin:assets:upload";
   type?: "action" | undefined;

package/dist/rpc/index.mjs

@@ -1,2 +1,2 @@
-import { a as readText, c as assetInfoSchema, f as deleteAssets, h as upload, i as rename, l as list, m as UPLOAD_CHANNEL, n as serverFunctions, o as readImageMeta, p as capabilities, r as writeFunctions, s as mkdir, t as readFunctions } from "../rpc-BOraEthN.mjs";
+import { a as readText, c as assetInfoSchema, f as deleteAssets, h as upload, i as rename, l as list, m as UPLOAD_CHANNEL, n as serverFunctions, o as readImageMeta, p as capabilities, r as writeFunctions, s as mkdir, t as readFunctions } from "../rpc-Pau8tZGm.mjs";
 export { UPLOAD_CHANNEL, assetInfoSchema, capabilities, deleteAssets, list, mkdir, readFunctions, readImageMeta, readText, rename, serverFunctions, upload, writeFunctions };

package/dist/{rpc-BOraEthN.mjs → rpc-Pau8tZGm.mjs}

@@ -1,4 +1,4 @@
-import { dirname, extname, join, resolve } from "pathe";
+import { dirname, extname, join, normalize, resolve } from "pathe";
 import { createWriteStream } from "node:fs";
 import fsp from "node:fs/promises";
 import { createDefineWrapperWithContext } from "devframe/rpc";
@@ -8,6 +8,11 @@ import { glob } from "tinyglobby";
 import { joinURL } from "ufo";
 import { imageMeta } from "image-meta";
 //#region src/diagnostics.ts
+/**
+* Uses the plugin's own `DP_ASSETS_` prefix per the built-in plugin
+* convention, keeping it collision-free with devframe core (`DF`) and the
+* hub (`DF8xxx`).
+*/
 const diagnostics = defineDiagnostics({
 	docsBase: "https://devfra.me/errors",
 	codes: {
@@ -25,7 +30,7 @@ const diagnostics = defineDiagnostics({
 		},
 		DP_ASSETS_0004: {
 			why: (p) => `No asset found at "${p.path}".`,
-			fix: "Refresh the asset list — it may have been moved or deleted already."
+			fix: "Refresh the asset list; it may have been moved or deleted already."
 		},
 		DP_ASSETS_0005: {
 			why: (p) => `Cannot create folder "${p.path}" because a file already exists there.`,
@@ -37,25 +42,67 @@ const diagnostics = defineDiagnostics({
 		},
 		DP_ASSETS_0007: {
 			why: "The upload streaming channel is unavailable because this devframe was set up with `write: false`.",
-			fix: "This indicates an internal registration bug — `upload` should never be reachable without `write: true`. Please report it."
+			fix: "This indicates an internal registration bug, since `upload` should never be reachable without `write: true`. Please report it."
 		}
 	}
 });
 //#endregion
 //#region src/node/paths.ts
+/** realpath, pathe-normalized, or `null` when the path doesn't exist. */
+async function realpath(path) {
+	try {
+		return normalize(await fsp.realpath(path));
+	} catch {
+		return null;
+	}
+}
 /**
 * 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.
+* directory, rejecting anything that would escape it lexically (`..`
+* traversal, a rogue absolute path). The first guard every RPC handler runs;
+* symlink-aware containment is layered on by {@link resolveAssetReadPath}
+* (reads) and {@link assertAssetMutationPath} (mutations).
 */
 function resolveAssetPath(root, relativePath) {
-	const cleaned = relativePath.replace(/^[/\\]+/, "");
 	const normalizedRoot = resolve(root);
-	const absolute = resolve(normalizedRoot, cleaned);
+	const absolute = resolve(normalizedRoot, relativePath.replace(/^[/\\]+/, ""));
 	if (absolute !== normalizedRoot && !absolute.startsWith(`${normalizedRoot}/`)) throw diagnostics.DP_ASSETS_0001({ path: relativePath });
 	return absolute;
 }
+/**
+* Resolve a path for a **read**, allowing a symlink only when its canonical
+* target stays inside the canonical managed root. A target resolving outside
+* throws `DP_ASSETS_0001`; a missing target is left for the caller's own read
+* to fail.
+*/
+async function resolveAssetReadPath(root, relativePath) {
+	const absolute = resolveAssetPath(root, relativePath);
+	const real = await realpath(absolute);
+	const canonRoot = await realpath(root) ?? resolve(root);
+	if (real && real !== canonRoot && !real.startsWith(`${canonRoot}/`)) throw diagnostics.DP_ASSETS_0001({ path: relativePath });
+	return absolute;
+}
+/**
+* Resolve a path for a **mutation**, rejecting every pre-existing symlink
+* among the path components from the managed root down to the target
+* (including in-root symlinks) so a mutation can never follow a symlink out
+* of, or around, the root. Only existing components are inspected, so it is
+* safe for not-yet-created upload/mkdir targets; call it again after
+* creating directories and right before the I/O. This closes deterministic,
+* pre-existing symlink escapes, not concurrent component-swap races.
+*/
+async function assertAssetMutationPath(root, relativePath) {
+	const lexRoot = resolve(root);
+	const absolute = resolveAssetPath(root, relativePath);
+	let current = await realpath(root) ?? lexRoot;
+	for (const segment of absolute.slice(lexRoot.length).split("/").filter(Boolean)) {
+		current += `/${segment}`;
+		const stat = await fsp.lstat(current).catch(() => null);
+		if (!stat) break;
+		if (stat.isSymbolicLink()) throw diagnostics.DP_ASSETS_0001({ path: relativePath });
+	}
+	return absolute;
+}
 //#endregion
 //#region src/node/context.ts
 const configs = /* @__PURE__ */ new WeakMap();
@@ -101,7 +148,7 @@ function isExtensionAllowed(path, allowed) {
 }
 /**
 * Allocates an upload and returns a streaming id. Actual bytes flow over
-* the `upload` channel opened in `setupAssets` — see the client-side
+* the `upload` channel opened in `setupAssets`; see the client-side
 * `useUpload` hook for the matching `rpc.streaming.upload()` call.
 */
 const upload = defineAssetsRpc$7({
@@ -118,14 +165,17 @@ const upload = defineAssetsRpc$7({
 	},
 	setup: (ctx) => {
 		const assets = getAssetsContext(ctx);
-		return { handler: (async ({ path }) => {
+		return { 
+		/** See `list.ts` for why the async handler is cast. */
+handler: (async ({ path }) => {
 			if (!isExtensionAllowed(path, assets.uploadExtensions)) throw diagnostics.DP_ASSETS_0002({
 				path,
 				extension: extname(path).slice(1).toLowerCase() || "(none)",
 				allowed: assets.uploadExtensions === "*" ? [] : assets.uploadExtensions
 			});
-			const absolute = assets.resolvePath(path);
+			const absolute = await assertAssetMutationPath(assets.dir, path);
 			await fsp.mkdir(dirname(absolute), { recursive: true });
+			await assertAssetMutationPath(assets.dir, path);
 			const channel = assets.uploadChannel;
 			if (!channel) throw diagnostics.DP_ASSETS_0007();
 			const reader = channel.openInbound();
@@ -147,7 +197,7 @@ const upload = defineAssetsRpc$7({
 /**
 * Lets the UI know upfront whether upload / rename / delete / mkdir are
 * available, so it can hide or disable those affordances proactively
-* instead of letting the user hit a "method not found" error — the same
+* instead of letting the user hit a "method not found" error, the same
 * `canWrite`-gating idea the git plugin's `GitStatus.canWrite` follows.
 */
 const capabilities = createDefineWrapperWithContext()({
@@ -189,10 +239,12 @@ const deleteAssets = createDefineWrapperWithContext()({
 	},
 	setup: (ctx) => {
 		const assets = getAssetsContext(ctx);
-		return { handler: (async ({ paths }) => {
+		return { 
+		/** See `list.ts` for why the async handler is cast. */
+handler: (async ({ paths }) => {
 			const deleted = [];
 			for (const path of paths) {
-				const absolute = assets.resolvePath(path);
+				const absolute = await assertAssetMutationPath(assets.dir, path);
 				try {
 					await fsp.unlink(absolute);
 					deleted.push(path);
@@ -245,11 +297,14 @@ async function scanAssets(dir, baseURL, includeFsPath = false) {
 	const files = await glob(["**/*"], {
 		cwd: dir,
 		onlyFiles: true,
-		dot: false
+		dot: false,
+		followSymbolicLinks: false
 	});
 	return (await Promise.all(files.map(async (relPath) => {
 		try {
-			return statToAssetInfo(dir, baseURL, relPath, await fsp.lstat(join(dir, relPath)), includeFsPath);
+			const stat = await fsp.lstat(join(dir, relPath));
+			if (stat.isSymbolicLink()) return void 0;
+			return statToAssetInfo(dir, baseURL, relPath, stat, includeFsPath);
 		} catch {
 			return;
 		}
@@ -288,7 +343,14 @@ const list = defineAssetsRpc$4({
 	},
 	setup: (ctx) => {
 		const assets = getAssetsContext(ctx);
-		return { handler: (async () => scanAssets(assets.dir, assets.baseURL, ctx.mode === "dev")) };
+		return { 
+		/**
+		* The RPC runtime awaits handlers before validating `returns`; its
+		* public setup type currently models schema-backed returns as
+		* synchronous.
+		* `fsPath` is dev-only, never baked into a static build's dump.
+		*/
+handler: (async () => scanAssets(assets.dir, assets.baseURL, ctx.mode === "dev")) };
 	}
 });
 const mkdir = createDefineWrapperWithContext()({
@@ -305,11 +367,14 @@ const mkdir = createDefineWrapperWithContext()({
 	},
 	setup: (ctx) => {
 		const assets = getAssetsContext(ctx);
-		return { handler: (async ({ path }) => {
-			const absolute = assets.resolvePath(path);
+		return { 
+		/** See `list.ts` for why the async handler is cast. */
+handler: (async ({ path }) => {
+			const absolute = await assertAssetMutationPath(assets.dir, path);
 			const stat = await fsp.stat(absolute).catch(() => void 0);
 			if (stat && !stat.isDirectory()) throw diagnostics.DP_ASSETS_0005({ path });
 			await fsp.mkdir(absolute, { recursive: true });
+			await assertAssetMutationPath(assets.dir, path);
 		}) };
 	}
 });
@@ -331,9 +396,11 @@ const readImageMeta = createDefineWrapperWithContext()({
 	},
 	setup: (ctx) => {
 		const assets = getAssetsContext(ctx);
-		return { handler: (async (path) => {
+		return { 
+		/** See `list.ts` for why the async handler is cast. */
+handler: (async (path) => {
 			try {
-				const buffer = await fsp.readFile(assets.resolvePath(path));
+				const buffer = await fsp.readFile(await resolveAssetReadPath(assets.dir, path));
 				const meta = imageMeta(buffer);
 				return {
 					width: meta.width,
@@ -364,9 +431,11 @@ const readText = defineAssetsRpc$1({
 	},
 	setup: (ctx) => {
 		const assets = getAssetsContext(ctx);
-		return { handler: (async (path, limit = DEFAULT_LIMIT) => {
+		return { 
+		/** See `list.ts` for why the async handler is cast. */
+handler: (async (path, limit = DEFAULT_LIMIT) => {
 			try {
-				return (await fsp.readFile(assets.resolvePath(path), "utf-8")).slice(0, limit);
+				return (await fsp.readFile(await resolveAssetReadPath(assets.dir, path), "utf-8")).slice(0, limit);
 			} catch {
 				return null;
 			}
@@ -390,20 +459,24 @@ const rename = createDefineWrapperWithContext()({
 	},
 	setup: (ctx) => {
 		const assets = getAssetsContext(ctx);
-		return { handler: (async ({ path, newName }) => {
+		return { 
+		/** See `list.ts` for why the async handler is cast. */
+handler: (async ({ path, newName }) => {
 			const trimmed = newName.trim();
 			if (!trimmed || /[/\\]/.test(trimmed)) throw diagnostics.DP_ASSETS_0006({ name: newName });
 			const folder = dirname(path);
 			const nextName = `${trimmed}${extname(path)}`;
 			const nextRelPath = folder === "." ? nextName : `${folder}/${nextName}`;
-			const from = assets.resolvePath(path);
-			const to = assets.resolvePath(nextRelPath);
+			const from = await assertAssetMutationPath(assets.dir, path);
+			const to = await assertAssetMutationPath(assets.dir, nextRelPath);
 			if (from === to) {
 				const stat = await fsp.lstat(from);
 				return statToAssetInfo(assets.dir, assets.baseURL, path, stat, true);
 			}
 			if (await fsp.access(to).then(() => true).catch(() => false)) throw diagnostics.DP_ASSETS_0003({ path: nextRelPath });
 			await fsp.mkdir(dirname(to), { recursive: true });
+			await assertAssetMutationPath(assets.dir, path);
+			await assertAssetMutationPath(assets.dir, nextRelPath);
 			try {
 				await fsp.rename(from, to);
 			} catch (error) {
@@ -417,14 +490,14 @@ const rename = createDefineWrapperWithContext()({
 });
 //#endregion
 //#region src/rpc/index.ts
-/** Read-only RPC — always registered. */
+/** Read-only RPC, always registered. */
 const readFunctions = [
 	list,
 	readImageMeta,
 	readText,
 	capabilities
 ];
-/** Mutating RPC — registered only when write actions are enabled. */
+/** Mutating RPC, registered only when write actions are enabled. */
 const writeFunctions = [
 	upload,
 	rename,

package/dist/{src-CPYq9rfy.mjs → src-BpDib51Z.mjs}

@@ -1,10 +1,10 @@
-import { n as setupAssets } from "./node-Cit_U9yi.mjs";
+import { n as setupAssets } from "./node-Diynhcd3.mjs";
 import process from "node:process";
 import { defineDevframe } from "devframe";
 import { resolve } from "pathe";
 //#region package.json
 var name = "@devframes/plugin-assets";
-var version = "0.9.8";
+var version = "0.9.9";
 var description = "Devframe plugin for browsing, previewing, uploading, and managing static assets in a directory.";
 var homepage = "https://github.com/devframes/devframe#readme";
 //#endregion
@@ -39,7 +39,7 @@ const remoteAssets = {
 };
 const DEFAULT_ID = "devframes_plugin_assets";
 /**
-* Create the assets manager devframe — a framework-neutral port of Nuxt
+* 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`).
 *
@@ -74,6 +74,14 @@ function createAssetsDevframe(options = {}) {
 			}
 		},
 		dock: { category: "~builtin" },
+		/**
+		* Both wire services are declared, not imperatively installed: devframe
+		* constructs them (deep-merging options across every declarer) before
+		* setup runs. `service-open` gets the managed dir as an allowed root so
+		* out-of-workspace dirs open; the client hits it directly with the
+		* dev-only absolute `fsPath`. `service-shiki` backs server-highlighted
+		* text previews, with a plain `<pre>` fallback when it isn't advertised.
+		*/
 		services: [{
 			package: "@devframes/service-open",
 			options: { roots: [dir] }

package/dist/{types-BrE0klRv.d.mts → types-BKiX3RbA.d.mts}

@@ -9,10 +9,10 @@ interface AssetInfo {
   /** URL the browser can fetch the raw bytes from (live adapters only). */
   publicPath: string;
   size: number;
-  /** `mtimeMs` — milliseconds since epoch. */
+  /** `mtimeMs` in milliseconds since epoch. */
   mtime: number;
   /**
-   * Absolute filesystem path — populated in `dev` mode only (never baked
+   * Absolute filesystem path, populated in `dev` mode only (never baked
    * into a static build's dump), so the client can hand it to the
    * `@devframes/service-open` wire service for open-in-editor / reveal.
    */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@devframes/plugin-assets",
   "type": "module",
-  "version": "0.9.8",
+  "version": "0.9.9",
   "description": "Devframe plugin for browsing, previewing, uploading, and managing static assets in a directory.",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -37,9 +37,9 @@
     "dist"
   ],
   "peerDependencies": {
-    "@devframes/plugin-assets--assets": "0.9.8",
-    "@devframes/service-shiki": "0.9.8",
-    "devframe": "0.9.8",
+    "@devframes/plugin-assets--assets": "0.9.9",
+    "@devframes/service-shiki": "0.9.9",
+    "devframe": "0.9.9",
     "vite": "^7.0.0 || ^8.0.0"
   },
   "peerDependenciesMeta": {
@@ -54,7 +54,7 @@
     }
   },
   "dependencies": {
-    "@devframes/service-open": "0.9.8",
+    "@devframes/service-open": "0.9.9",
     "cac": "^7.0.0",
     "chokidar": "^5.0.0",
     "image-meta": "^0.2.2",
@@ -65,9 +65,9 @@
   },
   "devDependencies": {
     "@antfu/design": "^0.4.0",
-    "@devframes/plugin-assets--assets": "0.9.8",
-    "@devframes/service-shiki": "0.9.8",
-    "@devframes/vite": "0.9.8",
+    "@devframes/plugin-assets--assets": "0.9.9",
+    "@devframes/service-shiki": "0.9.9",
+    "@devframes/vite": "0.9.9",
     "@iconify-json/ph": "^1.2.2",
     "@storybook/addon-a11y": "^10.5.10",
     "@storybook/addon-docs": "^10.5.10",
@@ -75,7 +75,7 @@
     "@types/node": "^26.4.0",
     "@vitejs/plugin-vue": "^6.0.8",
     "colorjs.io": "^0.7.1",
-    "devframe": "0.9.8",
+    "devframe": "0.9.9",
     "floating-vue": "^5.2.2",
     "h3": "^2.0.1-rc.29",
     "reka-ui": "^2.10.4",