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

package/README.md

@@ -263,9 +263,10 @@ development), the editor has full access, exactly as Node-RED does itself.
 - **Text editor only.** Files are opened as UTF‑8 text; binary files are not
   editable in the editor (they can still be uploaded, moved, downloaded, and
   deleted).
-- **Symlinks.** The scope check is path-based. A symlink *inside* the scope root
-  that points outside it would be followed by the OS on read/write. Do not place
-  untrusted symlinks inside the scope root. (See *Deferred improvements*.)
+- **Symlinks.** The scope check is symlink-aware: a symlink *inside* the scope
+  root that resolves outside it is rejected on read, write and delete (the
+  deepest existing ancestor is canonicalised with `realpath` before the boundary
+  comparison). Symlinks that stay within the scope continue to work normally.
 - **Single boundary per mode.** The plugin manages one tree at a time (the
   active project, or the user directory); it is not a general, multi-root
   filesystem browser. Dependency/Python tools exist only in Project Mode.
@@ -279,6 +280,53 @@ development), the editor has full access, exactly as Node-RED does itself.
 
 ---
 
+## Testing
+
+The suite uses Node's built-in test runner (`node:test`) — **no extra
+dependencies, no global Node-RED, no network**. It needs Node 18+ (developed on
+Node 22). Every test runs against temporary directories and cleans up after
+itself; nothing is written outside the OS temp dir, and `npm`/`pip` are mocked
+(no real package installs).
+
+```bash
+npm test            # all layers
+npm run test:unit       # pure rules.js logic (no DOM, no Node-RED)
+npm run test:frontend   # mode banner / context menu / dirty-guard decisions
+npm run test:backend    # runtime/admin.js: filesystem boundary + modes + deps
+npm run test:smoke      # package consistency + load + end-to-end workflow
+npm run syntax          # quick `node --check` syntax pass
+```
+
+**Layers** (see [`tests/README.md`](./tests/README.md) for details):
+
+| Layer                | Location          | Covers |
+| -------------------- | ----------------- | ------ |
+| Unit (rules)         | `tests/unit`      | Protected/read-only/language/move rules — pure, deterministic. |
+| Frontend behavior    | `tests/frontend`  | Mode-banner visibility, context-menu state, unsaved-changes guard. |
+| Backend              | `tests/backend`   | Scope boundary, traversal/symlink/absolute rejection, Project vs. User mode, mocked dependency commands. |
+| Smoke / integration  | `tests/smoke`     | Package metadata ↔ files, plugin load, list→create→open→edit→save→restart. |
+
+**Required before publishing (release-blocking):** the backend filesystem
+**boundary** tests (`tests/backend/boundary.test.js`) and the **mode** tests
+(`tests/backend/mode.test.js`). These prove no route can read, write, or delete
+outside the active scope and that mode resolution is correct. Treat a failure
+here as a release blocker.
+
+**Mocked / isolated external behavior:**
+
+- `child_process.spawn` is replaced in `tests/backend/deps.test.js`; **no real
+  `python`, `pip`, or `npm` runs**. Tests assert command intent (binary, args)
+  and the working directory only.
+- The browser frontend (`plugin.js` DOM) is not instantiated; its critical
+  decision logic was extracted into `rules.js` and is tested there directly.
+
+**Intentionally deferred:** a full Node-RED boot (pack → install → start → load
+editor) is marked `skip` in `tests/smoke/plugin-load.test.js` and only runs with
+`SMOKE_FULL=1`. It needs a heavy dependency and network, so it is opt-in/manual
+for release validation rather than part of the default offline suite.
+
+---
+
 ## Upgrading
 
 Your data lives in your projects/user directory, **not** inside the package, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inteli.city/node-red-plugin-project-files",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Node-RED sidebar plugin to browse and edit project files, manage Python virtual environments, and install Node packages — scoped safely to your projects directory.",
   "keywords": [
     "node-red",
@@ -35,6 +35,11 @@
     "node": ">=16.0.0"
   },
   "scripts": {
-    "test": "node --check runtime/admin.js && node --check resources/project-files/plugin.js && echo \"syntax OK\""
+    "syntax": "node --check runtime/admin.js && node --check resources/project-files/plugin.js && echo \"syntax OK\"",
+    "test": "node --test tests/*/*.test.js",
+    "test:unit": "node --test tests/unit/*.test.js",
+    "test:frontend": "node --test tests/frontend/*.test.js",
+    "test:backend": "node --test tests/backend/*.test.js",
+    "test:smoke": "node --test tests/smoke/*.test.js"
   }
 }

package/resources/project-files/plugin.js

@@ -381,7 +381,7 @@ RED.plugins.registerPlugin("project-files", {
         if (!ctx) return false;
         // Grow to the wide target (never shrink if already wider). No state
         // stored — the new width IS the state.
-        this._applyWidth(ctx.container, Math.max(ctx.width, this._widths(ctx).wideW), ctx.side);
+        this._applyWidth(ctx.container, Math.max(ctx.width, this._widths(ctx).wideW));
         return true;
       },
 
@@ -390,41 +390,38 @@ RED.plugins.registerPlugin("project-files", {
         if (!ctx) return false;
         // Shrink to the narrow target (never widen one that's already narrower).
         // Works regardless of which plugin expanded it.
-        this._applyWidth(ctx.container, Math.min(ctx.width, this._widths(ctx).narrowW), ctx.side);
+        this._applyWidth(ctx.container, Math.min(ctx.width, this._widths(ctx).narrowW));
         return true;
       },
 
-      _separatorWidth: function () {
-        var sep = document.getElementById("red-ui-sidebar-separator");
-        return sep ? (sep.offsetWidth || 7) : 7;
-      },
-
-      // The ONLY function that writes host layout. Guarded; never throws out.
-      _applyWidth: function (container, width, side) {
+      // The ONLY function that writes host layout. To keep Node-RED's internal
+      // layout consistent (so the node-edit tray — which sizes itself from
+      // #red-ui-editor-stack's geometry — respects the new width), we reproduce
+      // the EXACT settled state Node-RED's own separator-drag produces.
+      _applyWidth: function (container, width) {
         try {
-          // Model-agnostic: size the sidebar container itself. Set width AND
-          // flex-basis so it works whether the sidebar is a block (pre-v5,
-          // absolutely positioned) or a flex child (Node-RED 5 panel layout).
-          container.style.width = width + "px";
-          container.style.flexBasis = width + "px";
-
-          // pre-v5 ONLY (capability-gated): the workspace + editor stack are
-          // absolutely positioned and offset from the sidebar's side; they do
-          // NOT reflow when the sidebar width changes, so the offset on the SAME
-          // side the sidebar occupies must follow it. Node-RED 5's flex layout
-          // reflows on its own, so we detect position:absolute and skip it
-          // there. Side-aware (left → left offset, right → right offset).
-          var sepW = this._separatorWidth();
-          ["red-ui-workspace", "red-ui-editor-stack"].forEach(function (id) {
-            var elm = document.getElementById(id);
-            if (!elm) return;
-            var cs = window.getComputedStyle ? window.getComputedStyle(elm) : null;
-            if (!cs || cs.position !== "absolute") return; // flex model → leave alone
-            if (side === "left") elm.style.left  = (width + sepW) + "px";
-            else                 elm.style.right = (width + sepW) + "px";
-          });
-
-          // Let Node-RED re-layout (tray.js handleWindowResize) if it listens.
+          var ws = document.getElementById("red-ui-workspace");
+          var es = document.getElementById("red-ui-editor-stack");
+          var absolute = !!(ws && window.getComputedStyle &&
+                            window.getComputedStyle(ws).position === "absolute");
+          if (absolute && typeof $ !== "undefined") {
+            // Node-RED's absolute layout model (v4.x): set the sidebar width and
+            // the workspace / editor-stack / separator offsets to the same final
+            // values NR's drag leaves behind. Constants (width + 7 / + 8 / + 2)
+            // are taken verbatim from NR's sidebar source, so the tray, canvas
+            // and separator all line up exactly as after a manual drag.
+            $(container).width(width);
+            ws.style.right = (width + 7) + "px";
+            es.style.right = (width + 8) + "px";
+            var sep = document.getElementById("red-ui-sidebar-separator");
+            if (sep) { sep.style.left = "auto"; sep.style.right = (width + 2) + "px"; }
+          } else {
+            // Flex layout (Node-RED 5): size the sidebar; the workspace and
+            // editor stack reflow themselves, so the tray geometry stays correct
+            // without any manual offsets.
+            container.style.width = width + "px";
+            container.style.flexBasis = width + "px";
+          }
           if (window.RED && RED.events && typeof RED.events.emit === "function") {
             RED.events.emit("sidebar:resize");
           }
@@ -682,7 +679,7 @@ RED.plugins.registerPlugin("project-files", {
     // savedText. The dirty flag is only for UI; never trust it alone for guards.
     function isDirty() {
       if (!currentFile) return false;
-      return getEditorContent() !== savedText;
+      return needsDirtyConfirm(currentFile, getEditorContent(), savedText);
     }
 
     function syncDirty() {
@@ -841,12 +838,13 @@ RED.plugins.registerPlugin("project-files", {
     // the fallback (User Directory) Mode, where behavior differs from the normal
     // project-based workflow.
     function updateModeBar() {
-      if (mode === "project") {
+      var banner = modeBanner(mode);
+      if (!banner.show) {
         $modeBar.hide();
         return;
       }
       $modeBar.addClass("dsff-mode-user").show();
-      $modeIcon.attr("class", "fa fa-exclamation-triangle");
+      $modeIcon.attr("class", banner.icon);
       $modeText.empty().append(
         $("<strong>").text("User Directory Mode"),
         document.createTextNode(
@@ -1132,24 +1130,20 @@ RED.plugins.registerPlugin("project-files", {
       hideCtxMenu();
       ctxTarget = item;
       $ctxLabel.text(item.name);
-      $ctxDownload.toggle(item.type === "file");
-      var prot = isProtected(item);
-      $ctxRename.toggleClass("dsff-ctx-disabled", prot)
-                .attr("title", prot ? "This item is protected and cannot be renamed or moved" : null);
-      $ctxDelete.toggleClass("dsff-ctx-disabled", prot)
-                .attr("title", prot ? "This file is protected and cannot be deleted" : null);
-
-      var isReqFile = item.type === "file" && item.name === "requirements.txt";
-      $ctxInstallPy.toggle(isReqFile);
-      if (isReqFile) {
-        $ctxInstallPy.toggleClass("dsff-ctx-disabled", !hasVenv)
-                     .attr("title", hasVenv ? null : "Create a Python environment first");
+      var st = ctxMenuState(item, { hasVenv: hasVenv, projectRoot: projectRoot });
+      $ctxDownload.toggle(st.showDownload);
+      $ctxRename.toggleClass("dsff-ctx-disabled", st.renameDisabled)
+                .attr("title", st.renameDisabled ? "This item is protected and cannot be renamed or moved" : null);
+      $ctxDelete.toggleClass("dsff-ctx-disabled", st.deleteDisabled)
+                .attr("title", st.deleteDisabled ? "This file is protected and cannot be deleted" : null);
+
+      $ctxInstallPy.toggle(st.showInstallPy);
+      if (st.showInstallPy) {
+        $ctxInstallPy.toggleClass("dsff-ctx-disabled", st.installPyDisabled)
+                     .attr("title", st.installPyDisabled ? "Create a Python environment first" : null);
       }
 
-      // Root-level package.json only. Nested package.json files are ignored.
-      var isRootPkg = item.type === "file" && item.name === "package.json" &&
-                      !!projectRoot && item.path === projectRoot + "/package.json";
-      $ctxInstallNode.toggle(isRootPkg);
+      $ctxInstallNode.toggle(st.showInstallNode);
 
       var x = ev.clientX, y = ev.clientY;
       $ctxMenu.css({ top: 0, left: 0 }).show();

package/resources/project-files/rules.js

@@ -44,4 +44,46 @@
   window.canMove = function (item) {
     return !window.isProtected(item);
   };
+
+  // ── UI decision logic (pure; rendered by plugin.js) ───────────────────────
+  // Operating-mode banner. Project Mode is the normal state and shows NO banner
+  // (the active project stays visible in the header). User Directory Mode shows
+  // a persistent warning bar. Returns what to render, not the DOM itself.
+  window.modeBanner = function (mode) {
+    if (mode === "project") return { show: false, kind: "project" };
+    return { show: true, kind: "user", icon: "fa fa-exclamation-triangle" };
+  };
+
+  // Project-only features (Python venv, Node package install) require an active
+  // project — they are unavailable in User Directory Mode.
+  window.projectFeaturesAvailable = function (mode) {
+    return mode === "project";
+  };
+
+  // Context-menu item state for a tree item, given the current venv/project
+  // context. ctx: { hasVenv: bool, projectRoot: string|null }. Mirrors the
+  // backend's protection rules so the menu never offers a forbidden action.
+  window.ctxMenuState = function (item, ctx) {
+    ctx = ctx || {};
+    var prot      = window.isProtected(item);
+    var isReqFile = item.type === "file" && item.name === "requirements.txt";
+    // Root-level package.json only; nested package.json files are ignored.
+    var isRootPkg = item.type === "file" && item.name === "package.json" &&
+                    !!ctx.projectRoot && item.path === ctx.projectRoot + "/package.json";
+    return {
+      showDownload:      item.type === "file",
+      renameDisabled:    prot,
+      deleteDisabled:    prot,
+      showInstallPy:     isReqFile,
+      installPyDisabled: isReqFile ? !ctx.hasVenv : false,
+      showInstallNode:   isRootPkg,
+    };
+  };
+
+  // Whether abandoning the current file needs an "unsaved changes" confirm.
+  // Authoritative check: live editor content vs. the last saved baseline.
+  window.needsDirtyConfirm = function (currentFile, content, savedText) {
+    if (!currentFile) return false;
+    return content !== savedText;
+  };
 })();

package/runtime/admin.js

@@ -2,6 +2,7 @@ module.exports = function (RED) {
   const path = require("path");
   const fs   = require("fs");
   const fsp  = require("fs").promises;
+  const { createScope, withinSafe, safeErr } = require("./scope");
 
   // ── Config ────────────────────────────────────────────────────────────────
   // The plugin runs in one of two explicit operating modes, decided per request
@@ -39,14 +40,22 @@ module.exports = function (RED) {
   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
+  // ── Operating-mode resolution + path safety ───────────────────────────────
+  // The filesystem boundary and scope resolution live in ./scope.js — the single
+  // auditable security core. We inject the live "active project" read here: it is
+  // evaluated FRESH per request so switching/creating/closing a project at
+  // runtime (no NR restart) takes effect immediately, and 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; }
-  }
+  const { resolveScope, resolveInScope, toRel } = createScope({
+    userDir:     USER_DIR,
+    projectsDir: PROJECTS_DIR,
+    getActiveProject() {
+      try { return (RED.settings.get("projects") || {}).activeProject || null; }
+      catch (e) { return null; }
+    },
+  });
+
+  // Whether Node-RED Projects is enabled (messaging only — never a boundary input).
   function projectsEnabled() {
     try {
       const et = RED.settings.editorTheme;
@@ -55,66 +64,6 @@ module.exports = function (RED) {
     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}`);
   }
@@ -293,7 +242,7 @@ module.exports = function (RED) {
       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 (!withinSafe(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);

package/runtime/scope.js

@@ -0,0 +1,110 @@
+// scope.js — Filesystem security boundary + operating-mode resolution.
+//
+// This is the security core of the plugin: every client-supplied path is
+// resolved and bounds-checked here before any fs access happens in admin.js.
+// It is deliberately self-contained and free of Node-RED dependencies — the one
+// live input (the active project name) is injected as a callback — so the whole
+// boundary can be read, audited, and unit-tested in one place, in isolation.
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+
+// Lexical containment — is `abs` the boundary itself, or strictly inside it?
+// `abs` must already be absolute and resolved. Rejects ../ 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);
+}
+
+// Symlink-safe containment. `within()` is purely lexical, so a symlink that
+// LEXICALLY sits inside the boundary but points outside it would be followed on
+// read/write and escape the sandbox. We canonicalise the deepest existing
+// ancestor of `abs` (symlinks resolved), re-append the not-yet-existing tail
+// (those segments can't be symlinks because they don't exist), and compare
+// against the real boundary. The tail handling lets create/save/rename target
+// paths that don't exist yet still be checked correctly.
+function realResolve(abs) {
+  let cur = path.normalize(abs);
+  const tail = [];
+  for (;;) {
+    try {
+      const real = fs.realpathSync(cur);
+      return tail.length ? path.join(real, ...tail.reverse()) : real;
+    } catch (e) {
+      const parent = path.dirname(cur);
+      if (parent === cur) return path.normalize(abs); // reached FS root; nothing resolved
+      tail.push(path.basename(cur));
+      cur = parent;
+    }
+  }
+}
+function realBoundary(boundary) {
+  try { return fs.realpathSync(boundary); } catch (e) { return path.normalize(boundary); }
+}
+function withinSafe(abs, boundary) {
+  return within(realResolve(abs), realBoundary(boundary));
+}
+
+// Map a thrown fs error to a generic, path-free message safe to return to the
+// client. Keeps absolute filesystem paths and internal structure out of HTTP
+// responses; the caller logs the real error server-side.
+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";
+  }
+}
+
+// Build the scope resolver for one plugin instance. Inputs are explicit:
+//   userDir          — absolute Node-RED user directory (User Directory Mode boundary)
+//   projectsDir      — absolute projects base (Project Mode anchor)
+//   getActiveProject — () => active project name | null, read FRESH per request so
+//                      switching/creating/closing a project at runtime takes effect
+//                      immediately. We never simulate a project when none is active.
+//
+// resolveScope() returns, 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 createScope({ userDir, projectsDir, getActiveProject }) {
+  function resolveScope() {
+    const active = getActiveProject();
+    if (active) {
+      return {
+        mode:     "project",
+        project:  active,
+        anchor:   projectsDir,
+        boundary: path.join(projectsDir, active),
+      };
+    }
+    return { mode: "user", project: null, anchor: userDir, boundary: userDir };
+  }
+
+  // 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
+  // (directly, via ../ traversal, or through a symlink that points outside).
+  function resolveInScope(scope, rel) {
+    const abs = path.resolve(scope.anchor, rel || ".");
+    return withinSafe(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, "/");
+  }
+
+  return { resolveScope, resolveInScope, toRel };
+}
+
+module.exports = { createScope, within, withinSafe, realResolve, safeErr };