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

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to this project are documented here. This project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [1.1.0] — 2026-06-09
+
+Introduced two explicit **operating modes** with distinct, documented filesystem
+boundaries and capabilities.
+
+### Added
+- **Project Mode** — active when a Node-RED project is selected. The active
+  project directory is now the authoritative security boundary.
+- **User Directory Mode** — active when Projects are disabled or no project is
+  selected. Scope is the Node-RED user directory (`<userDir>`).
+- A **fallback warning bar** shown **only** in User Directory Mode (Project Mode,
+  the default, shows no banner so it consumes no file-list space). It states that
+  Projects is disabled / no project is active, that the user directory is being
+  browsed, and that project-specific tools are unavailable. In Project Mode the
+  active project name is shown compactly in the header path (which ellipsizes
+  from the left so the project/current folder stays visible in a narrow sidebar).
+- Mode is reported by the `config` and `list` admin endpoints (`mode`,
+  `scopeDir`, `projectsEnabled`).
+
+### Changed
+- **Security hardening (Project Mode):** the backend boundary is now the *active
+  project* instead of the projects container, so sibling projects and anything
+  above the project can no longer be reached, even with crafted paths. The UI
+  already locked navigation to the project, so there is **no visible regression**.
+- Dependency/Python routes now always target the **authoritative active project**
+  (server-decided), ignoring any client-supplied project name, and return a clear
+  "Project Mode only" error in User Directory Mode.
+
+### Migration / behavior change
+- **Only** the *no-active-project* case changes: previously the plugin browsed
+  the projects container; it now enters User Directory Mode scoped to `<userDir>`
+  and hides the project-only dependency/Python features. **Project Mode
+  workflows are unchanged.** No data migration is required.
+
+## [1.0.0] — 2026-06-09
+
+First public release as an independent, npm-installable Node-RED plugin.
+
+### Added
+- Public `README.md`, `LICENSE` (MIT), and this changelog.
+- `projectFiles.pythonPath` setting to choose the Python interpreter.
+- Best-effort creation of the scope root (`baseDir`) at startup.
+
+### Changed
+- **Packaging:** removed `private` flag; added npm metadata (license, author,
+  repository, keywords, `files` allow-list) so the package can be published and
+  installed without copying files manually. All runtime/editor/resource assets
+  are included in the published tarball.
+- **Portability:** the Python interpreter (`python3`/`python`), the `pip`
+  executable path (POSIX `.venv/bin` and Windows `.venv/Scripts`), and the `npm`
+  command (`npm`/`npm.cmd`) are now resolved from `PATH`/platform instead of
+  being hard-coded — no hard-coded filesystem assumptions remain.
+- **Security:** error responses are now sanitized and never include absolute
+  filesystem paths; the underlying error is logged server-side only.
+
+### Notes
+- Behavior and UI are unchanged from the pre-publication version. There are no
+  migrations: your files live in `baseDir`, not in the package, and browser-side
+  preferences (word wrap, editor view-state) are preserved.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,300 @@
+# @inteli.city/node-red-plugin-project-files
+
+A Node-RED **sidebar plugin** that adds a *Project Files* tab to the editor for
+browsing and editing the files inside your projects directory — with a built‑in
+code editor (Monaco, with a textarea fallback), drag‑and‑drop upload, per‑project
+Python virtual environments, and project‑local Node package installation.
+
+All file and command operations are confined to a single, explicitly defined
+directory tree (the **scope root**). The plugin can never read, write, or execute
+anything outside that tree.
+
+---
+
+## Features
+
+- **File browser** in the Node-RED sidebar — navigate folders, sort by name or
+  modified time, show/hide dotfiles.
+- **In-editor code editing** with Monaco (syntax highlighting, word wrap) and an
+  automatic `<textarea>` fallback when Monaco is unavailable.
+- **File operations** — new file/folder, rename, move (drag a file onto a
+  folder), delete, download, copy path.
+- **Drag-and-drop upload** from your computer into the current folder.
+- **Protected files** — Node-RED's own `flows.json`, `flows_cred.json`,
+  `package.json`, their `.backup` siblings, and the `.git` directory are
+  read-only and cannot be renamed, moved, or deleted from the UI.
+- **Python virtual environments** — create a per-project `.venv` and install a
+  `requirements.txt` into it. `.venv/` is auto-added to the project's
+  `.gitignore`.
+- **Node packages** — run `npm install` against a project's root `package.json`,
+  installing into that project's own `node_modules`.
+
+The plugin is designed to complement Node-RED's
+[Projects feature](https://nodered.org/docs/user-guide/projects/) and runs in one
+of two explicit **operating modes** depending on your Node-RED environment (see
+[Operating modes](#operating-modes)).
+
+---
+
+## Requirements
+
+| Component          | Supported versions                                     |
+| ------------------ | ------------------------------------------------------ |
+| **Node-RED**       | `>= 3.0.0`                                              |
+| **Node.js**        | `>= 16.0.0`                                             |
+| **Python** *(opt)* | Python 3 on `PATH` (only for the virtual-env features) |
+| **npm** *(opt)*    | `npm` on `PATH` (only for Node package install)         |
+
+Python and npm are **optional** — the file-browser/editor works without them. The
+relevant context-menu actions simply report a clear error if the tool is missing.
+
+---
+
+## Installation
+
+Install into an existing Node-RED instance like any other node module.
+
+**Using the Node-RED editor** *(recommended)*
+Menu → **Manage palette** → **Install** → search for `@inteli.city/node-red-plugin-project-files`.
+
+**Using npm** — from your Node-RED user directory (the one that contains
+`settings.js`, usually `~/.node-red`):
+
+```bash
+cd ~/.node-red
+npm install @inteli.city/node-red-plugin-project-files
+```
+
+Then restart Node-RED. The *Project Files* tab appears in the sidebar
+automatically — there is no manual registration step. The plugin re-loads and
+behaves identically across restarts.
+
+> The package ships all of its own assets (runtime, editor HTML, and frontend
+> resources). Nothing needs to be copied manually, and it does not rely on any
+> repository-relative paths.
+
+---
+
+## Configuration
+
+All configuration is optional. Add a `projectFiles` block to your Node-RED
+`settings.js`:
+
+```js
+module.exports = {
+  // ...existing settings...
+
+  projectFiles: {
+    // Where Node-RED stores projects — used as the Project Mode anchor.
+    // Default: <userDir>/projects  (the Node-RED Projects directory).
+    // (User Directory Mode always uses <userDir> and is not affected by this.)
+    baseDir: "/home/user/.node-red/projects",
+
+    // Maximum size (bytes) for files opened in the editor or saved/uploaded.
+    // Default: 50 MiB.
+    maxBytes: 50 * 1024 * 1024,
+
+    // Python interpreter used to create virtual environments.
+    // Default: "python3" (or "python" on Windows). Resolved from PATH.
+    pythonPath: "python3",
+  },
+};
+```
+
+| Setting      | Default                              | Purpose                                            |
+| ------------ | ------------------------------------ | -------------------------------------------------- |
+| `baseDir`    | `<userDir>/projects`                 | Where projects live (Project Mode anchor).         |
+| `maxBytes`   | `52428800` (50 MiB)                  | Max size for open/save/upload.                     |
+| `pythonPath` | `python3` (`python` on Windows)      | Interpreter for `python -m venv`.                  |
+
+If `baseDir` does not exist at startup, the plugin attempts to create it
+(non-fatally).
+
+---
+
+## Operating modes
+
+The plugin runs in one of **two explicit modes**, chosen automatically from the
+live Node-RED environment and re-evaluated on every request (so switching,
+creating, or closing a project takes effect immediately — no restart).
+
+**Project Mode is the primary, default experience and is shown without any
+banner** — a persistent "everything's fine" strip would only waste the limited
+vertical space in the file panel. Instead, the active project name appears
+compactly in the header path (e.g. `…/projects/acme`). A **warning bar appears
+only in the fallback** (User Directory) Mode, where behavior differs from the
+normal project-based workflow. In other words: no news is good news; you only see
+a banner when something is *not* the normal project setup.
+
+| | **Project Mode** | **User Directory Mode** |
+| --- | --- | --- |
+| **When** | Node-RED Projects enabled **and** a project is active | Projects disabled, **or** no project is active |
+| **Filesystem boundary** | the active project directory `<projectsDir>/<project>` | the Node-RED user directory `<userDir>` |
+| **Sidebar indicator** | *no banner* — the normal state; the active project name shows compactly in the header path (e.g. `…/projects/acme`) | amber **warning bar**: *“User Directory Mode — …”* |
+| Browse / open / edit / save | ✅ | ✅ |
+| New / rename / move / delete / upload / download | ✅ | ✅ |
+| Protected files (`flows.json`, `flows_cred.json`, `package.json`, `.git`, backups) | ✅ enforced | ✅ enforced |
+| **Python virtual environment** | ✅ create & install into `<project>/.venv` | ❌ unavailable (stated in the UI) |
+| **Node package install** (`npm install`) | ✅ into `<project>/node_modules` | ❌ unavailable (stated in the UI) |
+
+Project Mode is the **primary, fully-featured** experience. User Directory Mode
+is a deliberately reduced model — it never pretends a project exists.
+
+### Project Mode
+
+Active when Node-RED Projects are enabled and a project is selected. This is the
+**default, fully-featured state and shows no banner**; the active project name is
+visible compactly in the header path. The **active project is the authoritative
+boundary**: you cannot browse, edit, or operate on sibling projects or anything
+above the project, even by crafting paths. All existing project workflows —
+including the Python and Node dependency tools — work exactly as before, at the
+same layout density.
+
+> Example: with active project `acme`, the scope is
+> `~/.node-red/projects/acme`. Creating a Python env makes
+> `~/.node-red/projects/acme/.venv`; *Install Node libraries* runs `npm install`
+> in `~/.node-red/projects/acme`.
+
+### User Directory Mode
+
+Active when Projects are **disabled**, or enabled but **no project is selected**.
+The scope is the **Node-RED user directory** (`<userDir>`, e.g. `~/.node-red`).
+A noticeable (but non-disruptive) **amber warning bar appears at the top of the
+file panel — only in this mode** — making it explicit that you are *not* inside a
+project. It states that Projects is disabled / no project is active, that the
+plugin is now browsing the Node-RED user directory, and that some
+project-specific features are unavailable. The plugin never falls back to this
+mode silently.
+
+- **File browsing and editing are fully available** within `<userDir>`.
+- **Dependency management and Python environments are unavailable.** They are
+  inherently project-scoped (a `.venv`/`node_modules` needs a project home that
+  is git-ignored and deployable). Rather than guess a location or simulate a
+  project, the plugin disables them and says so in the UI. To use them, enable
+  Node-RED Projects and open a project.
+- **Heads-up:** `<userDir>` contains Node-RED's own configuration
+  (`settings.js`, `.config.*.json`, `flows.json`, …). `flows.json`,
+  `flows_cred.json`, `package.json`, and `.git` are protected from
+  rename/move/delete and the flow files open read-only, but other config files
+  are browsable and editable. If that is not desirable for your deployment,
+  enable Projects (to get Project Mode) or restrict editor access via
+  `adminAuth`.
+
+> Example: with no active project and a default install, the scope is
+> `~/.node-red`. You can edit `~/.node-red/settings.js` or browse
+> `~/.node-red/projects/`, but the *Create Python environment* / *Install*
+> actions do not appear.
+
+---
+
+## Scope model & security
+
+Each mode has **exactly one** authoritative filesystem boundary (see the table
+above). The rules below are enforced **identically across every operation** —
+browse, edit, upload, download, rename, move, delete, dependency install, and
+Python-environment operations:
+
+- **Every** operation resolves its target against the active boundary and is
+  rejected if it falls outside it. There is no operation that uses a different
+  or wider boundary.
+- **Path traversal is prevented.** Inputs are normalized and `../` sequences
+  cannot escape the boundary; sibling directories that merely share a name
+  prefix (e.g. `acme` vs `acme-evil`) are also rejected. In Project Mode this
+  includes other projects.
+- **External commands run inside the boundary.** `python -m venv`,
+  `pip install`, and `npm install` only run in Project Mode, always with their
+  working directory set to the **active project**, writing only to
+  `<project>/.venv` and `<project>/node_modules`. A client cannot redirect them
+  to another project — the server uses the authoritative active project, not any
+  client-supplied name.
+- **Protected files are immutable from the UI.** `flows.json`,
+  `flows_cred.json`, `package.json`, their `.backup` siblings, and `.git` cannot
+  be renamed, moved, or deleted; `flows*.json` and their backups are opened
+  read-only.
+- **Errors are sanitized.** HTTP responses never include absolute filesystem
+  paths; the underlying error is logged server-side only. (Output from
+  `pip`/`npm` is still surfaced to you, since you need it to diagnose dependency
+  problems, and it is confined to your own project.)
+- **Fails safe.** Invalid, missing, or out-of-scope paths return a clear error
+  rather than performing a partial or unsafe operation.
+
+### Authentication & authorization
+
+All backend endpoints are registered on Node-RED's admin API and respect your
+Node-RED security settings. When `adminAuth` is enabled, requests must be
+authenticated, and the plugin enforces two permissions:
+
+| Action                                              | Required permission     |
+| --------------------------------------------------- | ----------------------- |
+| Browse, open, stat, download                        | `projectFiles.read`    |
+| Create, save, rename, move, delete, upload, install | `projectFiles.write`   |
+
+These are satisfied by Node-RED's standard `read`/`write` permission scopes, so
+a user with `*` or `write` permission has full access and a `read`-only user has
+view-only access. With `adminAuth` **disabled** (the default for local
+development), the editor has full access, exactly as Node-RED does itself.
+
+> **Operational note:** users who can write files and trigger `pip`/`npm`
+> install effectively can cause code to be written into your projects directory.
+> Grant `projectFiles.write` only to trusted editor users, the same way you
+> would protect deploy/admin access in Node-RED.
+
+---
+
+## Usage
+
+1. Open the Node-RED editor and select the **Project Files** tab in the sidebar.
+2. Browse the tree on the left; click a file to open it in the editor on the
+   right. `Ctrl/Cmd+S` saves.
+3. Right-click a file or folder for **rename / move / delete / download / copy
+   path** and the install actions.
+4. Drag files from your computer onto the tree to **upload** them into the
+   current folder. Drag a row onto a folder to **move** it.
+5. **Python:** with a project active, use the **Python environment** bar to
+   *Create* a `.venv`, then right-click a `requirements.txt` → *Install Python
+   libraries*.
+6. **Node:** right-click a project's root `package.json` → *Install Node
+   libraries* to run `npm install` for that project.
+
+---
+
+## Limitations & known caveats
+
+- **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*.)
+- **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.
+- **Windows venv/Node.** Paths for `pip` are handled for both POSIX
+  (`.venv/bin`) and Windows (`.venv/Scripts`), but the venv/Node features are
+  primarily exercised on Linux.
+- **Concurrent edits.** If a file changes on disk while open, the editor shows a
+  *"changed on disk"* status; saving overwrites with the editor's content (last
+  write wins). No automatic merge is performed.
+- **Default sidebar tab.** On first load the plugin focuses its own sidebar tab.
+
+---
+
+## Upgrading
+
+Your data lives in your projects/user directory, **not** inside the package, so
+upgrading (`npm update @inteli.city/node-red-plugin-project-files`) never touches your files.
+Word-wrap and editor view-state preferences are stored in the browser's
+`localStorage` and are likewise preserved.
+
+**Upgrading to 1.1 (operating modes).** Project Mode behaves exactly as before —
+no migration, no regression. The only behavior change is for the case where **no
+project is active**: previously the plugin browsed the projects *container*;
+it now enters **User Directory Mode** scoped to `<userDir>` and disables the
+project-only dependency/Python tools (clearly indicated in the UI). Project-Mode
+users are unaffected. See [CHANGELOG.md](./CHANGELOG.md) for details.
+
+---
+
+## License
+
+[MIT](./LICENSE)

package/editor/project-files.html

@@ -0,0 +1,7 @@
+<!-- Project Files sidebar plugin — loads frontend modules in dependency order -->
+<script src="resources/@inteli.city/node-red-plugin-project-files/project-files/style.js"></script>
+<script src="resources/@inteli.city/node-red-plugin-project-files/project-files/prefs.js"></script>
+<script src="resources/@inteli.city/node-red-plugin-project-files/project-files/admin-ajax.js"></script>
+<script src="resources/@inteli.city/node-red-plugin-project-files/project-files/rules.js"></script>
+<script src="resources/@inteli.city/node-red-plugin-project-files/project-files/dialogs.js"></script>
+<script src="resources/@inteli.city/node-red-plugin-project-files/project-files/plugin.js"></script>

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@inteli.city/node-red-plugin-project-files",
+  "version": "1.0.0",
+  "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",
+    "node-red-plugin",
+    "sidebar",
+    "files",
+    "file-browser",
+    "editor",
+    "monaco",
+    "projects"
+  ],
+  "license": "Apache-2.0",
+  "main": "runtime/admin.js",
+  "files": [
+    "runtime/",
+    "editor/",
+    "resources/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "node-red": {
+    "version": ">=3.0.0",
+    "plugins": {
+      "project-files": "editor/project-files.html"
+    },
+    "nodes": {
+      "project-files-admin": "runtime/admin.js"
+    }
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "scripts": {
+    "test": "node --check runtime/admin.js && node --check resources/project-files/plugin.js && echo \"syntax OK\""
+  }
+}

package/resources/project-files/admin-ajax.js

@@ -0,0 +1,12 @@
+// Thin wrapper around $.ajax that adds the Node-RED auth headers required by
+// all httpAdmin endpoints when adminAuth is enabled.
+function dsffAjax(method, url, data) {
+  return $.ajax({
+    method,
+    url,
+    data:        data ? JSON.stringify(data) : undefined,
+    contentType: data ? "application/json"  : undefined,
+    headers:     { "Node-RED-API-Version": "v2" },
+    xhrFields:   { withCredentials: true },
+  });
+}