Introduction

In the DSH “Everything is a Plugin” ecosystem, many extension capabilities are independently provided by community plugins. When the DSH Web GUI processes workspace files, it often needs to view directories directly within the interface, preview files, modify content, and check Git status before submitting.

folder-tree-sh is the workspace file tree plugin for the DSH Web GUI (dsh-ftree), providing file browsing, multi-format preview, inline editing, Git change panel, and complete file operations. It integrates into DSH Web via zero-core modification and hot-pluggable (profile bundle) methods.

What is this

The package name provided in the materials is folder-tree-sh, version 0.3.0 in package.json, and declares private: true. The license is MIT, and dsh.client.platform is web.

The repository address is:

https://github.com/Nothree-code/folder-tree-sh

Its positioning is the DSH Web GUI workspace file tree plugin: providing file tree, preview, edit, Git changes, and file operations capabilities on the web side.

Core Features

File Tree

The file tree sidebar supports:

  1. Directory expand / collapse.
  2. 5-second auto-refresh, manual refresh supported.
  3. Filter box: Real-time filtering by filename.
  4. Sort: Name / Size / Modified time, directories always on top.
  5. Hidden files toggle: Hides .git / node_modules / .DS_Store by default.
  6. Width drag-and-drop adjustment, panel toggle state persisted to localStorage.

Multi-tab Preview

The plugin supports multiple tabs to open multiple files simultaneously, with instant switching. Preview capabilities include:

  • Markdown: Render + Edit dual mode, supports toolbar, live preview, auto-save, Ctrl+S.
  • Workspace relative path images: e.g., ![](assets/a.png), rendered via host raw route.
  • Code: 30+ languages lightweight highlighting.
  • CSV: Automatic delimiter detection (, ; Tab), rendered as table.
  • Image: Supports zooming (Ctrl+Scroll), double-click to reset.
  • PDF: Browser native rendering, uses no-cache byte stream.
  • DOCX: Relies on mammoth to convert to HTML for true rendering, including images; without mammoth, automatically degrades to PowerShell extracting plain text.
  • Text: Chunked loading, 1MB/chunk, 100MB limit; GBK encoding auto-detection and fallback.

Markdown Inline Editing

Markdown files support inline editing:

  • Auto-save: 800ms debounce.
  • Manual save: Ctrl+S.
  • Scroll backup before save: .dshbak.1 to .dshbak.3.

Git Change Panel

The Git change panel provides:

  • Branch display.
  • Change list: Untracked / Staged / Modified.
  • Operations:
    • Stage: add
    • Unstage: restore --staged
    • Discard changes: checkout --; untracked files go to recycle bin.
    • View diff: diff / diff --cached

File Operations

The right-click menu supports the following file operations:

  1. Refresh.
  2. New file.
  3. New folder.
  4. Rename.
  5. Delete, goes to recycle bin, not permanently deleted.
  6. Copy / Cut / Paste.
  7. Copy in-place.
  8. Open source folder, i.e., locate in file explorer.
  9. Copy path.
  10. Add to chat, applicable to images.

Security Model

The plugin provides multiple boundary limits on the host side:

  1. Origin whitelist: Dynamically derived from webStartup, e.g., 127.0.0.1, localhost, [::1], configured host, trustedHosts. Cross-site requests always return 403. When listening on 0.0.0.0 (LAN), it degrades to relying solely on CSRF token.
  2. Per-process anti-CSRF token: All change routes (op / write / git-op) must carry a token issued by /dsh-ftree-token.
  3. Workspace whitelist: All paths must be within registered workspace roots, deny by default.
  4. Delete to recycle bin: Not permanently deleted.
  5. Scroll backup before write: .dshbak.1 to .dshbak.3.
  6. Shell injection protection: All PowerShell commands are escaped with single quotes, ' becomes ''.
  7. realpath path guard: All paths are normalized via realpath, following symlinks and NTFS junctions, then checked against workspace prefix. .. traversal, junction, and symlink escape are all impossible to bypass the whitelist; non-existent write targets automatically backtrack to the nearest existing ancestor (realpathLenient).
  8. Preview cache: Auto-invalidates based on file size verification, actively clears after write.

Installation and Enablement

Current materials do not provide official installation commands for end users. The README provides steps for development / local package installation scenarios.

First, sync modifications to node_modules entity copy:

powershell -ExecutionPolicy Bypass -File sync.ps1

If package.json has changes, e.g., name, version, dsh.client, execute local package installation / update:

cd ..\.. && pnpm add "file:./packages/dsh-ftree"

After the above steps, restart dsh web to take effect.

Typical Routes

The routes exposed on the host side are as follows:

  • GET /dsh-ftree-meta: Get version info.
  • GET /dsh-ftree-token: Get CSRF token.
  • GET /dsh-ftree-list: List directory, attaches modification time when withMtime=1.
  • GET /dsh-ftree-read: Chunked read file, supports text/image/pdf/docx.
  • POST /dsh-ftree-op: Execute rename / delete / paste / open / mkdir / newfile.
  • POST /dsh-ftree-write: Save text, with .dshbak backup.
  • GET /dsh-ftree-pdf: Get PDF byte stream.
  • GET /dsh-ftree-raw: Get workspace raw bytes, used for Markdown images and other scenarios.
  • GET /dsh-ftree-git: Get git status, including branch and changes.
  • POST /dsh-ftree-git-op: Execute stage / unstage / discard / diff.

Before calling change-related routes, you need to obtain the token issued by /dsh-ftree-token first.

Applicable Scenarios and Precautions

Suitable for these scenarios:

  1. Browse workspace directories in DSH Web GUI.
  2. Quickly preview Markdown, code, CSV, images, PDF, DOCX, text, and other files.
  3. Directly edit Markdown files and view backups before saving.
  4. View Git branch, change list before commit, and execute stage / unstage / discard / diff.
  5. Perform file operations like new, rename, delete, copy, move, etc.

Precautions before use:

  1. The plugin runs with the current dsh process permissions; source code and license should be checked before installation.
  2. Current materials do not provide official installation commands for end users; installation commands cannot be simply constructed from the repository name.
  3. The plugin’s path capabilities are restricted by the workspace whitelist; paths must be located within registered workspace roots.
  4. DOCX true rendering relies on mammoth; if missing, it degrades to PowerShell extracting plain text.

Links

  • Directory page: Current materials do not include a verifiable directory page address.
  • GitHub: https://github.com/Nothree-code/folder-tree-sh
  • License: MIT