@inteli.city/node-red-plugin-project-files 1.0.0

package/runtime/admin.js

@@ -0,0 +1,469 @@
+module.exports = function (RED) {
+  const path = require("path");
+  const fs   = require("fs");
+  const fsp  = require("fs").promises;
+
+  // ── Config ────────────────────────────────────────────────────────────────
+  // The plugin runs in one of two explicit operating modes, decided per request
+  // from the live Node-RED environment (see resolveScope()):
+  //
+  //   • Project Mode      — an active Node-RED project exists. The authoritative
+  //                         filesystem boundary is that project's directory.
+  //   • User Directory    — no active project (Projects disabled, or enabled but
+  //     Mode                no project selected). The boundary is <userDir>.
+  //
+  // PROJECTS_DIR is where Node-RED stores projects (and the path-encoding anchor
+  // for Project Mode). Override with `projectFiles.baseDir` in settings.js.
+  const cfg          = RED.settings.get("projectFiles") || {};
+  const USER_DIR     = path.resolve(RED.settings.userDir || process.cwd());
+  const PROJECTS_DIR = cfg.baseDir
+    ? path.resolve(cfg.baseDir)
+    : path.join(USER_DIR, "projects");
+  const MAX_BYTES    = cfg.maxBytes || 50 * 1024 * 1024;
+
+  // External commands. Resolved from PATH by default so the plugin is portable
+  // across OSes and installs; override the Python interpreter via
+  // `projectFiles.pythonPath` in settings.js.
+  const PYTHON = cfg.pythonPath || (process.platform === "win32" ? "python" : "python3");
+  const NPM    = process.platform === "win32" ? "npm.cmd" : "npm";
+
+  const PROTECTED_FILES = new Set([
+    "flows.json", "flows_cred.json", "package.json",
+    ".flows.json.backup", ".flows_cred.json.backup",
+    ".git",
+  ]);
+
+  // Best-effort: make sure the projects directory exists so a fresh install in
+  // Project Mode lists an empty tree instead of erroring. Never fatal — a
+  // failure here must not stop Node-RED from loading. (USER_DIR always exists.)
+  try { fs.mkdirSync(PROJECTS_DIR, { recursive: true }); }
+  catch (e) { RED.log.warn(`[project-files] could not create projects dir: ${e.code || e.message}`); }
+
+  // ── Operating-mode resolution ─────────────────────────────────────────────
+  // Read fresh on every request so switching/creating/closing a project at
+  // runtime (no NR restart) takes effect immediately. We never simulate a
+  // project when none is active — the absence of one *is* User Directory Mode.
+  function activeProjectName() {
+    try { return (RED.settings.get("projects") || {}).activeProject || null; }
+    catch (e) { return null; }
+  }
+  function projectsEnabled() {
+    try {
+      const et = RED.settings.editorTheme;
+      if (et && et.projects && typeof et.projects.enabled === "boolean") return et.projects.enabled;
+    } catch (e) { /* unknown */ }
+    return null; // undetermined — treated as "not enabled" for messaging only
+  }
+
+  // Returns the scope for the current request:
+  //   mode     — "project" | "user"
+  //   project  — active project name (Project Mode) or null
+  //   anchor   — directory that relative paths are resolved/encoded against
+  //   boundary — the authoritative security boundary; nothing may escape it
+  function resolveScope() {
+    const active = activeProjectName();
+    if (active) {
+      return {
+        mode:     "project",
+        project:  active,
+        anchor:   PROJECTS_DIR,
+        boundary: path.join(PROJECTS_DIR, active),
+      };
+    }
+    return {
+      mode:     "user",
+      project:  null,
+      anchor:   USER_DIR,
+      boundary: USER_DIR,
+    };
+  }
+
+  // Sandbox check — every request goes through this. `abs` must already be an
+  // absolute, resolved path (callers use path.resolve(scope.anchor, …)).
+  // Rejects anything outside the active boundary, including ../ traversal and
+  // sibling directories that merely share a name prefix.
+  function within(abs, boundary) {
+    const n = path.normalize(abs);
+    const b = path.normalize(boundary);
+    return n === b || n.startsWith(b + path.sep);
+  }
+
+  // Resolve a client-supplied, anchor-relative path and enforce the boundary in
+  // one step. Returns the absolute path, or null if it escapes the boundary.
+  function resolveInScope(scope, rel) {
+    const abs = path.resolve(scope.anchor, rel || ".");
+    return within(abs, scope.boundary) ? abs : null;
+  }
+  // Encode an absolute path back to an anchor-relative, forward-slash path.
+  function toRel(scope, abs) {
+    return path.relative(scope.anchor, abs).replace(/\\/g, "/");
+  }
+
+  // Map a thrown error to a generic, path-free message safe to return to the
+  // client, and log the real error server-side for operators. This keeps
+  // absolute filesystem paths and internal structure out of HTTP responses.
+  function safeErr(e) {
+    switch (e && e.code) {
+      case "ENOENT":  return "File or folder not found";
+      case "EACCES":
+      case "EPERM":   return "Permission denied";
+      case "EEXIST":  return "A file or folder with that name already exists";
+      case "ENOTDIR": return "Path is not a directory";
+      case "EISDIR":  return "Path is a directory";
+      case "ENOSPC":  return "No space left on device";
+      case "EROFS":   return "Filesystem is read-only";
+      default:        return "Operation failed";
+    }
+  }
+  function logErr(where, e) {
+    RED.log.warn(`[project-files] ${where}: ${(e && (e.stack || e.message)) || e}`);
+  }
+  // Generic out-of-scope rejection — never reveals the boundary path itself.
+  const OUT_OF_SCOPE = "Path is outside the allowed scope for the current mode";
+
+  async function trystat(abs) {
+    try { return await fsp.stat(abs); } catch { return null; }
+  }
+
+  // ── Auth middleware ───────────────────────────────────────────────────────
+  const canRead  = RED.auth.needsPermission("projectFiles.read");
+  const canWrite = RED.auth.needsPermission("projectFiles.write");
+
+  // ── Routes ────────────────────────────────────────────────────────────────
+
+  // Config: tell the client the active mode and the directory scope it manages.
+  RED.httpAdmin.get("/project-files/config", canRead, (req, res) => {
+    const scope = resolveScope();
+    res.json({
+      mode:            scope.mode,            // "project" | "user"
+      activeProject:   scope.project,         // name, or null in User Directory Mode
+      projectsEnabled: projectsEnabled(),     // true | false | null (undetermined)
+      baseDir:         scope.anchor,          // path-encoding anchor (for "copy path"/labels)
+      scopeDir:        scope.boundary,        // the authoritative boundary for this mode
+      userDir:         USER_DIR,
+    });
+  });
+
+  // List directory contents.
+  RED.httpAdmin.get("/project-files/list", canRead, async (req, res) => {
+    try {
+      const scope  = resolveScope();
+      const dirAbs = resolveInScope(scope, req.query.path || ".");
+      if (!dirAbs) return res.status(400).json({ error: OUT_OF_SCOPE });
+
+      const ents = await fsp.readdir(dirAbs, { withFileTypes: true });
+      const items = [];
+      for (const de of ents) {
+        const full = path.join(dirAbs, de.name);
+        const st   = await trystat(full);
+        items.push({
+          name:  de.name,
+          path:  toRel(scope, full),
+          type:  de.isDirectory() ? "dir" : "file",
+          size:  st ? st.size  : 0,
+          mtime: st ? st.mtimeMs : 0,
+        });
+      }
+      items.sort((a, b) => {
+        if (a.type !== b.type) return a.type === "dir" ? -1 : 1;
+        return a.name.localeCompare(b.name);
+      });
+
+      const rel = toRel(scope, dirAbs) || ".";
+      res.json({
+        mode:       scope.mode,
+        baseDir:    scope.anchor,
+        scopeDir:   scope.boundary,
+        cwd:        rel,
+        items,
+        breadcrumb: rel === "." ? [] : rel.split("/").filter(Boolean),
+      });
+    } catch (e) { logErr("list", e); res.status(400).json({ error: safeErr(e) }); }
+  });
+
+  // Open a text file for reading.
+  RED.httpAdmin.get("/project-files/open", canRead, async (req, res) => {
+    try {
+      const scope = resolveScope();
+      const abs = resolveInScope(scope, req.query.path || "");
+      if (!abs) return res.status(400).json({ error: OUT_OF_SCOPE });
+      const st = await fsp.stat(abs);
+      if (!st.isFile()) return res.status(400).json({ error: "Not a file" });
+      if (st.size > MAX_BYTES) return res.status(400).json({ error: "File too large" });
+      const buf = await fsp.readFile(abs);
+      if (buf.includes(0)) return res.status(400).json({ error: "Binary file not supported" });
+      res.json({ text: buf.toString("utf8"), size: st.size, mtime: st.mtimeMs });
+    } catch (e) { logErr("open", e); res.status(400).json({ error: safeErr(e) }); }
+  });
+
+  // Stat a file (used by the on-disk-change poller).
+  RED.httpAdmin.get("/project-files/stat", canRead, async (req, res) => {
+    try {
+      const scope = resolveScope();
+      const abs = resolveInScope(scope, req.query.path || "");
+      if (!abs) return res.status(400).json({ error: OUT_OF_SCOPE });
+      const st = await fsp.stat(abs);
+      if (!st.isFile()) return res.status(400).json({ error: "Not a file" });
+      res.json({ size: st.size, mtime: st.mtimeMs });
+    } catch (e) { logErr("stat", e); res.status(400).json({ error: safeErr(e) }); }
+  });
+
+  // Write (save) a text file.
+  RED.httpAdmin.post("/project-files/save", canWrite, async (req, res) => {
+    try {
+      const scope = resolveScope();
+      const { path: rel, text } = req.body || {};
+      if (!rel) return res.status(400).json({ error: "Missing path" });
+      const abs = resolveInScope(scope, rel);
+      if (!abs) return res.status(400).json({ error: OUT_OF_SCOPE });
+      const dirSt = await trystat(path.dirname(abs));
+      if (!dirSt || !dirSt.isDirectory()) return res.status(400).json({ error: "Parent folder missing" });
+      const buf = Buffer.from(String(text ?? ""), "utf8");
+      if (buf.length > MAX_BYTES) return res.status(400).json({ error: "Content too large" });
+      await fsp.writeFile(abs, buf);
+      const st = await trystat(abs);
+      res.json({ ok: true, size: st?.size ?? buf.length, mtime: st?.mtimeMs ?? Date.now() });
+    } catch (e) { logErr("save", e); res.status(400).json({ error: safeErr(e) }); }
+  });
+
+  // Create an empty file.
+  RED.httpAdmin.post("/project-files/new-file", canWrite, async (req, res) => {
+    try {
+      const scope = resolveScope();
+      const { dir, name } = req.body || {};
+      if (!name || /[\\/:*?"<>|]/.test(name)) return res.status(400).json({ error: "Invalid filename" });
+      const abs = resolveInScope(scope, path.join(dir || ".", name));
+      if (!abs) return res.status(400).json({ error: OUT_OF_SCOPE });
+      if (await trystat(abs)) return res.status(400).json({ error: "File already exists" });
+      await fsp.writeFile(abs, "");
+      const st = await trystat(abs);
+      res.json({ ok: true, path: toRel(scope, abs), size: st?.size ?? 0, mtime: st?.mtimeMs ?? Date.now() });
+    } catch (e) { logErr("new-file", e); res.status(400).json({ error: safeErr(e) }); }
+  });
+
+  // Move a file into a target directory.
+  RED.httpAdmin.post("/project-files/move", canWrite, async (req, res) => {
+    try {
+      const scope = resolveScope();
+      const { path: rel, dir, overwrite } = req.body || {};
+      if (!rel || !dir) return res.status(400).json({ error: "Missing path or dir" });
+      const srcAbs = resolveInScope(scope, rel);
+      if (!srcAbs) return res.status(400).json({ error: OUT_OF_SCOPE });
+      if (PROTECTED_FILES.has(path.basename(srcAbs))) return res.status(403).json({ error: "This file is protected and cannot be moved." });
+      const st = await trystat(srcAbs);
+      if (!st || !st.isFile()) return res.status(400).json({ error: "Source not found or not a file" });
+      const destDirAbs = resolveInScope(scope, dir);
+      if (!destDirAbs) return res.status(400).json({ error: OUT_OF_SCOPE });
+      const destDirSt = await trystat(destDirAbs);
+      if (!destDirSt || !destDirSt.isDirectory()) return res.status(400).json({ error: "Destination is not a directory" });
+      const filename = path.basename(srcAbs);
+      const destAbs  = path.join(destDirAbs, filename);
+      if (path.normalize(destAbs) === path.normalize(srcAbs))
+        return res.status(400).json({ error: "Source and destination are the same" });
+      if (await trystat(destAbs) && !overwrite)
+        return res.status(409).json({ error: "A file named \"" + filename + "\" already exists there" });
+      await fsp.rename(srcAbs, destAbs);
+      res.json({ ok: true, path: toRel(scope, destAbs) });
+    } catch (e) { logErr("move", e); res.status(400).json({ error: safeErr(e) }); }
+  });
+
+  // Upload a file (base64-encoded body).
+  RED.httpAdmin.post("/project-files/upload", canWrite, async (req, res) => {
+    try {
+      const scope = resolveScope();
+      const { dir, name, data } = req.body || {};
+      if (!name || /[\\/:*?"<>|]/.test(name)) return res.status(400).json({ error: "Invalid filename" });
+      const abs = resolveInScope(scope, path.join(dir || ".", name));
+      if (!abs) return res.status(400).json({ error: OUT_OF_SCOPE });
+      const buf = Buffer.from(data || "", "base64");
+      if (buf.length > MAX_BYTES) return res.status(400).json({ error: "File too large" });
+      await fsp.writeFile(abs, buf);
+      const st = await trystat(abs);
+      res.json({ ok: true, path: toRel(scope, abs), size: st?.size ?? buf.length });
+    } catch (e) { logErr("upload", e); res.status(400).json({ error: safeErr(e) }); }
+  });
+
+  // Rename a file or folder (same parent directory).
+  RED.httpAdmin.post("/project-files/rename", canWrite, async (req, res) => {
+    try {
+      const scope = resolveScope();
+      const { path: rel, name } = req.body || {};
+      if (!rel)  return res.status(400).json({ error: "Missing path" });
+      if (!name || /[\\/:*?"<>|]/.test(name)) return res.status(400).json({ error: "Invalid name" });
+      const abs = resolveInScope(scope, rel);
+      if (!abs) return res.status(400).json({ error: OUT_OF_SCOPE });
+      const newAbs = path.join(path.dirname(abs), name);
+      if (!within(newAbs, scope.boundary)) return res.status(400).json({ error: OUT_OF_SCOPE });
+      if (PROTECTED_FILES.has(path.basename(abs))) return res.status(403).json({ error: "This file is protected and cannot be renamed." });
+      if (await trystat(newAbs)) return res.status(400).json({ error: "Name already exists" });
+      await fsp.rename(abs, newAbs);
+      res.json({ ok: true, path: toRel(scope, newAbs) });
+    } catch (e) { logErr("rename", e); res.status(400).json({ error: safeErr(e) }); }
+  });
+
+  // Delete a file or folder (folders removed recursively).
+  RED.httpAdmin.post("/project-files/delete", canWrite, async (req, res) => {
+    try {
+      const scope = resolveScope();
+      const { path: rel } = req.body || {};
+      if (!rel) return res.status(400).json({ error: "Missing path" });
+      const abs = resolveInScope(scope, rel);
+      if (!abs) return res.status(400).json({ error: OUT_OF_SCOPE });
+      if (PROTECTED_FILES.has(path.basename(abs))) return res.status(403).json({ error: "This file is protected and cannot be deleted." });
+      const st = await trystat(abs);
+      if (!st) return res.status(400).json({ error: "Not found" });
+      await fsp.rm(abs, { recursive: true, force: true });
+      res.json({ ok: true });
+    } catch (e) { logErr("delete", e); res.status(400).json({ error: safeErr(e) }); }
+  });
+
+  // Create a directory.
+  RED.httpAdmin.post("/project-files/new-folder", canWrite, async (req, res) => {
+    try {
+      const scope = resolveScope();
+      const { dir, name } = req.body || {};
+      if (!name || /[\\/:*?"<>|]/.test(name)) return res.status(400).json({ error: "Invalid folder name" });
+      const abs = resolveInScope(scope, path.join(dir || ".", name));
+      if (!abs) return res.status(400).json({ error: OUT_OF_SCOPE });
+      await fsp.mkdir(abs, { recursive: true });
+      res.json({ ok: true, path: toRel(scope, abs) });
+    } catch (e) { logErr("new-folder", e); res.status(400).json({ error: safeErr(e) }); }
+  });
+
+  // ── Project dependency routes (Project Mode only) ─────────────────────────
+  // Python virtual environments live at <project>/.venv and Node dependencies at
+  // <project>/node_modules. Both are inherently project-scoped: they target the
+  // *active project* and are UNAVAILABLE in User Directory Mode (no project
+  // boundary to attach to — we never simulate one). Each route therefore
+  // requires Project Mode and always operates on the active project directory
+  // (scope.boundary), ignoring any client-claimed project name for safety.
+  const { spawn } = require("child_process");
+
+  // Guard helper: ensures Project Mode and returns the active project dir, or
+  // sends a clear 400 and returns null.
+  function requireProject(res, feature) {
+    const scope = resolveScope();
+    if (scope.mode !== "project") {
+      res.status(400).json({ error: `${feature} is only available in Project Mode (no active Node-RED project).` });
+      return null;
+    }
+    return scope; // scope.boundary is the active project directory
+  }
+
+  // Ensure the given entry is listed in <projAbs>/.gitignore. Recognises common
+  // equivalent forms (.venv, .venv/, /.venv, /.venv/) so we don't create duplicates.
+  // Non-fatal: any I/O error is swallowed — a missing .gitignore line should never
+  // block venv creation itself.
+  async function ensureGitignored(projAbs, entry) {
+    const giAbs  = path.join(projAbs, ".gitignore");
+    const target = entry.replace(/\/+$/, ""); // ".venv/" → ".venv"
+    const equiv  = new Set([target, target + "/", "/" + target, "/" + target + "/"]);
+    try {
+      let existing = "";
+      try { existing = await fsp.readFile(giAbs, "utf8"); } catch { /* missing: create below */ }
+      const hit = existing.split(/\r?\n/).some((line) => equiv.has(line.trim()));
+      if (hit) return;
+      const prefix = existing.length && !existing.endsWith("\n") ? "\n" : "";
+      await fsp.writeFile(giAbs, existing + prefix + entry + "\n");
+    } catch { /* non-fatal */ }
+  }
+
+  function runChild(cmd, args, opts, done) {
+    let stdout = "", stderr = "";
+    let child;
+    try { child = spawn(cmd, args, opts); }
+    catch (e) { return done(-1, "", String(e.message || e)); }
+    child.stdout.on("data", (d) => { if (stdout.length < 65536) stdout += d.toString(); });
+    child.stderr.on("data", (d) => { if (stderr.length < 65536) stderr += d.toString(); });
+    child.on("error", (err) => done(-1, stdout, stderr || String(err.message || err)));
+    child.on("close", (code) => done(code, stdout, stderr));
+  }
+
+  // Report whether <project>/.venv exists as a directory.
+  RED.httpAdmin.get("/project-files/python-env", canRead, async (req, res) => {
+    try {
+      const scope = requireProject(res, "Python environments");
+      if (!scope) return;
+      const projAbs = scope.boundary;
+      const venvAbs = path.join(projAbs, ".venv");
+      const st = await trystat(venvAbs);
+      res.json({ present: !!(st && st.isDirectory()), path: scope.project + "/.venv" });
+    } catch (e) { logErr("python-env", e); res.status(400).json({ error: safeErr(e) }); }
+  });
+
+  // Create <project>/.venv for the active project using the configured Python.
+  RED.httpAdmin.post("/project-files/python-env/create", canWrite, async (req, res) => {
+    try {
+      const scope = requireProject(res, "Python environments");
+      if (!scope) return;
+      const projAbs = scope.boundary;
+      const projSt = await trystat(projAbs);
+      if (!projSt || !projSt.isDirectory()) return res.status(400).json({ error: "Project folder not found" });
+      const venvAbs = path.join(projAbs, ".venv");
+      if (await trystat(venvAbs)) return res.status(409).json({ error: "Python environment already exists" });
+      runChild(PYTHON, ["-m", "venv", venvAbs], { cwd: projAbs }, async (code, _out, err) => {
+        if (code !== 0) return res.status(500).json({ error: "venv creation failed: " + (err || "exit " + code).slice(-1000) });
+        // Seed an empty requirements.txt so the "Install Python libraries" action
+        // has an obvious target. Never overwrite an existing file.
+        const reqAbs = path.join(projAbs, "requirements.txt");
+        if (!(await trystat(reqAbs))) {
+          try { await fsp.writeFile(reqAbs, ""); } catch (e) { /* non-fatal */ }
+        }
+        // Add .venv/ to the project's .gitignore so the environment never gets committed.
+        await ensureGitignored(projAbs, ".venv/");
+        res.json({ ok: true, path: scope.project + "/.venv" });
+      });
+    } catch (e) { logErr("python-env/create", e); res.status(400).json({ error: safeErr(e) }); }
+  });
+
+  // Install a requirements file into the active project's .venv.
+  RED.httpAdmin.post("/project-files/python-env/install", canWrite, async (req, res) => {
+    try {
+      const scope = requireProject(res, "Python environments");
+      if (!scope) return;
+      const projAbs = scope.boundary;
+      const pipAbs  = process.platform === "win32"
+        ? path.join(projAbs, ".venv", "Scripts", "pip.exe")
+        : path.join(projAbs, ".venv", "bin", "pip");
+      if (!(await trystat(pipAbs))) return res.status(400).json({ error: "Python environment not found. Create it first." });
+
+      const { requirements } = req.body || {};
+      const reqRel = requirements || (scope.project + "/requirements.txt");
+      const reqAbs = resolveInScope(scope, reqRel);
+      if (!reqAbs) return res.status(400).json({ error: OUT_OF_SCOPE });
+      const relFromProj = path.relative(projAbs, reqAbs);
+      if (relFromProj.startsWith("..") || path.isAbsolute(relFromProj)) {
+        return res.status(400).json({ error: "Requirements file must be inside the project" });
+      }
+      const reqSt = await trystat(reqAbs);
+      if (!reqSt || !reqSt.isFile()) return res.status(400).json({ error: "Requirements file not found" });
+
+      runChild(pipAbs, ["install", "-r", reqAbs], { cwd: projAbs }, (code, out, err) => {
+        if (code === 0) return res.json({ ok: true });
+        res.status(500).json({ error: "pip install failed: " + ((err || out || "exit " + code).slice(-1000)) });
+      });
+    } catch (e) { logErr("python-env/install", e); res.status(400).json({ error: safeErr(e) }); }
+  });
+
+  // ── Node packages route (Project Mode only) ───────────────────────────────
+  // Runs `npm install` with the active project as cwd. Packages land in
+  // <project>/node_modules — the Node-RED runtime's own node_modules is never
+  // touched.
+  RED.httpAdmin.post("/project-files/node-packages/install", canWrite, async (req, res) => {
+    try {
+      const scope = requireProject(res, "Node package installation");
+      if (!scope) return;
+      const projAbs = scope.boundary;
+      const pkgAbs  = path.join(projAbs, "package.json");
+      const pkgSt   = await trystat(pkgAbs);
+      if (!pkgSt || !pkgSt.isFile()) return res.status(400).json({ error: "package.json not found in project root" });
+      runChild(NPM, ["install"], { cwd: projAbs }, (code, out, err) => {
+        if (code === 0) return res.json({ ok: true });
+        res.status(500).json({ error: "npm install failed: " + ((err || out || "exit " + code).slice(-1000)) });
+      });
+    } catch (e) { logErr("node-packages/install", e); res.status(400).json({ error: safeErr(e) }); }
+  });
+
+  const startMode = resolveScope();
+  RED.log.info(`[project-files] ready — mode: ${startMode.mode}, scope: ${startMode.boundary}`);
+};