@dsh-xhl/dsh-file-explorer 0.1.0

package/lib/index.js

@@ -0,0 +1,639 @@
+import { mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+//#region src/trust-fence.ts
+function header(headers, name) {
+	const value = headers[name];
+	return typeof value === "string" ? value : void 0;
+}
+function parseAuthority(authority) {
+	try {
+		return new URL(`http://${authority}`);
+	} catch {
+		return;
+	}
+}
+/** Whether a normalized URL hostname names the local loopback authority. */
+function isLoopbackHostname(hostname) {
+	if (hostname === "localhost" || hostname === "[::1]") return true;
+	const parts = hostname.split(".");
+	return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+/**
+* Decide whether one request may reach the plugin routes. Only loopback
+* Host authorities pass (the DSH web GUI is served from 127.0.0.1/localhost);
+* cross-site browser requests are refused.
+*/
+function isTrustedApiRequest(request) {
+	const host = header(request.headers, "host");
+	if (host === void 0) return false;
+	const hostUrl = parseAuthority(host);
+	if (hostUrl === void 0) return false;
+	if (!isLoopbackHostname(hostUrl.hostname)) return false;
+	if (header(request.headers, "sec-fetch-site") === "cross-site") return false;
+	const origin = header(request.headers, "origin");
+	if (origin === void 0) return true;
+	try {
+		return new URL(origin).host === hostUrl.host;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/index.ts
+/**
+* dsh-file-explorer host half: the /filex JSON API (session cwd, file list,
+* read / write / content search) and the /filex/file media route (images /
+* PDFs). Every route passes the same loopback browser-trust fence.
+*
+* All operations are conversation-scoped: requests carry a sessionId and the
+* session's authoritative cwd comes from the session store.
+*/
+/** Plugin identity for cordis.yml rows. */
+const name = "dsh-file-explorer";
+/** Services required before mounting: the webserver routes and the session store. */
+const inject = ["webServer", "sessions"];
+/** Media content types by extension. */
+const MEDIA_TYPES = {
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".webp": "image/webp",
+	".svg": "image/svg+xml",
+	".bmp": "image/bmp",
+	".ico": "image/x-icon",
+	".avif": "image/avif",
+	".pdf": "application/pdf"
+};
+/** Directories never listed by the explorer / search. */
+const IGNORED_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	".hg",
+	".svn",
+	".dsh",
+	".next",
+	".nuxt",
+	".output",
+	"dist",
+	"build",
+	"out",
+	"coverage",
+	".turbo",
+	".cache",
+	".yarn",
+	".pnpm-store",
+	"target",
+	".venv",
+	"venv",
+	"__pycache__",
+	".pytest_cache",
+	".mypy_cache",
+	".idea",
+	".vscode",
+	"release",
+	"vendor",
+	"bin",
+	"obj",
+	".expo",
+	"Pods",
+	"DerivedData"
+]);
+const MAX_FILES = 3e4;
+const MAX_PREVIEW = 1048576;
+const MAX_SEARCH_FILE = 1048576;
+const MAX_SEARCH_MATCHES = 1e3;
+const MAX_MEDIA = 31457280;
+/** One wire failure carrying a stable code. */
+var FilexError = class extends Error {
+	code;
+	status;
+	constructor(code, message, status = 400) {
+		super(message);
+		this.code = code;
+		this.status = status;
+	}
+};
+function requireString(payload, key) {
+	const value = payload[key];
+	if (typeof value !== "string" || value === "") throw new FilexError("bad-request", `missing or invalid "${key}"`);
+	return value;
+}
+/** Resolve a request path (absolute or cwd-relative) and fence it inside the session cwd. */
+function resolvePathWithin(cwd, raw) {
+	const abs = isAbsolute(raw) ? resolve(raw) : resolve(join(cwd, raw));
+	if (!isWithin(cwd, abs)) throw new FilexError("forbidden", "path outside the session working directory", 403);
+	return abs;
+}
+/** Canonical containment check (case-aware on Windows, separator-normalized). */
+function isWithin(parent, child) {
+	const p = resolve(parent);
+	const c = resolve(child);
+	if (c === p) return true;
+	return c.startsWith(p + "\\") || c.startsWith(p + "/") || c.startsWith(p + "\\") || c.startsWith(p + "/");
+}
+/** Resolve a session's authoritative working directory (header cwd first, process cwd last). */
+function sessionCwdOf(ctx, sessionId) {
+	const headerCwd = ctx.sessions.get(sessionId)?.header.cwd;
+	if (headerCwd !== void 0 && headerCwd !== "") return resolve(headerCwd);
+	return process.cwd();
+}
+async function readJsonBody(req) {
+	let raw = "";
+	for await (const chunk of req) raw += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+	if (raw === "") return {};
+	try {
+		const parsed = JSON.parse(raw);
+		if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) return parsed;
+	} catch {}
+	throw new FilexError("bad-request", "invalid JSON body");
+}
+function writeJson(res, status, value) {
+	res.writeHead(status, { "content-type": "application/json" });
+	res.end(JSON.stringify(value));
+}
+function writeOk(res, value) {
+	writeJson(res, 200, {
+		ok: true,
+		value
+	});
+}
+function writeError(res, error) {
+	if (error instanceof FilexError) {
+		writeJson(res, error.status, {
+			ok: false,
+			error: {
+				code: error.code,
+				message: error.message
+			}
+		});
+		return;
+	}
+	writeJson(res, 500, {
+		ok: false,
+		error: {
+			code: "internal",
+			message: error instanceof Error ? error.message : String(error)
+		}
+	});
+}
+/**
+* Recursively walk a directory tree, invoking onFile for every regular file.
+* Skips IGNORED_DIRS; stops at MAX_FILES. The callback may return false to
+* stop early (or a Promise resolving to false / void for async callbacks).
+*
+* `opts.withSize` gates the per-file stat: listing does not need sizes (the
+* client never displays them), and skipping the stat keeps large-workspace
+* listings fast (stat on tens of thousands of files is seconds on Windows).
+* Content search still opts in, because it skips files bigger than the
+* search cap.
+*/
+async function walkFiles(cwd, onFile, opts = {}) {
+	const withSize = opts.withSize === true;
+	let count = 0;
+	let truncated = false;
+	const queue = [{
+		abs: cwd,
+		rel: ""
+	}];
+	while (queue.length > 0) {
+		if (truncated) break;
+		const cur = queue.pop();
+		let entries;
+		try {
+			entries = await readdir(cur.abs, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (let i = entries.length - 1; i >= 0; i--) {
+			if (truncated) break;
+			const entry = entries[i];
+			const childAbs = join(cur.abs, entry.name);
+			const childRel = cur.rel === "" ? entry.name : `${cur.rel}/${entry.name}`;
+			if (entry.isDirectory()) {
+				if (IGNORED_DIRS.has(entry.name)) continue;
+				queue.push({
+					abs: childAbs,
+					rel: childRel
+				});
+			} else if (entry.isFile()) {
+				count++;
+				let size = 0;
+				if (withSize) try {
+					size = (await stat(childAbs)).size;
+				} catch {
+					size = 0;
+				}
+				if (onFile(childAbs, childRel, size) === false) truncated = true;
+				else if (count >= MAX_FILES) truncated = true;
+			}
+		}
+	}
+	return truncated;
+}
+/** Text read with the size cap; binary detection via NUL probe. */
+async function readTextFile(path) {
+	const info = await stat(path).catch(() => {
+		throw new FilexError("fs-error", `cannot read "${path}": not found`, 404);
+	});
+	if (info.isDirectory()) throw new FilexError("fs-error", `"${path}" is a directory`);
+	const size = info.size;
+	const truncated = size > MAX_PREVIEW;
+	const handle = await open(path, "r").catch((error) => {
+		throw new FilexError("fs-error", `cannot read "${path}": ${error instanceof Error ? error.message : String(error)}`);
+	});
+	try {
+		const length = Math.min(size, MAX_PREVIEW);
+		const buffer = Buffer.alloc(length);
+		const { bytesRead } = await handle.read(buffer, 0, length, 0);
+		const slice = buffer.subarray(0, bytesRead);
+		if (slice.includes(0)) return {
+			kind: "binary",
+			size,
+			truncated
+		};
+		return {
+			kind: "text",
+			content: slice.toString("utf8"),
+			size,
+			truncated
+		};
+	} finally {
+		await handle.close();
+	}
+}
+function escapeRegExp(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function buildRegex(pattern, opts) {
+	const flags = opts.caseSensitive === true ? "g" : "gi";
+	let source = opts.regex === true ? pattern : escapeRegExp(pattern);
+	if (opts.wholeWord === true) source = `\\b(?:${source})\\b`;
+	return new RegExp(source, flags);
+}
+function globToRegExp(glob) {
+	let out = "";
+	for (let i = 0; i < glob.length; i++) {
+		const ch = glob[i];
+		if (ch === "*") {
+			if (glob[i + 1] === "*") {
+				out += ".*";
+				i++;
+			} else out += "[^/]*";
+		} else if (ch === "?") out += "[^/]";
+		else out += escapeRegExp(ch);
+	}
+	return new RegExp(`^${out}$`);
+}
+const GLOB_META = /[*?{\[]/;
+function parseGlobList(raw) {
+	if (!Array.isArray(raw)) return [];
+	const out = [];
+	for (const item of raw) {
+		const token = String(item).trim();
+		if (token === "") continue;
+		out.push(globToRegExp(GLOB_META.test(token) ? token : `**/${token}/**`));
+	}
+	return out;
+}
+/**
+* Launch the OS file manager pointing at `target` (a directory). Detached and
+* stdio-ignored so the spawn never blocks the host or leaks pipes; failures
+* are swallowed — the API reports unsupported platforms instead.
+*
+* NOTE: never pass `windowsHide: true` on Windows — explorer.exe honors the
+* startup show-window flag and would open its folder window hidden, making
+* the click look dead. The plain GUI-app spawn shows the window normally.
+*/
+function openInSystemFileManager(target) {
+	let command;
+	let args;
+	if (process.platform === "win32") {
+		command = "explorer";
+		args = [target];
+	} else if (process.platform === "darwin") {
+		command = "open";
+		args = [target];
+	} else if (process.platform === "linux") {
+		command = "xdg-open";
+		args = [target];
+	} else return false;
+	try {
+		const child = spawn(command, args, {
+			detached: true,
+			stdio: "ignore"
+		});
+		child.on("error", () => {});
+		child.unref();
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Resolve the directory a reveal/open action should point at. Authoritative
+* source: the session's own header cwd. When it is absent (sessions created
+* without workspace metadata fall back to the host process cwd — usually
+* meaningless), accept the loopback-only client's session-list cwd hint so
+* the folder still opens where the user works.
+*/
+function revealCwdOf(ctx, sessionId, rawHint) {
+	const headerCwd = ctx.sessions.get(sessionId)?.header.cwd;
+	const hint = typeof rawHint === "string" && rawHint !== "" ? rawHint : void 0;
+	return headerCwd !== void 0 && headerCwd !== "" ? resolve(headerCwd) : hint !== void 0 && isAbsolute(hint) ? resolve(hint) : process.cwd();
+}
+/**
+* Locate the VS Code CLI (`code`). Checks the standard install locations
+* first, then falls back to a PATH scan. Windows `code` is a .cmd shim, so
+* the caller must route it through `cmd /c` (spawn alone cannot execute it).
+*/
+async function resolveVscodeCli() {
+	const candidates = [];
+	if (process.platform === "win32") {
+		const local = process.env.LOCALAPPDATA;
+		if (local !== void 0) candidates.push(join(local, "Programs", "Microsoft VS Code", "bin", "code.cmd"));
+		const pf = process.env.ProgramFiles;
+		if (pf !== void 0) candidates.push(join(pf, "Microsoft VS Code", "bin", "code.cmd"));
+		const pf86 = process.env["ProgramFiles(x86)"];
+		if (pf86 !== void 0) candidates.push(join(pf86, "Microsoft VS Code", "bin", "code.cmd"));
+	} else if (process.platform === "darwin") candidates.push("/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code");
+	else if (process.platform === "linux") candidates.push("/usr/bin/code", "/usr/local/bin/code", "/snap/bin/code");
+	for (const candidate of candidates) try {
+		await stat(candidate);
+		return candidate;
+	} catch {}
+	const name = process.platform === "win32" ? "code.cmd" : "code";
+	const paths = (process.env.PATH ?? "").split(process.platform === "win32" ? ";" : ":");
+	for (const dir of paths) {
+		if (dir === "") continue;
+		const probe = join(dir, name);
+		try {
+			await stat(probe);
+			return probe;
+		} catch {}
+	}
+	return null;
+}
+/**
+* Launch VS Code pointed at `target` (a directory). On Windows the CLI is a
+* .cmd shim, so it is routed through `cmd /c` with the console hidden (the
+* hidden console belongs to cmd only — the Code GUI window is unaffected).
+*/
+function openInVscode(cli, target) {
+	try {
+		const child = process.platform === "win32" ? spawn("cmd", [
+			"/c",
+			cli,
+			target
+		], {
+			detached: true,
+			stdio: "ignore",
+			windowsHide: true
+		}) : spawn(cli, [target], {
+			detached: true,
+			stdio: "ignore"
+		});
+		child.on("error", () => {});
+		child.unref();
+		return true;
+	} catch {
+		return false;
+	}
+}
+function buildApi(ctx) {
+	const cwdOf = (payload) => {
+		const sessionId = requireString(payload, "sessionId");
+		return {
+			sessionId,
+			cwd: sessionCwdOf(ctx, sessionId)
+		};
+	};
+	return {
+		"session.cwd": (payload) => {
+			const { sessionId, cwd } = cwdOf(payload);
+			return {
+				sessionId,
+				cwd,
+				root: basename(cwd)
+			};
+		},
+		"fs.list": async (payload) => {
+			const { cwd } = cwdOf(payload);
+			const files = [];
+			const truncated = await walkFiles(cwd, (_abs, rel) => {
+				files.push({
+					name: rel.split("/").pop() ?? rel,
+					relPath: rel,
+					size: 0
+				});
+				return true;
+			});
+			files.sort((a, b) => a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0);
+			return {
+				root: cwd,
+				files,
+				truncated
+			};
+		},
+		"fs.read": async (payload) => {
+			const { cwd } = cwdOf(payload);
+			return readTextFile(resolvePathWithin(cwd, requireString(payload, "path")));
+		},
+		"fs.write": async (payload) => {
+			const { cwd } = cwdOf(payload);
+			const raw = requireString(payload, "path");
+			const content = requireString(payload, "content");
+			const path = resolvePathWithin(cwd, raw);
+			const tmp = `${path}.dsh-filex-tmp-${process.pid}`;
+			try {
+				await mkdir(dirname(path), { recursive: true });
+				await writeFile(tmp, content, "utf8");
+				await rename(tmp, path);
+			} catch (error) {
+				await rm(tmp, { force: true }).catch(() => {});
+				throw new FilexError("fs-error", `cannot write "${path}": ${error instanceof Error ? error.message : String(error)}`);
+			}
+			return { ok: true };
+		},
+		"fs.reveal": async (payload) => {
+			const { sessionId } = cwdOf(payload);
+			const cwd = revealCwdOf(ctx, sessionId, payload.cwd);
+			if (!(await stat(cwd).catch(() => {
+				throw new FilexError("fs-error", `cannot open "${cwd}": not found`, 404);
+			})).isDirectory()) throw new FilexError("fs-error", `"${cwd}" is not a directory`);
+			if (!openInSystemFileManager(cwd)) throw new FilexError("unsupported", "current platform has no file-manager launcher", 501);
+			return {
+				ok: true,
+				cwd
+			};
+		},
+		"fs.vscode": async (payload) => {
+			const { sessionId } = cwdOf(payload);
+			const cwd = revealCwdOf(ctx, sessionId, payload.cwd);
+			if (!(await stat(cwd).catch(() => {
+				throw new FilexError("fs-error", `cannot open "${cwd}": not found`, 404);
+			})).isDirectory()) throw new FilexError("fs-error", `"${cwd}" is not a directory`);
+			const cli = await resolveVscodeCli();
+			if (cli === null) throw new FilexError("vscode-not-found", "未找到 VS Code 命令行工具（code）。请确认 VS Code 已安装且勾选了“添加到 PATH”", 404);
+			if (!openInVscode(cli, cwd)) throw new FilexError("unsupported", "failed to launch the VS Code CLI", 501);
+			return {
+				ok: true,
+				cwd,
+				cli
+			};
+		},
+		"fs.capabilities": async () => {
+			return { vscode: await resolveVscodeCli() !== null };
+		},
+		"fs.search": async (payload) => {
+			const { cwd } = cwdOf(payload);
+			const pattern = requireString(payload, "pattern").trim();
+			if (pattern === "") return {
+				results: [],
+				truncated: false
+			};
+			const record = payload;
+			const opts = typeof record.options === "object" && record.options !== null ? record.options : {};
+			let re;
+			try {
+				re = buildRegex(pattern, opts);
+			} catch (error) {
+				throw new FilexError("bad-request", `invalid regular expression: ${error instanceof Error ? error.message : String(error)}`);
+			}
+			const include = parseGlobList(record.include);
+			const exclude = parseGlobList(record.exclude);
+			const results = [];
+			let truncated = false;
+			await walkFiles(cwd, async (abs, rel, size) => {
+				if (include.length > 0 && !include.some((rx) => rx.test(rel))) return true;
+				if (exclude.some((rx) => rx.test(rel))) return true;
+				if (size > MAX_SEARCH_FILE) return true;
+				let text;
+				try {
+					const result = await readTextFile(abs);
+					if (result.kind !== "text") return true;
+					text = result.content;
+				} catch {
+					return true;
+				}
+				const lines = text.split("\n");
+				for (let i = 0; i < lines.length; i++) {
+					re.lastIndex = 0;
+					const highlights = [];
+					let match;
+					while ((match = re.exec(lines[i])) !== null) {
+						highlights.push({
+							start: match.index,
+							end: match.index + match[0].length
+						});
+						if (match[0].length === 0) re.lastIndex++;
+						if (highlights.length >= 200) break;
+					}
+					if (highlights.length > 0) {
+						results.push({
+							file: rel,
+							line: i + 1,
+							text: lines[i],
+							highlights
+						});
+						if (results.length >= MAX_SEARCH_MATCHES) {
+							truncated = true;
+							return false;
+						}
+					}
+				}
+				return true;
+			}, { withSize: true });
+			return {
+				results,
+				truncated
+			};
+		}
+	};
+}
+function apply(ctx) {
+	const fence = (req) => isTrustedApiRequest(req);
+	const api = buildApi(ctx);
+	ctx.effect(() => ctx.webServer.register({
+		kind: "prefix",
+		path: "/filex/api",
+		handler: async (req, res) => {
+			if (!fence(req)) {
+				writeJson(res, 403, {
+					ok: false,
+					error: {
+						code: "forbidden",
+						message: "forbidden"
+					}
+				});
+				return;
+			}
+			if (req.method !== "POST") {
+				writeJson(res, 405, {
+					ok: false,
+					error: {
+						code: "method-error",
+						message: "method not allowed"
+					}
+				});
+				return;
+			}
+			const pathname = new URL(req.url ?? "/", "http://dsh.internal").pathname;
+			const method = pathname.startsWith("/filex/api/") ? pathname.slice(11) : void 0;
+			if (method === void 0 || method.includes("/")) {
+				writeError(res, new FilexError("not-found", "unknown filex API method", 404));
+				return;
+			}
+			try {
+				const payload = await readJsonBody(req);
+				const handler = api[method];
+				if (handler === void 0) throw new FilexError("not-found", `unknown filex API method "${method}"`, 404);
+				writeOk(res, await handler(payload));
+			} catch (error) {
+				writeError(res, error);
+			}
+		}
+	}), "dsh-file-explorer: /filex/api routes");
+	ctx.effect(() => ctx.webServer.register({
+		kind: "prefix",
+		path: "/filex/file",
+		handler: async (req, res) => {
+			if (!fence(req)) {
+				res.writeHead(403);
+				res.end("forbidden");
+				return;
+			}
+			if (req.method !== "GET") {
+				res.writeHead(405);
+				res.end();
+				return;
+			}
+			try {
+				const url = new URL(req.url ?? "/", "http://dsh.internal");
+				const sessionId = url.searchParams.get("sessionId");
+				const raw = url.searchParams.get("path");
+				if (sessionId === null || raw === null) throw new FilexError("bad-request", "sessionId and path are required");
+				const path = resolvePathWithin(sessionCwdOf(ctx, sessionId), raw);
+				const info = await stat(path);
+				if (!info.isFile() || info.size > MAX_MEDIA) throw new FilexError("fs-error", "not a file or too large");
+				const lower = path.toLowerCase();
+				const type = Object.keys(MEDIA_TYPES).find((ext) => lower.endsWith(ext));
+				const headers = {
+					"content-type": type ? MEDIA_TYPES[type] : "application/octet-stream",
+					"cache-control": "no-cache",
+					"x-content-type-options": "nosniff",
+					"referrer-policy": "no-referrer"
+				};
+				if (url.searchParams.get("download") === "1") headers["content-disposition"] = `attachment; filename*=UTF-8''${encodeURIComponent(basename(path))}`;
+				const body = await readFile(path);
+				res.writeHead(200, headers);
+				res.end(body);
+			} catch (error) {
+				writeError(res, error);
+			}
+		}
+	}), "dsh-file-explorer: /filex/file media route");
+}
+//#endregion
+export { apply, inject, isWithin, name };