@chronosun/dsh-wsl 0.0.0-stage → 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yunson
+
+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,234 @@
-# Temporary Holding Version
+# @chronosun/dsh-wsl
 
-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.
+Run a DeepSeek Harness session inside a local WSL distribution: `bash`,
+background jobs, the sidebar terminal, `read`/`write`/`edit`, `grep` and `glob`
+all operate on the Linux filesystem — not on a `\\wsl.localhost` share.
+
+## What it gives you
+
+- **A WSL workspace picker.** The sidebar gains a `WSL` panel: pick a
+  distribution, browse its directories, and adopt one as a workspace. The
+  workspace is registered through the official API, so history, diffs and the
+  session list keep working; its title is prefixed with `🐧`.
+- **WSL by default inside a WSL workspace.** Opening a `🐧` workspace or
+  pressing **New Session** there creates the session under the `WSL` preset
+  without asking. The Host rewrites the preset only when the Client names none,
+  and only for `\\wsl.localhost\...` / `\\wsl$\...` paths, so Windows
+  workspaces and explicit preset choices keep their behavior. An existing
+  session keeps the preset recorded when it was created; resuming it never
+  switches modes. This works for existing workspaces too — no re-creation is
+  needed.
+- **A `WSL` agent preset.** Sessions created in that workspace run their tools
+  in Linux. A broker keeps one persistent connection per (distribution, user)
+  and disconnects it after **5 idle days** by default (configurable in the
+  panel, `0` = never).
+- **A clean environment.** `wsl.exe` normally hands Linux a PATH polluted with
+  `/mnt/c`, `/mnt/d` entries, so `node`, `npm`, `git` and `rg` can silently
+  resolve to Windows binaries. Every command here runs with the distribution's
+  **login PATH minus every `/mnt/*` entry**, so the user's own toolchain
+  (`~/.local/bin`, cargo, nvm, `/usr/local/bin`, …) stays reachable and an
+  interop binary is never used.
+- **WSL-native `@` discovery.** For a WSL-preset Agent, `@file` candidates are
+  indexed inside the distribution (bounded tree, `.gitignore`-aware) and
+  returned relative to the Linux cwd, not scanned through the UNC share. The
+  Host provider remains for every other preset.
+- **Linux diff summaries and comparisons.** For a WSL-preset Session the plugin
+  snapshots the work tree inside the distribution at turn start/end (private
+  `GIT_INDEX_FILE`, `write-tree`/`diff-tree`) and serves the changed-files card
+  from Linux git. The Host recorder remains the event source and fallback; the
+  card's open action still uses the Host's UNC coordinates. Absolute UNC display
+  paths are translated to Linux; relative paths are already neutral.
+- **Linux-native worktree creation.** `create_wsl_worktree` creates a retained
+  Git worktree with Linux git and returns its path, branch and base commit.
+  The Session working directory is unchanged, so pass the returned path (or
+  `workdir`) to later tools; the shipped Host `create_worktree` tool is not
+  mounted in the WSL preset.
+
+## Why this instead of opening the UNC path
+
+Opening `\\wsl.localhost\...` as a Workspace only changes the folder: on Windows
+the standard preset still runs `pwsh`, reads and writes through the 9P share,
+and spawns the Windows `rg`. This bundle changes the **execution world**:
+
+| | UNC workspace | WSL preset |
+|---|---|---|
+| shell | Windows `pwsh` | Linux `bash`, clean login PATH |
+| file I/O | 9P share | persistent broker → ext4 |
+| search | Windows ripgrep over 9P | Linux walk / `git ls-files` |
+| model cwd | UNC (`\\wsl.localhost\...`) | `/home/...` |
+| toolchain | Windows node/npm/git | the distribution's own |
+
+Measured on a local machine (1000 `stat`, 20 `readdir`): 9P 1.31 ms vs broker
+0.29 ms per stat (4.5×), 4.48 ms vs 0.49 ms per readdir (9.1×). A cold
+`wsl.exe` is about 120 ms, which is why file and search work go through the
+persistent broker while `bash` keeps DSH's one-shot contract (`workdir`, not a
+persistent `cd`).
+
+It is deliberately not a host-preset rewrite and not a `wsl_*` tool set: the
+world is declared as its own preset, so the model never chooses between Windows
+and Linux tools, and upgrades do not depend on the text of a shipped preset.
+
+## Install
+
+Published package:
+
+```powershell
+dsh plugin --profile desktop add @chronosun/dsh-wsl
+```
+
+From a source checkout:
+
+```powershell
+npm pack --pack-destination dist
+dsh plugin --profile desktop add dist\chronosun-dsh-wsl-<version>.tgz
+```
+
+Then **quit DSH from the tray and reopen it** — client plugins and preset rows
+load at boot; a page refresh is not enough.
+
+Requires: Windows, WSL 2, and a Linux `node` (v18+) inside the distribution,
+used only to run a small helper. Nothing is installed into the distribution.
+
+## Use
+
+1. Sidebar → `WSL` → `＋ 添加 WSL 工作区`.
+2. Choose a distribution, browse to a directory, press `使用此目录`.
+3. The workspace opens with the `WSL` preset; every later **New Session**
+   inside that workspace also defaults to `WSL`. In a WSL session the Agent's
+   `Current working directory` is the Linux path (the Host still keeps the UNC
+   path for its own diff/`@` features). Ask the agent to run
+   `pwd; uname -s; echo $PATH` and it should answer `/home/..., Linux` and a
+   five-entry PATH.
+4. `标记已有` renames existing `\\wsl.localhost\...` workspaces with the `🐧`
+   prefix; workspaces that already carry it are skipped and the panel reports
+   how many changed. Renaming is only cosmetic — the preset default keys off
+   the path, so an unmarked WSL workspace still gets `WSL` sessions.
+
+## Limits (deliberate, documented)
+
+- `watch` is not implemented by the WSL filesystem, so the skill catalog is
+  collected once (`watch: false`) instead of being invalidated live.
+- The Host keeps the durable session cwd as the UNC path, because host
+  features (diff view, `@` references, open-in-app) resolve it through the
+  Windows filesystem. WSL-preset sessions present the **Linux** equivalent as
+  `Current working directory` to the Agent, so every model-visible path is
+  Linux; every tool still accepts either form.
+- A WSL snapshot companion serves the changed-files summary/comparison for WSL
+  Sessions; the Host recorder still runs as the `workspace/changes` event
+  source and fallback. When the WSL snapshot misses the event race, the card
+  falls back to the Host summary. Open coordinates (`path`/`cwd`) stay UNC.
+- A filesystem target carries its own distribution, so workspaces from several
+  distributions coexist; a call with a Linux-only path falls back to the
+  distribution the world was configured with.
+- `grep` uses a JavaScript regular expression and skips files over 2 MiB;
+  `glob`/`grep` require an explicit `path`. Inside a Git worktree both respect
+  `.gitignore` (they list files with `git ls-files --exclude-standard`), so
+  `build/`, `dist/` and ignored dependency trees are not searched; outside a
+  worktree the walk prunes `.git`/`node_modules`.
+
+## SSH and web
+
+- `ssh`, `scp`, `rsync` and `curl` are the distribution's own binaries; keys
+  and `~/.ssh/config` belong to the distribution user, not to Windows. The
+  Agent has no TTY, so use key-based auth (`ssh -o BatchMode=yes host 'cmd'`)
+  or `ControlMaster` for reuse; interactive password logins belong in the
+  sidebar terminal. A `Host *` block with `ControlMaster auto`,
+  `ControlPath ~/.ssh/cm-%r@%h:%p` and `ControlPersist 10m` makes one-shot
+  Agent commands reuse a single connection.
+- `web_fetch` / `web_search` run on the Host but share the network. A service
+  started inside the distribution is reachable from Windows at
+  `http://localhost:<port>` (WSL2 localhost forwarding), so both the web tools
+  and `curl` work; use `curl` in `bash` when the service is reachable only
+  through an SSH tunnel.
+
+## Doctor and settings
+
+The `WSL` panel has **运行诊断**: it checks the WSL version, each distribution's
+user/home, Linux `node`, `git`, `ssh`, SSH keys, `~/.ssh/config`, the login PATH
+and how many `/mnt` entries the plugin has to remove, plus `.wslconfig`
+networking mode and localhost forwarding. Missing pieces offer guided actions:
+
+- **安装 Node** — `apt-get install nodejs` as the distro user (uses `sudo -n`;
+  refuses without passwordless sudo and prints the command instead);
+- **生成 SSH key** — `ssh-keygen -t ed25519` with no passphrase, then shows the
+  public key to add to devices;
+- **写 SSH 配置** — appends a `ControlMaster`/`ControlPersist` block once;
+- **创建普通用户** — when a distro's default user is `root` and it has no normal
+  user, creates `chronos` (locked password, home, bash).
+
+Settings store a **default distribution** and a **per-distribution login user**
+in `~/.dsh/remote-wsl-settings.json`. The user field is a dropdown of users
+reported by the doctor; a root distro is automatically moved to its first normal
+user when settings are empty. The terminal, WSL preset and `@` index all use
+that user, so a Session and its terminal run as the same non-root identity.
+Leave it empty only when the distro default is already the intended user.
+
+The panel and plugin icon are a penguin outline (white body, current-color
+outline, no blue tile); the display title is `WSL` and the package id is
+`@chronosun/dsh-wsl`.
+
+## Compatibility
+
+| DSH | Status |
+|---|---|
+| `0.2.2-rc.1` | tested (unit + real WSL + Agent A/B eval) |
+| other `0.2.x` | capability-probed, untested |
+
+The Host seam is narrow: `sessionController.create`, `workingDirectory.contextText`,
+`fileReferences.list`, `workspaceChanges.summary/diff`, plus the web server.
+Each patch checks the service/method and degrades independently; `/dsh-wsl/state`
+reports `capabilities` so a missing seam is visible instead of taking the whole
+plugin down. The WSL preset itself uses only published Cordis services.
+
+## Verifying a live install
+
+From the source checkout, after restarting DSH to load the current profile:
+
+```sh
+node tools/verify-live.mjs
+```
+
+It checks the installed Host version, the `wslDiff` install flag, all
+capabilities, the doctor's Node/PATH result for every distro, and the settings
+endpoint. Worktree creation and the panel render are manual: open a new WSL
+session and call `create_wsl_worktree`, then open the WSL panel's Doctor /
+Settings section.
+
+## Troubleshooting
+
+- **`WSL 发行版里没有 node`** — the distribution has no Linux Node.js (the
+  Windows `node.exe` on `/mnt/...` does not count and is rejected). Install it
+  inside the distribution, then press `断开` → `连接` in the panel:
+  `sudo apt-get update && sudo apt-get install -y nodejs` (Ubuntu/Debian), or
+  put a v18+ `node` on the login-shell `PATH` (`bash -lc 'command -v node'`).
+  The broker caches the resolved path in `~/.dsh/wsl-broker-cache.json` and
+  self-heals once when that path goes stale.
+- **New Session still opens in Standard/PTC instead of WSL** — the profile was
+  started before this version: the preset default is installed by the Host row
+  at boot. Restart DSH (tray → quit), or check the `WSL` panel: it says when
+  the default injection is not installed.
+- **Agent still sees a `\\wsl.localhost\...` working directory** — `/dsh-wsl/state`
+  should report `modelCwd.installed: true`. If it is missing, this build
+  predates 1.0.6 or the Host row was not reloaded: restart DSH. The durable
+  session cwd is intentionally still UNC for the Host's diff/`@` features.
+- **`npm` / `cargo` / compiler not found in a WSL session** — commands inherit
+  the distribution login PATH with `/mnt/*` removed. If a tool lives in a
+  directory your login shell does not export, add it to `~/.profile` (or
+  `~/.bash_profile`), then reconnect. The pre-broker fallback also includes
+  `~/.local/bin`, `~/.cargo/bin` and `~/.hermes/node/bin`.
+- **No `WSL` entry in the sidebar** — the bundle is installed but the client
+  half was not scanned; reinstall from a tarball (`remove_bundle` →
+  `install_bundle`) and restart.
+- **`agent-preset/invalid: <row> (<package>): ...`** — one preset row failed to
+  activate; the message names the exact service, usually a missing `isolate`
+  entry on the `wsl-world` group.
+- **`Receiver must be an instance of class ...`** — a provider used `#private`
+  members; Cordis' service proxy calls methods with a different `this`.
+- **`wsl-exec: line 1: exec: : not found`** — `wsl.exe` drops trailing
+  arguments; commands must travel inside a single `-c` script.
+- **`syntax error near unexpected token '('`** — `wsl.exe` pre-expands `$VAR`
+  in its command line against the dirty target environment; commands are
+  base64-encoded to avoid it. Quote variables in commands you write yourself.
+
+Set `DSH_WSL_DEBUG=1` to append provider traces to
+`wsl-world.log` beside this package's source.