dsh-explorer 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 wwwroot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# dsh-explorer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Native workspace file explorer plugin engineered specifically for DeepSeek Harness (DSH). Bridges local workspace navigation and AI-assisted conversation workflows with seamless chat referencing, fluid animations, and editor tab integration.
+
+<p align="center">
+  <img src="./assets/preview.png" alt="dsh-explorer preview" width="850" />
+</p>
+
+---
+
+## Key Features
+
+### 1. Conversational Chat Integration
+* **Precision Drag & Drop**: Drop files or folders into the DSH chat composer with exact text cursor / insertion point positioning, preserving existing words without clobbering text.
+* **Smart Mention Chips**: Files dropped or inserted appear as `@path/to/file` chips, and directories appear with trailing slash `@path/to/folder/`.
+* **Modifier Drop Snippets**: Hold **Alt** or **Shift** while dropping a file to embed its full source code directly into the chat prompt as a syntax-highlighted markdown code block.
+* **One-Click Mentioning**: Click the `@` hover icon on any row or select *Insert Mention to Chat* from the context menu to insert the reference at your active cursor.
+
+### 2. Tab Navigation & Workspace Viewing
+* **Double-Click to Open**: Double-click any file to launch it directly into a new DSH editor tab (seamlessly integrating with `betterSidebar`, `sidebarRight`, or native workspace tabs).
+* **Context Menu "Open in New Tab"**: Right-click any file to open it in an editor tab.
+* **Instant Filter Search**: Top search bar filters files and folders in real time with instant path matching.
+
+### 3. Motion Collapse Transitions
+* **Fluid Grid Animations**: Smooth CSS grid accordion animations when expanding and collapsing folders.
+* **Rotating Chevrons**: Responsive chevron rotation synchronized with folder open/close state.
+* **Toggleable in Preferences**: Easily disable animations in the Options modal for instantaneous snap navigation.
+
+### 4. Git Status Indicators
+* **Multi-Repo & Monorepo Support**: Automatic detection of git repositories at workspace root or nested sub-repositories across tools and project folders.
+* **Parent Folder Bubble-Up**: Ancestor directories reflect modified (`M`), untracked (`U`), or deleted (`D`) states of their children, so changes are visible without needing to expand every folder.
+* **Refined Pill Badges**: Right-aligned status badges with subtle tint backgrounds (`M` in warm amber, `U` in soft green, `D` in coral red).
+* **Toggleable in Preferences**: Cleanly hide all Git colors and badges with one switch in the Options modal.
+
+### 5. Compact Folders
+* **Single-Child Folder Chaining**: Single-child directory hierarchies (such as `src/client/ui`) are collapsed into a single compact line.
+* **Instant Responsive Toggle**: Turn Compact Folders on or off in the Options modal with immediate, zero-lag visual re-rendering.
+
+### 6. Scale & Density Customization
+* **Density Presets**: Switch between **Compact** (20px rows), **Normal** (24px rows), and **Relaxed** (28px rows).
+* **Continuous Zoom Slider**: Zoom the entire tree from **75%** to **135%** scale, automatically adjusting row heights, font sizes, icon sizes, and indentation step guides.
+* **Persistent Preferences**: All display options are saved to local storage and restored automatically.
+
+### 7. Language Icons & Visual Hierarchy
+* **Color-Coded File Types**: Hand-tuned colors and badges for TypeScript, JavaScript, Python, Rust, Go, C/C++, HTML, CSS, JSON, Markdown, YAML, Docker, Git, and shell scripts.
+* **Directory Guides**: Visual indent guide lines showing nesting levels clearly across deep workspace structures.
+* **Hidden Files Toggle**: Toggle visibility of dotfiles and hidden system configurations.
+
+### 8. Complete File Management
+* **Inline Operations**: Hover actions for Mention (@), Copy Relative Path, Rename (F2), and Delete.
+* **Keyboard Navigation**: Full keyboard navigation support (Up / Down arrows, Left / Right collapse / expand, Enter to mention or expand, F2 to rename).
+* **Live File System Watcher**: Instantaneous tree updates via WebSocket server when files are created, modified, or deleted externally.
+
+---
+
+## Installation
+
+### Via DSH Plugin CLI (NPM)
+```sh
+dsh plugin --profile web add dsh-explorer
+```
+*(or use `--profile desktop` for desktop harness)*
+
+### Via Source (GitHub)
+```sh
+dsh plugin --profile web add github:wwwroot/dsh-explorer
+```
+
+### Via cordis.patch.yml
+Add `dsh-explorer` to your profile configuration:
+
+```yaml
+- insert:
+    - id: dsh-explorer
+      name: 'dsh-explorer'
+```
+
+---
+
+## Development & Building
+
+Building the standalone client bundle and host ESM service:
+
+```sh
+# Install dev dependencies
+npm install
+
+# Build host ESM (lib/index.js) and client bundle (lib/client.js)
+npm run build
+
+# TypeScript validation
+npm run typecheck
+```
+
+---
+
+## Architecture
+
+* **Host Service (`src/index.ts`, `src/fs-tree.ts`, `src/git-status.ts`)**: Node.js ESM service running on the DSH Cordis container, providing secure filesystem tree traversal, WebSocket live file-watching, and parallel git status aggregation.
+* **Client Surface (`src/client/index.tsx`, `src/client/ExplorerView.tsx`)**: React UI mounted inside DSH's right sidebar slot (`sidebar.right.panel`), managing reactive tree navigation, drag-and-drop caret tracking, and customizable display preferences.
+* **Self-Contained Distribution**: Build outputs in `lib/` are fully bundled by `esbuild` with inlined CSS modules, requiring zero external client dependencies at runtime.
+
+---
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-explorer bundle patch
+- insert:
+    - id: dsh-explorer
+      name: 'dsh-explorer'
+

package/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" fill="none">
+  <path d="M4 4C4 2.89543 4.89543 2 6 2H14L19 7V17C19 18.1046 18.1046 19 17 19H6C4.89543 19 4 18.1046 4 17V4Z" fill="#29B6F6" fill-opacity="0.2" stroke="#0288D1" stroke-width="1.6" stroke-linejoin="round"/>
+  <path d="M13.5 2V7.5H19" stroke="#0288D1" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M8 7H11M8 11H15M8 15H13" stroke="#0288D1" stroke-width="1.6" stroke-linecap="round"/>
+  <path d="M8 22H18C19.6569 22 21 20.6569 21 19V8" stroke="#0288D1" stroke-width="1.6" stroke-linecap="round" opacity="0.6"/>
+</svg>
+