dsh-sidebar-files

Readme

# dsh-sidebar-files

English | [中文](README.zh.md)

[![npm version](https://img.shields.io/npm/v/dsh-sidebar-files.svg)](https://www.npmjs.com/package/dsh-sidebar-files)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

A sidebar file tree for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness). Adds a **Sessions / Files** tab strip to the left sidebar and an inline, lazy-loaded file tree over the active workspace — with per-extension brand icons, copy-path, and send-to-agent actions.

![Files tab in the sidebar](docs/screenshot-v2.png)

Hover a file row for two actions — **copy path** and **send to agent**:

<table>
<tr>
<td align="center"><img src="docs/feature-copy-path.png" width="320" alt="Copy path"><br><sub>Copy path</sub></td>
<td align="center"><img src="docs/feature-send-to-agent.png" width="320" alt="Send to agent"><br><sub>Send to agent</sub></td>
</tr>
</table>

> **Plugin status.** Built and verified against the published harness (`0.1.0-rc.6`, the `web` profile). It runs entirely as an out-of-tree bundle: the node half serves directory listings through its own HTTP route, the browser half renders the tree. No core changes required.

## Features

- **Sessions / Files tab strip** injected below the New Session button (wide sidebar). The tree renders inline in the sidebar region — same presentation as the harness's own browsing surfaces.
- **Lazy listing**: one directory level is fetched on demand (the workspace root on open, a directory on first expand), through the plugin's own `GET /dsh-sidebar-files/list?path=…` route. Wire cost follows what you actually open.
- **Per-extension icons**: 47 brand-style glyphs for common extensions (ts/js/json/yml/yaml/css/html/md/ico/png/zip/log/…), plus a generic document fallback. Icon path data from [Material Icon Theme](https://github.com/PKief/vscode-material-icon-theme) (MIT, © Material Extensions 2025) — see [LICENSE](LICENSE).
- **Hidden by default**: dot-led names, `node_modules`, and `.git` are filtered out; the **显示隐藏项** toggle reveals them. `node_modules`/`.git` stay hidden until the toggle is on.
- **Row actions** (hover): copy path (with one-second "copied" feedback) and send the file to the current session's agent (a queued "please read this file" prompt).
- **Resilient fallback**: if the shell's sidebar structure is ever unrecognizable, the plugin degrades to a footer action button + centered modal instead of the tab strip — never a blank screen.
- **Bilingual** (中文 / English), following the harness locale.

## Install

Requires the `dsh` CLI (`npm i -g @deepseek-ai/dsh`) and pnpm.

**What is a profile?** A *profile* is one runnable composition of the harness — a named instance with its own set of plugins. Profiles live under `$DSH_HOME/profiles/<name>` (e.g. `~/.dsh/profiles/web`). `--profile <name>` tells the `dsh` CLI which instance to operate on; replace `<name>` with your own (the classic example is `web`).

```sh
# from any directory — installs the published package from npm
dsh plugin --profile web add dsh-sidebar-files
```

If a profile with that name does not exist yet, the command initializes it on first use. Restart the harness with the same profile name and the **会话 / 文件** tabs appear in the sidebar:

```sh
dsh --profile web
```

> If the profile is a fresh one, also add the web app bundle first: `dsh plugin --profile web add @deepseek-ai/dsh-web-app@0.1.0-rc.6` (or use the built-in `web` profile template that ships with the CLI).

### Alternative installs

Local checkout or prebuilt tarball (no registry needed):

```sh
dsh plugin --profile web add ./dsh-sidebar-files           # local checkout (uses prepare)
dsh plugin --profile web add ./dsh-sidebar-files-0.1.0.tgz # prebuilt tarball
```

From GitHub (`github:Fallen0543/dsh-sidebar-files`) — fetches **sources**; the package's `prepare` script then builds `lib/` from source, self-contained (no monorepo checkout needed). pnpm ≥10 refuses to run a git dependency's `prepare` script until you allowlist it — copy the exact package key pnpm printed into the profile's `pnpm-workspace.yaml`:

```yaml
allowBuilds:
  dsh-sidebar-files: true
```

and re-run the `add`. Only allow packages whose source you trust, and prefer pinning a commit (`github:Fallen0543/dsh-sidebar-files#<sha>`). Installing from npm or a tarball needs no build permission.

## Development

```sh
pnpm install
pnpm test        # unit tests: listing logic, sidebar-host probing/injection, panel behavior
pnpm run typecheck
pnpm run build   # lib/index.js (node) + lib/client.js (browser bundle)
```

The browser bundle is a CommonJS closure-factory artifact (`window.__ModuleLoader__.load({…})`) with the harness's platform modules external, so it loads through the web shell's module table; CSS modules are compiled in with lightningcss.

## How it works

- `cordis.patch.yml` inserts one host row (`id: sidebar-files`) that mounts the node half.
- The node half (`src/index.ts`) registers a web-server route prefix `/dsh-sidebar-files`; `GET /list?path=` lists one directory level (directories first, then files; bounded to the first 1000 entries) and returns `{ path, entries, truncated }` — errors are 400 with a machine-readable code.
- The browser half (`dsh.client` declaration, `./client` export) registers into the harness's `sidebar.footer.action` slot, then locates the sidebar column at runtime from its own trigger button and injects the Sessions/Files tab strip and the inline tree region (see `src/client/sidebar-host.ts`). When the shell structure is unrecognizable, the footer button + modal fallback takes over.
- The active workspace path is derived from the session/workspace stores (current session's workspace, else recent, else first) through selector hooks, exactly like the harness's own browsing surfaces.

## License

MIT — see [LICENSE](LICENSE). File-type icon glyphs are derived from [Material Icon Theme](https://github.com/PKief/vscode-material-icon-theme) (MIT, © Material Extensions 2025); the attribution and copyright notice are preserved in `src/client/file-type-icons.tsx`.