@devframes/plugin-assets 0.7.15

package/dist/rpc/index.mjs

@@ -0,0 +1,2 @@
+import { _ as UPLOAD_CHANNEL, a as revealInFolder, c as readImageMeta, d as assetInfoSchema, f as list, g as capabilities, h as deleteAssets, i as writeFunctions, l as openInEditor, n as readFunctions, o as rename, r as serverFunctions, s as readText, t as alwaysFunctions, u as mkdir, v as upload } from "../rpc-lfFykVQ_.mjs";
+export { UPLOAD_CHANNEL, alwaysFunctions, assetInfoSchema, capabilities, deleteAssets, list, mkdir, openInEditor, readFunctions, readImageMeta, readText, rename, revealInFolder, serverFunctions, upload, writeFunctions };

package/dist/rpc-lfFykVQ_.mjs

@@ -0,0 +1,489 @@
+import { dirname, extname, join, resolve } from "pathe";
+import { createWriteStream } from "node:fs";
+import fsp from "node:fs/promises";
+import { createDefineWrapperWithContext } from "devframe/rpc";
+import * as v from "valibot";
+import { defineDiagnostics } from "nostics";
+import { glob } from "tinyglobby";
+import { joinURL } from "ufo";
+import { launchEditor } from "devframe/utils/launch-editor";
+import { imageMeta } from "image-meta";
+import { open } from "devframe/utils/open";
+//#region src/diagnostics.ts
+const diagnostics = defineDiagnostics({
+	docsBase: "https://devfra.me/errors",
+	codes: {
+		DP_ASSETS_0001: {
+			why: (p) => `"${p.path}" resolves outside the managed directory.`,
+			fix: "Use a path relative to the configured `dir`, without leading `/` or `..` segments."
+		},
+		DP_ASSETS_0002: {
+			why: (p) => `Cannot upload "${p.path}" because the "${p.extension}" extension is not allowed. Allowed extensions: ${p.allowed.join(", ")}.`,
+			fix: "Configure `uploadExtensions` on the assets devframe to allow this extension, or pass `'*'` to allow any."
+		},
+		DP_ASSETS_0003: {
+			why: (p) => `Cannot rename to "${p.path}" because a file already exists there.`,
+			fix: "Choose a different name."
+		},
+		DP_ASSETS_0004: {
+			why: (p) => `No asset found at "${p.path}".`,
+			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.`,
+			fix: "Choose a different folder name."
+		},
+		DP_ASSETS_0006: {
+			why: (p) => `"${p.name}" is not a valid file name.`,
+			fix: "Names must be non-empty and cannot contain `/` or `\\`."
+		},
+		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."
+		}
+	}
+});
+//#endregion
+//#region src/node/paths.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.
+*/
+function resolveAssetPath(root, relativePath) {
+	const cleaned = relativePath.replace(/^[/\\]+/, "");
+	const normalizedRoot = resolve(root);
+	const absolute = resolve(normalizedRoot, cleaned);
+	if (absolute !== normalizedRoot && !absolute.startsWith(`${normalizedRoot}/`)) throw diagnostics.DP_ASSETS_0001({ path: relativePath });
+	return absolute;
+}
+//#endregion
+//#region src/node/context.ts
+const configs = /* @__PURE__ */ new WeakMap();
+const contexts = /* @__PURE__ */ new WeakMap();
+/**
+* Record the managed directory and write policy for a context. Called from
+* the devframe's `setup` before any RPC handler runs.
+*/
+function configureAssets(ctx, config) {
+	configs.set(ctx, config);
+	contexts.delete(ctx);
+}
+/**
+* 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.
+*/
+function getAssetsContext(ctx) {
+	const existing = contexts.get(ctx);
+	if (existing) return existing;
+	const config = configs.get(ctx);
+	const dir = config?.dir ?? ctx.cwd;
+	const built = {
+		dir,
+		write: config?.write ?? true,
+		uploadExtensions: config?.uploadExtensions ?? "*",
+		baseURL: config?.baseURL ?? "/",
+		uploadChannel: config?.uploadChannel,
+		resolvePath: (relativePath) => resolveAssetPath(dir, relativePath)
+	};
+	contexts.set(ctx, built);
+	return built;
+}
+//#endregion
+//#region src/rpc/functions/upload.ts
+const defineAssetsRpc$9 = createDefineWrapperWithContext();
+/** Streaming channel name, namespaced like every other RPC name in this plugin. */
+const UPLOAD_CHANNEL = "devframes:plugin:assets:upload";
+function isExtensionAllowed(path, allowed) {
+	if (allowed === "*") return true;
+	const ext = extname(path).slice(1).toLowerCase();
+	return allowed.includes(ext);
+}
+/**
+* Allocates an upload and returns a streaming id. Actual bytes flow over
+* the `upload` channel opened in `setupAssets` — see the client-side
+* `useUpload` hook for the matching `rpc.streaming.upload()` call.
+*/
+const upload = defineAssetsRpc$9({
+	name: "devframes:plugin:assets:upload",
+	type: "action",
+	jsonSerializable: true,
+	args: [v.object({ path: v.string() })],
+	returns: v.object({ uploadId: v.string() }),
+	agent: {
+		title: "Upload an asset",
+		description: "Allocate an upload slot for a new file at the given path. The caller streams the bytes over the paired upload channel.",
+		safety: "action",
+		tags: ["assets"]
+	},
+	setup: (ctx) => {
+		const assets = getAssetsContext(ctx);
+		return { 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);
+			await fsp.mkdir(dirname(absolute), { recursive: true });
+			const channel = assets.uploadChannel;
+			if (!channel) throw diagnostics.DP_ASSETS_0007();
+			const reader = channel.openInbound();
+			(async () => {
+				const file = createWriteStream(absolute);
+				try {
+					for await (const chunk of reader) file.write(chunk);
+				} catch {
+					file.close();
+					await fsp.unlink(absolute).catch(() => {});
+					return;
+				}
+				file.close();
+			})();
+			return { uploadId: reader.id };
+		}) };
+	}
+});
+/**
+* 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
+* `canWrite`-gating idea the git plugin's `GitStatus.canWrite` follows.
+*/
+const capabilities = createDefineWrapperWithContext()({
+	name: "devframes:plugin:assets:capabilities",
+	type: "query",
+	snapshot: true,
+	jsonSerializable: true,
+	args: [],
+	returns: v.object({
+		write: v.boolean(),
+		uploadExtensions: v.union([v.array(v.string()), v.literal("*")])
+	}),
+	agent: {
+		title: "Read assets capabilities",
+		description: "Read whether upload, rename, delete, and folder creation are enabled, and which upload extensions are allowed.",
+		safety: "read",
+		tags: ["assets"]
+	},
+	setup: (ctx) => {
+		const assets = getAssetsContext(ctx);
+		return { handler: (async () => ({
+			write: assets.write,
+			uploadExtensions: assets.uploadExtensions
+		})) };
+	}
+});
+/** One request covers both single- and multi-select delete. */
+const deleteAssets = createDefineWrapperWithContext()({
+	name: "devframes:plugin:assets:delete",
+	type: "action",
+	jsonSerializable: true,
+	args: [v.object({ paths: v.array(v.string()) })],
+	returns: v.object({ deleted: v.array(v.string()) }),
+	agent: {
+		title: "Delete assets",
+		description: "Delete one or more assets from the managed directory.",
+		safety: "destructive",
+		tags: ["assets"]
+	},
+	setup: (ctx) => {
+		const assets = getAssetsContext(ctx);
+		return { handler: (async ({ paths }) => {
+			const deleted = [];
+			for (const path of paths) {
+				const absolute = assets.resolvePath(path);
+				try {
+					await fsp.unlink(absolute);
+					deleted.push(path);
+				} catch (error) {
+					if (error.code !== "ENOENT") throw error;
+				}
+			}
+			return { deleted };
+		}) };
+	}
+});
+//#endregion
+//#region src/node/scanner.ts
+const reImage = /\.(?:png|jpe?g|jxl|gif|svg|webp|avif|ico|bmp|tiff?)$/i;
+const reVideo = /\.(?:mp4|webm|ogv|mov|avi|flv|wmv|mpg|mpeg|mkv|3gp|3g2|ts|mts|m2ts|vob|ogm|ogx|rm|rmvb|asf|amv|divx|m4v|svi|viv|f4v|f4p|f4a|f4b)$/i;
+const reAudio = /\.(?:mp3|wav|ogg|flac|aac|wma|alac|ape|ac3|dts|tta|opus|amr|aiff|au|mid|midi|ra|rm|wv|weba|dss|spx|vox|tak|dsf|dff|dsd|cda)$/i;
+const reFont = /\.(?:woff2?|eot|ttf|otf|ttc|pfa|pfb|pfm|afm)$/i;
+const reText = /\.(?:json[5c]?|te?xt|[mc]?[jt]sx?|md[cx]?|markdown|ya?ml|toml|csv|css|scss|less|styl|html?|xml|vue|svelte|astro|env|ini|conf|sh)$/i;
+/** Classifies a path by extension, driving preview and icon choice. */
+function guessAssetType(path) {
+	if (reImage.test(path)) return "image";
+	if (reVideo.test(path)) return "video";
+	if (reAudio.test(path)) return "audio";
+	if (reFont.test(path)) return "font";
+	if (reText.test(path)) return "text";
+	return "other";
+}
+function toPublicPath(baseURL, posixPath) {
+	return joinURL(baseURL, posixPath.split("/").map(encodeURIComponent).join("/"));
+}
+/** Builds an {@link AssetInfo} from an already-resolved `fs.Stats`. */
+function statToAssetInfo(dir, baseURL, relPath, stat) {
+	const posixPath = relPath.replace(/\\/g, "/");
+	return {
+		path: posixPath,
+		type: guessAssetType(posixPath),
+		publicPath: toPublicPath(baseURL, posixPath),
+		size: stat.size,
+		mtime: stat.mtimeMs
+	};
+}
+/** Recursively lists every file under `dir`, sorted alphabetically by path. */
+async function scanAssets(dir, baseURL) {
+	const files = await glob(["**/*"], {
+		cwd: dir,
+		onlyFiles: true,
+		dot: false
+	});
+	return (await Promise.all(files.map(async (relPath) => {
+		try {
+			return statToAssetInfo(dir, baseURL, relPath, await fsp.lstat(join(dir, relPath)));
+		} catch {
+			return;
+		}
+	}))).filter((info) => info !== void 0).sort((a, b) => a.path.localeCompare(b.path));
+}
+//#endregion
+//#region src/rpc/functions/list.ts
+const defineAssetsRpc$6 = createDefineWrapperWithContext();
+const assetInfoSchema = v.object({
+	path: v.string(),
+	type: v.picklist([
+		"image",
+		"font",
+		"video",
+		"audio",
+		"text",
+		"other"
+	]),
+	publicPath: v.string(),
+	size: v.number(),
+	mtime: v.number()
+});
+const list = defineAssetsRpc$6({
+	name: "devframes:plugin:assets:list",
+	type: "query",
+	snapshot: true,
+	jsonSerializable: true,
+	args: [],
+	returns: v.array(assetInfoSchema),
+	agent: {
+		title: "List managed assets",
+		description: "List every file under the managed directory with its type, size, and last-modified time.",
+		safety: "read",
+		tags: ["assets", "files"]
+	},
+	setup: (ctx) => {
+		const assets = getAssetsContext(ctx);
+		return { handler: (async () => scanAssets(assets.dir, assets.baseURL)) };
+	}
+});
+const mkdir = createDefineWrapperWithContext()({
+	name: "devframes:plugin:assets:mkdir",
+	type: "action",
+	jsonSerializable: true,
+	args: [v.object({ path: v.string() })],
+	returns: v.void(),
+	agent: {
+		title: "Create a folder",
+		description: "Create a folder under the managed directory, including any missing parent folders.",
+		safety: "action",
+		tags: ["assets"]
+	},
+	setup: (ctx) => {
+		const assets = getAssetsContext(ctx);
+		return { handler: (async ({ path }) => {
+			const absolute = assets.resolvePath(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 });
+		}) };
+	}
+});
+/**
+* Reuses devframe's `launchEditor` utility (the same one backing the core
+* `devframe:open-in-editor` recipe) but resolves the path against the
+* managed directory first, so the client only ever sends a root-relative
+* path — never the server's absolute filesystem layout.
+*/
+const openInEditor = createDefineWrapperWithContext()({
+	name: "devframes:plugin:assets:open-in-editor",
+	type: "action",
+	jsonSerializable: true,
+	args: [v.string()],
+	returns: v.void(),
+	agent: {
+		title: "Open an asset in the editor",
+		description: "Open an asset in the user's configured editor.",
+		safety: "action",
+		tags: ["assets"]
+	},
+	setup: (ctx) => {
+		const assets = getAssetsContext(ctx);
+		return { handler: (async (path) => {
+			launchEditor(assets.resolvePath(path));
+		}) };
+	}
+});
+const readImageMeta = createDefineWrapperWithContext()({
+	name: "devframes:plugin:assets:read-image-meta",
+	type: "query",
+	jsonSerializable: true,
+	args: [v.string()],
+	returns: v.nullable(v.object({
+		width: v.optional(v.number()),
+		height: v.optional(v.number()),
+		orientation: v.optional(v.number())
+	})),
+	agent: {
+		title: "Read image dimensions",
+		description: "Read width, height, and orientation for an image asset.",
+		safety: "read",
+		tags: ["assets", "images"]
+	},
+	setup: (ctx) => {
+		const assets = getAssetsContext(ctx);
+		return { handler: (async (path) => {
+			try {
+				const meta = imageMeta(await fsp.readFile(assets.resolvePath(path)));
+				return {
+					width: meta.width,
+					height: meta.height,
+					orientation: meta.orientation
+				};
+			} catch {
+				return null;
+			}
+		}) };
+	}
+});
+//#endregion
+//#region src/rpc/functions/read-text.ts
+const defineAssetsRpc$2 = createDefineWrapperWithContext();
+const DEFAULT_LIMIT = 5e3;
+const readText = defineAssetsRpc$2({
+	name: "devframes:plugin:assets:read-text",
+	type: "query",
+	jsonSerializable: true,
+	args: [v.string(), v.optional(v.number())],
+	returns: v.nullable(v.string()),
+	agent: {
+		title: "Read a text asset",
+		description: "Read the (possibly truncated) text content of a text-type asset, for preview or editing.",
+		safety: "read",
+		tags: ["assets", "text"]
+	},
+	setup: (ctx) => {
+		const assets = getAssetsContext(ctx);
+		return { handler: (async (path, limit = DEFAULT_LIMIT) => {
+			try {
+				return (await fsp.readFile(assets.resolvePath(path), "utf-8")).slice(0, limit);
+			} catch {
+				return null;
+			}
+		}) };
+	}
+});
+const rename = createDefineWrapperWithContext()({
+	name: "devframes:plugin:assets:rename",
+	type: "action",
+	jsonSerializable: true,
+	args: [v.object({
+		path: v.string(),
+		newName: v.string()
+	})],
+	returns: assetInfoSchema,
+	agent: {
+		title: "Rename an asset",
+		description: "Rename an asset, keeping it in the same folder.",
+		safety: "destructive",
+		tags: ["assets"]
+	},
+	setup: (ctx) => {
+		const assets = getAssetsContext(ctx);
+		return { 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);
+			if (from === to) {
+				const stat = await fsp.lstat(from);
+				return statToAssetInfo(assets.dir, assets.baseURL, path, stat);
+			}
+			if (await fsp.access(to).then(() => true).catch(() => false)) throw diagnostics.DP_ASSETS_0003({ path: nextRelPath });
+			await fsp.mkdir(dirname(to), { recursive: true });
+			try {
+				await fsp.rename(from, to);
+			} catch (error) {
+				if (error.code === "ENOENT") throw diagnostics.DP_ASSETS_0004({ path });
+				throw error;
+			}
+			const stat = await fsp.lstat(to);
+			return statToAssetInfo(assets.dir, assets.baseURL, nextRelPath, stat);
+		}) };
+	}
+});
+/**
+* Reuses devframe's `open` utility (the same one backing the core
+* `devframe:open-in-finder` recipe), opening the asset's containing folder
+* so it's revealed in the OS file manager rather than launched with its
+* default app (which `download` already covers).
+*/
+const revealInFolder = createDefineWrapperWithContext()({
+	name: "devframes:plugin:assets:reveal-in-folder",
+	type: "action",
+	jsonSerializable: true,
+	args: [v.string()],
+	returns: v.void(),
+	agent: {
+		title: "Reveal an asset in the file manager",
+		description: "Open the OS file manager at the asset's containing folder.",
+		safety: "action",
+		tags: ["assets"]
+	},
+	setup: (ctx) => {
+		const assets = getAssetsContext(ctx);
+		return { handler: (async (path) => {
+			await open(dirname(assets.resolvePath(path)));
+		}) };
+	}
+});
+//#endregion
+//#region src/rpc/index.ts
+/** Read-only RPC — always registered. */
+const readFunctions = [
+	list,
+	readImageMeta,
+	readText,
+	capabilities
+];
+/**
+* Informational actions — launch external apps, never touch the managed
+* directory's contents. Always registered regardless of `write`.
+*/
+const alwaysFunctions = [openInEditor, revealInFolder];
+/** Mutating RPC — registered only when write actions are enabled. */
+const writeFunctions = [
+	upload,
+	rename,
+	deleteAssets,
+	mkdir
+];
+const serverFunctions = [
+	...readFunctions,
+	...alwaysFunctions,
+	...writeFunctions
+];
+//#endregion
+export { UPLOAD_CHANNEL as _, revealInFolder as a, getAssetsContext as b, readImageMeta as c, assetInfoSchema as d, list as f, capabilities as g, deleteAssets as h, writeFunctions as i, openInEditor as l, scanAssets as m, readFunctions as n, rename as o, guessAssetType as p, serverFunctions as r, readText as s, alwaysFunctions as t, mkdir as u, upload as v, resolveAssetPath as x, configureAssets as y };