dsh-bash-terminal-ts 0.7.0 → 0.7.2-compat.2

package/README.de.md

@@ -0,0 +1,205 @@
+# dsh-bash-terminal-ts
+
+> 🌐 [简体中文](README.md) | [English](README.en.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Italiano](README.it.md) | [Русский](README.ru.md) | [Español](README.es.md) · Community: [LINUX DO](https://linux.do) · [GitHub](https://github.com/drscrewdriver/dsh-bash-terminal-ts)
+
+![test](https://github.com/drscrewdriver/dsh-bash-terminal-ts/actions/workflows/test.yml/badge.svg)
+
+DSH-Plugin (DeepSeek Harness): ein `shell`-Werkzeug, das unter Windows die Befehle **vierer** Terminals – **PowerShell / Git Bash / MSYS2 / WSL** – einheitlich ausführt.
+
+> **Dieses Repository ist die TypeScript-Neuschreibung von `MAXeaglet/dsh-bash-terminal`** mit funktionsfähiger MSYS2/MINGW64-Unterstützung. Die Kompatibilitätslinien werden pro DSH-Host-Segment geschnitten; alle Linien teilen sich den Paketnamen `dsh-bash-terminal-ts` und werden über npm-dist-tags unterschieden:
+>
+> | DSH-Segment | Branch | Plugin-Version | npm-dist-tag |
+> |--------|------|----------|--------------|
+> | `>=0.2.0-rc.1 <0.2.1-0` | `compat/0.2.0` (dieser Branch) | 0.7.x | `dsh-0.2.0` |
+> | 0.1.7-rc.1 – 0.1.7.x | `compat/0.1.7` | 0.6.x | `dsh-0.1.7` |
+> | 0.1.5-alpha.1 – 0.1.5-rc.x | `ts/0.1.5` (historisch, eingefroren) | ≤ 0.5.2 | `dsh-0.1.5` |
+> | 0.1.2-alpha.1 – 0.1.2-rc.x | `main` (historisch, eingefroren) | ≤ 0.4.2 | `dsh-0.1.2` |
+>
+> Wählen Sie die Linie passend zu Ihrer DSH-Version; die Versionsserien überlappen nicht, daher kann eine `^`-Installation nie über Linien hinweg auflösen.
+
+| Backend | Tatsächliche Ausführung | Syntax / Pfade | Umgebungsvariablen |
+|------|----------|-------------|----------|
+| `powershell` (Standard) | `pwsh -NoLogo -NoProfile -NonInteractive -Command <cmd>` | PowerShell; `C:\...` | `$env:NAME` |
+| `gitbash` | `bash -lc <cmd>` aus Git for Windows | POSIX; `/d/workspace`; PATH enthält `/usr/bin` und `/mingw64/bin` | `$NAME` |
+| `msys2` | MSYS2 `bash -lc <cmd>` (`C:\msys64\usr\bin\bash.exe`) | POSIX; `/c/...`; PATH enthält `/usr/bin` und `/mingw64/bin` (gcc / make) | `$NAME` (`MSYSTEM=MINGW64` wird automatisch injiziert) |
+| `wsl` | `wsl [-d <distro>] -e bash -lc <cmd>` | Linux; `/mnt/d/...` | `$NAME` (über WSLENV) |
+
+Jeder Aufruf startet eine komplett neue Shell: **Es wird kein Zustand bewahrt** (cwd / Variablen / Aliasse) – übergeben Sie `workdir`, statt `cd` zu verwenden.
+
+## Vorschau der Oberfläche
+
+Die Zeile „Standardterminal" in Einstellungen → Allgemein: Der Nutzer wählt zwischen PowerShell / Git Bash / MSYS2 / WSL, und das `shell`-Werkzeug führt ausschließlich gemäß dieser Einstellung aus – das Modell kann sie nicht überschreiben:
+
+![Zeile für die Standardterminal-Einstellung](assets/shells.png)
+
+## Entwurfsprinzipien
+
+- **Das Terminal bestimmt der Nutzer, die KI kann es nicht ändern**: Die Einstellungsseite der Web-UI (Einstellungen → Allgemein) bietet ein Dropdown „Standardterminal" (PowerShell / Git Bash / MSYS2 / WSL); das `shell`-Werkzeug folgt stets ausschließlich dieser Einstellung und legt dem Modell keine Terminal-Parameter offen. Die Einstellung wird über das DSH-Settings-System persistiert (settings.yaml).
+- **Belegt die Fähigkeitsschnittstelle `ctx.shell` nicht**: Das sandboxierte `pwsh`-Werkzeug von DSH bleibt unverändert nutzbar; das `shell`-Werkzeug dieses Plugins ist ein **zusätzlicher** Multi-Terminal-Einstiegspunkt.
+- Prozesse werden über die gemeinsame `ctx.subprocess`-Naht erzeugt: Beendigung des Prozessbaums (unter Windows `taskkill /T`), SIGTERM → Gnistenfrist → SIGKILL, Ausgabe-Spill-Dateien – Verhalten identisch zu den offiziellen Werkzeugen `dsh-tool-bash` / `dsh-tool-pwsh`.
+- Hintergrundaufgaben werden im generischen `jobs`-Registry registriert, mit Unterstützung für `run_in_background` / `job_output` / `job_kill`.
+- Die Zeile „Standardterminal" der Frontend-Einstellungsseite ist eine Enumeration (von der UI automatisch als Dropdown gerendert); das Modell führt bei jedem Aufruf gemäß dieser Einstellung aus und kann das Terminal nicht eigenmächtig wechseln.
+
+## Installation (Web-Profil)
+
+### Standardinstallation (nach der npm-Veröffentlichung, offizieller Bundle-Mechanismus)
+
+Das Plugin bringt das offizielle `dsh.bundle`-Manifest mit (eigene `cordis.patch.yml` im Paket); sobald ein Profil dieses Paket aufführt, **wendet DSH den Mount automatisch an** – eine manuelle Anpassung der Profil-Konfiguration ist nicht nötig:
+
+```powershell
+# 1. Plugin-Paket installieren
+npm install -g dsh-bash-terminal-ts
+dsh plugin --profile web add dsh-bash-terminal-ts   # automatisch in die Profile-Bundles aufnehmen und Patch anwenden
+
+# 2. Settings-Allowlist von DSH patchen (DSH-Einschränkung, siehe Erläuterung unten)
+powershell -ExecutionPolicy Bypass -File install.ps1 install
+
+# 3. dsh web neu starten
+```
+
+> Mit einem temporären Profil praktisch erprobt: `bundles: [dsh-bash-terminal-ts]` → der Eintrag `tool-bash-terminal` erscheint automatisch im dump-config.
+
+### Installation für die lokale Entwicklung (Junction, Quellcode-Änderungen wirken sofort)
+
+```powershell
+# 1. Plugin-Paket in die node_modules des Profils linken (Junction, Quellcode-Änderungen wirken sofort)
+$profile = "$env:USERPROFILE\.dsh\profiles\web"
+New-Item -ItemType Junction -Path "$profile\node_modules\dsh-bash-terminal-ts" -Target "D:\workspace\projects\dsh-bash-terminal-ts" | Out-Null
+
+# 2. Dem Plugin die Auflösung der @deepseek-ai/*-Abhängigkeiten ermöglichen (Junction in den Abhängigkeitsbaum des Profils; Plugin und Host teilen sich dieselben Modulinstanzen)
+New-Item -ItemType Junction -Path "D:\workspace\projects\dsh-bash-terminal-ts\node_modules\@deepseek-ai" -Target "$profile\..\node_modules\@deepseek-ai" | Out-Null
+
+# 3. Das Profil das Plugin über das offizielle Bundle mounten lassen (install.ps1 install erledigt das automatisch; entspricht dem Eintrag "dsh-bash-terminal-ts" in dsh.profile.bundles)
+# 4. (nur nach Änderungen am Frontend-Quellcode) Client-Bundle neu bauen:
+#    cd D:\workspace\projects\dsh-bash-terminal-ts && node scripts/build-client.mjs
+# 5. dsh web neu starten
+```
+
+> ⚠️ **Führen Sie in diesem Projekt kein `npm install` aus**: Es würde die Junction aus Schritt 2 oben löschen und stattdessen eine **eigenständige** Kopie von
+> `@deepseek-ai/*` für das Plugin installieren – Plugin und Host teilten sich dann keine Modulinstanzen mehr, und nach einem Host-Upgrade bliebe das Plugin auf der alten API hängen
+> (dieses Projekt hing dadurch einmal auf 0.1.0-rc.6 fest). Nur zum Aktualisieren des Locks `npm install --package-lock-only` verwenden.
+
+> **Kompatibilität**: Erfordert DSH ≥ **0.1.7-rc.1** (Linie `compat/0.1.7`) oder ≥ **0.2.0-rc.1** (Linie `compat/0.2.0`, dieser Branch).
+> Historischer Hintergrund: In 0.1.5 wurde `@deepseek-ai/dsh-client-runtime` in der Client-Modultabelle in `@deepseek-ai/dsh-client-store` umbenannt und wird nur über exakte Treffer des nackten Namens aufgelöst; alte Bundles schlagen auf dem neuen Host fehl mit
+> `Failed to load plugins` / `require(...) missed the module table`.
+>
+> Hinweis: Seit 0.1.5 nutzt die Web-Settings-Oberfläche die dynamische Enumeration `settings.describe()` und hat **keine Namespace-Allowlist mehr**
+> (`settings-not-exposed` existiert nicht mehr); der Allowlist-Patch in `install.ps1` ist nur noch ein historisches Überbleibsel und kann ignoriert werden.
+
+> Eine manuelle Anpassung der `cordis.patch.yml` des Profils ist nicht mehr erforderlich: Das Plugin-Paket bringt sein eigenes `dsh.bundle.patch` mit (`cordis.patch.yml` im Paket); sobald `dsh-bash-terminal-ts` im `dsh.profile.bundles` des Profils steht, mountet DSH das Plugin automatisch.
+
+Kombinierten Baum verifizieren (ohne Neustart):
+
+```powershell
+node "$env:APPDATA\nvm\<node-version>\node_modules\@deepseek-ai\dsh\lib\bin.js" --profile web --dump-config | Select-String dsh-bash-terminal-ts
+```
+
+## Verwendung
+
+**Der Nutzer wählt das Standardterminal in der Web-UI**: Einstellungen (Zahnrad) öffnen → Allgemein → Dropdown „Standardterminal" und eines der Terminals PowerShell / Git Bash / MSYS2 / WSL wählen. Änderungen wirken sofort und werden persistiert.
+
+Sobald das Modell das `shell`-Werkzeug sieht, verwendet es automatisch das von Ihnen gewählte Terminal (das Werkzeug legt keinen Terminal-Parameter offen; das Modell kann Ihre Wahl nicht ändern):
+
+- Standardterminal = Git Bash: `shell(command: "git status")` läuft über Git Bash
+- Standardterminal = MSYS2: `shell(command: "gcc --version")` läuft über MSYS2 (MINGW64-Umgebung, gcc und make aus `/mingw64/bin` verfügbar)
+- Standardterminal = WSL: `shell(command: "ls -la /mnt/d/workspace")` läuft über WSL; mit `distro: "Ubuntu"` lässt sich die Distribution angeben
+- Standardterminal = PowerShell: `shell(command: "Get-Process node")` läuft über PowerShell
+
+## Beispiele zur Modellnutzung
+
+- Einmalbefehl (Standardterminal): `shell(command: "git status", description: "Git-Status prüfen")`
+- Zustand über Runden hinweg bewahren (interaktiv): `terminal(action: "open")` → `sessionId` notieren → `terminal(action: "send", sessionId, input: "cd /d/project\n")` → `terminal(action: "send", sessionId, input: "npm run dev\n")` → `terminal(action: "close", sessionId)`
+- Laufendes Programm unterbrechen: `terminal(action: "signal", sessionId, signal: "SIGINT")`
+- Aktive Sitzungen einsehen: `terminal(action: "list")`
+- Eskalation nach Sandbox-Ablehnung: `shell(command: ..., sandbox_permissions: "workspace-write", justification: "...")`
+
+## Konfiguration
+
+**Web-UI-Einstellungen** (empfohlen): Einstellungen → Allgemein → „Standardterminal".
+
+`config` der Plugin-Zeile (überschreibt die Standardwerte und dient als Kompositionsgrundlage der Einstellungen):
+
+| Schlüssel | Standard | Beschreibung |
+|----|------|------|
+| `defaultShell` | `powershell` | Backend, sofern die Einstellungen nichts anderes festlegen |
+| `timeoutMs` | 120000 | Standard-Timeout |
+| `maxTimeoutMs` | 600000 | Obergrenze für das timeoutMs des Aufrufers |
+| `pwshPath` | automatische Erkennung | Fester Pfad zu pwsh.exe |
+| `gitBashPath` | automatische Erkennung | Fester Pfad zu git bash.exe |
+| `msys2Path` | automatische Erkennung (`C:\msys64\usr\bin\bash.exe` bevorzugt, Fallback `msys2.exe`) | Fester Pfad zu MSYS2 bash.exe |
+| `wslPath` | automatische Erkennung | Fester Pfad zu wsl.exe |
+
+## Veröffentlichung (npm)
+
+Das npm-Konto hat die 2FA-Verifizierung für Veröffentlichungen aktiviert; ein Einmalcode ist erforderlich:
+
+```powershell
+cd D:\workspace\projects\dsh-bash-terminal-ts
+npm publish --otp <Code>   # der Code stammt von Ihrem Authentifikator
+```
+
+Vor der Veröffentlichung mit `npm pack --dry-run` den Inhalt prüfen und `npm run build` ausführen, um alles neu zu bauen (tsc-Serverkompilierung + Client-Bundle + Testkompilierung).
+
+## Deinstallation
+
+Einfach ausführen:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File install.ps1 uninstall
+```
+
+Der Befehl entfernt die Junctions, stellt die Settings-Allowlist wieder her, räumt die veralteten `cordis.patch.yml`-Mount-Blöcke früherer Versionen auf und entfernt `dsh-bash-terminal-ts` aus dem `dsh.profile.bundles`. Anschließend dsh web neu starten.
+
+Bei manueller Deinstallation ist – neben dem Entfernen von `node_modules\dsh-bash-terminal-ts` – auch daran zu denken, `dsh-bash-terminal-ts` aus dem `dsh.profile.bundles` der Profil-`package.json` zu entfernen.
+
+## Interaktives Terminal (Werkzeug `terminal`)
+
+Das Werkzeug `terminal` stellt **persistente interaktive Sitzungen** über die PTY-Naht bereit (node-pty; unter Windows direkt über node-pty, weil der Process Inspector des upstream `spawnTerminal` nur POSIX unterstützt – `lib/terminal.js` verbindet sich daher direkt mit node-pty; unter Nicht-Windows wird weiterhin das offizielle `ctx.subprocess.spawnTerminal` verwendet):
+
+- `action: open` startet eine echte Terminal-Sitzung (gemäß Ihrer Standardterminal-Einstellung; bei wsl kann `distro` angegeben werden) und liefert eine `sessionId`
+- `action: send` schreibt die Eingabe und liest die neue Ausgabe; `action: read` liest nur, ohne zu schreiben; `action: signal` sendet ein Signal an die Vordergrund-Prozessgruppe (SIGINT = Ctrl+C)
+- `action: close` beendet die Sitzung
+- **Der Sitzungszustand bleibt über Aufrufe hinweg erhalten** (cwd / Variablen / Aliasse), geeignet für REPL, ssh und interaktive CLIs
+- `send` wartet, bis sich die Ausgabe stabilisiert hat (300 ms Stille, Obergrenze 5 s), und liefert die **vollständige Antwort**; bei mehr als 1 MB Ausgabe folgt der Hinweis `truncated`
+- Die Eingabe endet mit `\\n` (oder \\r), um die Eingabetaste zu signalisieren
+
+## Sandbox (Anbindung an den offiziellen Mechanismus)
+
+Das `shell`-Werkzeug nutzt die offizielle Sandbox-Naht von DSH (`ctx.sandboxPolicy` + `ctx.sandbox`):
+
+- Bei jedem Aufruf wird die aktuelle Sandbox-Richtlinie aufgelöst; `danger-full-access`-Sitzungen werden direkt ausgeführt (ohne Ummantelung).
+- Das PowerShell-Backend umhüllt argv über `ctx.sandbox.confine` – dieselbe **Fail-closed**-Semantik wie bei den offiziellen Executoren: Wird der eingeschränkte Modus angefordert, aber kein Backend gefunden, fliegt eine `SandboxUnavailableError`; ein ungeschützter Lauf wird verweigert.
+- Das Git-Bash-Backend wird nicht umhüllt: Der Windows-ACL-Restricted-Token-Runner von DSH ist inkompatibel mit Cygwin/MSYS2 (bash bricht beim Start mit `CreateFileMapping` Win32-Fehler 5 ab); daher läuft Git Bash auch im eingeschränkten Modus ohne Sandbox-Ummantelung; das Ergebnis meldet `enforcement: gitbash-unconfined`.
+- Das MSYS2-Backend wird ebenfalls nicht umhüllt (dieselbe Cygwin/MSYS2-Laufzeitinkompatibilität); das Ergebnis meldet `enforcement: msys2-unconfined`.
+- Das WSL-Backend wird nicht umhüllt: Die eigenständige Linux-VM von WSL ist selbst die Isolation (das Ergebnis meldet `enforcement: wsl-isolation`).
+- Wird ein Aufruf im eingeschränkten Modus von der Sandbox abgelehnt, trägt das Ergebnis das offizielle Kennzeichen `[sandbox: file access denied under <mode> mode]` samt Eskalationshinweis für dieselbe Runde; das Modell kann mit `sandbox_permissions` + `justification` eine Eskalation anstoßen (Nutzerfreigabe über `ctx.approval`) – exakt wie bei den offiziellen bash/pwsh-Werkzeugen.
+- Hinweis: Wenn der Windows-ACL-Runner von DSH verfügbar ist, wird der eingeschränkte Modus von PowerShell über ihn umhüllt; Git Bash und MSYS2 bleiben wegen der Cygwin/MSYS2-Inkompatibilität unumhüllt.
+
+## ⚠️ Sicherheitshinweis
+
+Das `shell`-Werkzeug im eingeschränkten Modus: PowerShell wird über `ctx.sandbox.confine` umhüllt (fail-closed); Git Bash und MSYS2 bleiben wegen der Inkompatibilität von Cygwin/MSYS2 mit dem Windows-ACL-Restricted-Token **unumhüllt** (gleiche Berechtigungen wie der dsh-Prozess); WSL bleibt dank seiner eigenständigen Linux-VM unumhüllt. Es ist ein **zusätzlicher Multi-Terminal-Einstiegspunkt** und genießt nicht die ConstrainedLanguage-Einschränkungen des offiziellen `pwsh`-Werkzeugs. Die Datei-Werkzeuge von DSH (read/write/edit) unterliegen weiterhin der Datei-Sandbox. Nur in Sitzungen verwenden, denen Sie vertrauen; für sandboxgeschütztes PowerShell weiterhin das offizielle `pwsh`-Werkzeug nutzen.
+
+## Bekannte Einschränkungen des interaktiven Terminals (ConPTY)
+
+- **PowerShell 5.1 kann in einem ConPTY nicht starten** (0x8009001d) – für interaktives PowerShell [PowerShell 7](https://github.com/PowerShell/PowerShell/releases) installieren (Einmalbefehle sind nicht betroffen).
+- **Der interaktive Modus von wsl.exe kann unter ConPTY einen RPC-Fehler des WSL-Dienstes auslösen** (0x8007072c, sporadisch) – Einmalbefehle `wsl -e bash -lc ...` funktionieren normal; für interaktive Sitzungen besser Windows Terminal / ein WSL-Terminal verwenden oder es erneut versuchen.
+- **node-pty akzeptiert unter Windows keine benannten Signale**: `SIGINT` von `signal` wird auf Ctrl+C (`\x03`) abgebildet; andere Signale (`SIGTERM` / `SIGKILL` / `SIGTSTP` / `SIGHUP`) degradieren zur Beendigung der Sitzung.
+- Interaktive Git-Bash-Sitzungen funktionieren vollumfänglich.
+
+## Bekannte Einschränkungen
+
+- WSL-Hintergrundprozesse können nach Timeout/Abbruch noch kurz in der Distribution weiterlaufen (die WSL-Instanz schaltet sich nach dem Ende des letzten Prozesses automatisch ab).
+- Git Bash ist eine msys2-Umgebung und weicht vom Linux-Verhalten von WSL ab (Pfad-Mapping, Paketverfügbarkeit).
+- Das MSYS2-Backend erfordert eine lokal installierte MSYS2 (Standard `C:\msys64`); ohne Installation meldet `shell` den Fehler `backend unavailable`, mit `msys2Path` lässt sich ein benutzerdefinierter Ort angeben. Die Kandidatenreihenfolge bleibt immer: `bash.exe` zuerst, `msys2.exe` als Fallback – bei weitergeleitetem stdio liefert `msys2.exe` stumm null Byte und dient nur als letzte Rettung.
+- Dieses Plugin registriert seine Werkzeuge nur auf der Plattform `win32`.
+
+## Tests
+
+```powershell
+cd D:\workspace\projects\dsh-bash-terminal-ts
+npm install          # Abhängigkeiten installieren (typescript inklusive)
+npm run build        # tsc-Kompilierung src/*.ts → lib/*.js; client.tsx → lib/client.js + dist/client.js; test/*.ts → test-dist/
+npm test             # node test-dist/unit.js → apply.js → client.js → terminal.js
+```
+
+Der Quellcode ist TypeScript (`strict` + `noUncheckedIndexedAccess`); die Build-Artefakte `lib/` und `dist/` werden mit dem Repository eingecheckt, DSH lädt direkt `lib/index.js` – ohne Installation einsatzbereit.

package/README.en.md

@@ -1,6 +1,6 @@
 # dsh-bash-terminal-ts
 
-> Community: [LINUX DO](https://linux.do) · [GitHub](https://github.com/drscrewdriver/dsh-bash-terminal-ts)
+> 🌐 [简体中文](README.md) | [English](README.en.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Italiano](README.it.md) | [Русский](README.ru.md) | [Español](README.es.md) · Community: [LINUX DO](https://linux.do) · [GitHub](https://github.com/drscrewdriver/dsh-bash-terminal-ts)
 
 A DeepSeek Harness (DSH) plugin: one `shell` tool that runs commands through **PowerShell / Git Bash / MSYS2 / WSL** on Windows, plus an **interactive terminal** tool — all following the terminal **you** choose in the Web UI settings.
 
@@ -50,6 +50,24 @@ powershell -ExecutionPolicy Bypass -File install.ps1 install   # patches the DSH
 
 > **DSH limitation**: the Web settings client only exposes a hard-coded allowlist of settings namespaces (`dsh-host-apiproxy`); third-party settings writes are refused with `settings-not-exposed` otherwise. `install.ps1` patches the allowlist (with a backup) — re-run it after upgrading DSH; `install` / `uninstall` restores it.
 
+### pnpm users: the node-pty build-script notice
+
+This plugin depends on the native PTY library [`node-pty`](https://www.npmjs.com/package/node-pty) (Microsoft-maintained, the same library VS Code uses) for the interactive `terminal` tool. **As of 0.7.1 it is pinned to `1.2.0-beta.15`** (the same version both DSH host lines use): the tarball ships prebuilt binaries for every platform, so even when pnpm 10+ skips the install script, the runtime loader falls back to `prebuilds/<platform>-<arch>/` and **runs without compiling**. The notice at the end of `pnpm add` only reports the skipped script; approve once to silence it:
+
+```text
+Error: ERR_PNPM_IGNORED_BUILDS
+  Ignored build scripts: node-pty@1.2.0-beta.15
+```
+
+```powershell
+pnpm approve-builds      # pick node-pty interactively
+# or declare it in the profile's package.json, then rebuild:
+#   "pnpm": { "onlyBuiltDependencies": ["node-pty"] }
+pnpm rebuild node-pty
+```
+
+> This is the **only** own dsh plugin with a native dependency; the other 0.2.0-line plugins (search-index, session-steward, patch-edit-plus, browser-cdp, date-wrapper) and live-token-stats are pure-JS and install on pnpm without any approval.
+
 For local development (junction install, source changes apply instantly) see the Chinese README's development section.
 
 ## Sandbox

package/README.es.md

@@ -0,0 +1,205 @@
+# dsh-bash-terminal-ts
+
+> 🌐 [简体中文](README.md) | [English](README.en.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Italiano](README.it.md) | [Русский](README.ru.md) | [Español](README.es.md) · Comunidad: [LINUX DO](https://linux.do) · [GitHub](https://github.com/drscrewdriver/dsh-bash-terminal-ts)
+
+![test](https://github.com/drscrewdriver/dsh-bash-terminal-ts/actions/workflows/test.yml/badge.svg)
+
+Plugin de DSH (DeepSeek Harness): una herramienta `shell` que ejecuta de forma unificada en Windows los comandos de **cuatro** terminales — **PowerShell / Git Bash / MSYS2 / WSL**.
+
+> **Este repositorio es la reescritura en TypeScript de `MAXeaglet/dsh-bash-terminal`**, con soporte MSYS2/MINGW64 funcional. Las líneas de compatibilidad se cortan por segmento de versión del host DSH; todas las líneas comparten el nombre de paquete `dsh-bash-terminal-ts` y se distinguen mediante dist-tags de npm:
+>
+> | Segmento DSH | Rama | Versión del plugin | dist-tag npm |
+> |--------|------|----------|--------------|
+> | `>=0.2.0-rc.1 <0.2.1-0` | `compat/0.2.0` (esta rama) | 0.7.x | `dsh-0.2.0` |
+> | 0.1.7-rc.1 – 0.1.7.x | `compat/0.1.7` | 0.6.x | `dsh-0.1.7` |
+> | 0.1.5-alpha.1 – 0.1.5-rc.x | `ts/0.1.5` (histórica, congelada) | ≤ 0.5.2 | `dsh-0.1.5` |
+> | 0.1.2-alpha.1 – 0.1.2-rc.x | `main` (histórica, congelada) | ≤ 0.4.2 | `dsh-0.1.2` |
+>
+> Elige la línea que cubra tu versión de DSH; las series de versiones nunca se solapan, por lo que una instalación con `^` no puede resolverse entre líneas.
+
+| Backend | Ejecución real | Sintaxis / rutas | Variables de entorno |
+|------|----------|-------------|----------|
+| `powershell` (predeterminado) | `pwsh -NoLogo -NoProfile -NonInteractive -Command <cmd>` | PowerShell; `C:\...` | `$env:NAME` |
+| `gitbash` | `bash -lc <cmd>` de Git for Windows | POSIX; `/d/workspace`; PATH con `/usr/bin` y `/mingw64/bin` | `$NAME` |
+| `msys2` | `bash -lc <cmd>` de MSYS2 (`C:\msys64\usr\bin\bash.exe`) | POSIX; `/c/...`; PATH con `/usr/bin` y `/mingw64/bin` (gcc / make) | `$NAME` (inyección automática de `MSYSTEM=MINGW64`) |
+| `wsl` | `wsl [-d <distro>] -e bash -lc <cmd>` | Linux; `/mnt/d/...` | `$NAME` (vía WSLENV) |
+
+Cada llamada arranca una shell totalmente nueva: **no se conserva estado alguno** (cwd / variables / alias) — pasa `workdir` en lugar de usar `cd`.
+
+## Vista previa de la interfaz
+
+La fila «Terminal predeterminado» en Ajustes → General: el usuario elige entre PowerShell / Git Bash / MSYS2 / WSL, y la herramienta `shell` ejecuta solo conforme a ese ajuste, sin que el modelo pueda saltárselo:
+
+![Fila del ajuste del terminal predeterminado](assets/shells.png)
+
+## Puntos de diseño
+
+- **El terminal lo decide el usuario, la IA no puede cambiarlo**: la página de ajustes de la UI web (Ajustes → General) muestra un desplegable de «Terminal predeterminado» (PowerShell / Git Bash / MSYS2 / WSL); la herramienta `shell` usa siempre únicamente ese ajuste y no expone ningún parámetro de terminal al modelo. El ajuste se persiste mediante el sistema de settings de DSH (settings.yaml).
+- **No ocupa la costura de capacidades `ctx.shell`**: la herramienta `pwsh` sandboxizada que trae DSH sigue disponible tal cual; la herramienta `shell` de este plugin es una **entrada adicional** multi-terminal.
+- Los procesos se derivan mediante la costura compartida `ctx.subprocess`: terminación del árbol de procesos (`taskkill /T` en Windows), SIGTERM → gracia → SIGKILL, archivos de spill de salida — comportamiento idéntico al de las herramientas oficiales `dsh-tool-bash` / `dsh-tool-pwsh`.
+- Las tareas en segundo plano se registran en el registro genérico de `jobs`, con soporte de `run_in_background` / `job_output` / `job_kill`.
+- La fila «Terminal predeterminado» de la página de ajustes del frontend es una enumeración (la UI la renderiza automáticamente como desplegable); en cada llamada el modelo ejecuta solo conforme a ese ajuste y no puede cambiar de terminal por su cuenta.
+
+## Instalación (perfil web)
+
+### Instalación estándar (tras la publicación en npm, mecanismo oficial de bundle)
+
+El plugin trae el manifiesto oficial `dsh.bundle` (`cordis.patch.yml` dentro del paquete); en cuanto un perfil lista este paquete, DSH **aplica el montaje automáticamente**, sin necesidad de editar a mano la configuración del perfil:
+
+```powershell
+# 1. Instalar el paquete del plugin
+npm install -g dsh-bash-terminal-ts
+dsh plugin --profile web add dsh-bash-terminal-ts   # se añade automáticamente a los bundles del perfil y aplica el parche
+
+# 2. Parchear la allowlist de ajustes de DSH (limitación de DSH, ver explicación abajo)
+powershell -ExecutionPolicy Bypass -File install.ps1 install
+
+# 3. Reiniciar dsh web
+```
+
+> Probado en la práctica con un perfil temporal: `bundles: [dsh-bash-terminal-ts]` → la entrada `tool-bash-terminal` aparece automáticamente en el dump-config.
+
+### Instalación para desarrollo local (junction, los cambios de código fuente surten efecto al instante)
+
+```powershell
+# 1. Enlazar el paquete del plugin a los node_modules del perfil (junction, los cambios de fuente surten efecto al instante)
+$profile = "$env:USERPROFILE\.dsh\profiles\web"
+New-Item -ItemType Junction -Path "$profile\node_modules\dsh-bash-terminal-ts" -Target "D:\workspace\projects\dsh-bash-terminal-ts" | Out-Null
+
+# 2. Permitir que el plugin resuelva las dependencias @deepseek-ai/* (junction hacia el árbol de dependencias del perfil; plugin y host comparten las mismas instancias de módulos)
+New-Item -ItemType Junction -Path "D:\workspace\projects\dsh-bash-terminal-ts\node_modules\@deepseek-ai" -Target "$profile\..\node_modules\@deepseek-ai" | Out-Null
+
+# 3. Dejar que el perfil monte el plugin mediante el bundle oficial (install.ps1 install lo hace automáticamente; equivale a añadir "dsh-bash-terminal-ts" a dsh.profile.bundles)
+# 4. (solo tras modificar el código del frontend) recompilar el bundle del cliente:
+#    cd D:\workspace\projects\dsh-bash-terminal-ts && node scripts/build-client.mjs
+# 5. Reiniciar dsh web
+```
+
+> ⚠️ **No ejecutes `npm install` en este proyecto**: borraría la junction del paso 2 de arriba e instalaría para el plugin una copia **independiente** de
+> `@deepseek-ai/*` — plugin y host dejarían de compartir instancias de módulos y, tras una actualización del host, el plugin se quedaría en la API antigua
+> (este proyecto llegó a quedarse atascado en 0.1.0-rc.6 por esa razón). Para refrescar solo el lock, usa `npm install --package-lock-only`.
+
+> **Compatibilidad**: requiere DSH ≥ **0.1.7-rc.1** (línea `compat/0.1.7`) o ≥ **0.2.0-rc.1** (línea `compat/0.2.0`, esta rama).
+> Contexto histórico: en 0.1.5, `@deepseek-ai/dsh-client-runtime` en la tabla de módulos del cliente pasó a llamarse `@deepseek-ai/dsh-client-store` y solo se resuelve por coincidencia exacta del nombre desnudo; los bundles antiguos fallan en el host nuevo con
+> `Failed to load plugins` / `require(...) missed the module table`.
+>
+> Además: desde 0.1.5 la superficie de ajustes web usa la enumeración dinámica `settings.describe()` y **ya no tiene una allowlist de namespaces**
+> (`settings-not-exposed` ya no existe); el parche de allowlist presente en `install.ps1` es solo un residuo histórico y puede ignorarse.
+
+> Ya no hace falta editar manualmente el `cordis.patch.yml` del perfil: el paquete del plugin trae su propio `dsh.bundle.patch` (`cordis.patch.yml` dentro del paquete); basta con que `dsh-bash-terminal-ts` figure en el `dsh.profile.bundles` del perfil para que DSH monte el plugin automáticamente.
+
+Verificar el árbol combinado (sin reiniciar):
+
+```powershell
+node "$env:APPDATA\nvm\<node-version>\node_modules\@deepseek-ai\dsh\lib\bin.js" --profile web --dump-config | Select-String dsh-bash-terminal-ts
+```
+
+## Uso
+
+**El usuario establece el terminal predeterminado en la UI web**: abre los ajustes (engranaje) → General → desplegable «Terminal predeterminado» y elige uno entre PowerShell / Git Bash / MSYS2 / WSL. El cambio surte efecto de inmediato y se persiste.
+
+Cuando el modelo ve la herramienta `shell`, ejecuta automáticamente con el terminal que elegiste (la herramienta no expone parámetros de terminal; el modelo no puede cambiar tu elección):
+
+- Terminal predeterminado = Git Bash: `shell(command: "git status")` va por Git Bash
+- Terminal predeterminado = MSYS2: `shell(command: "gcc --version")` va por MSYS2 (entorno MINGW64, disponibles gcc y make de `/mingw64/bin`)
+- Terminal predeterminado = WSL: `shell(command: "ls -la /mnt/d/workspace")` va por WSL; `distro: "Ubuntu"` permite indicar la distribución
+- Terminal predeterminado = PowerShell: `shell(command: "Get-Process node")` va por PowerShell
+
+## Ejemplos de uso para el modelo
+
+- Comando puntual (terminal predeterminado): `shell(command: "git status", description: "ver el estado de git")`
+- Estado preservado entre turnos (interactivo): `terminal(action: "open")` → anota el `sessionId` → `terminal(action: "send", sessionId, input: "cd /d/project\n")` → `terminal(action: "send", sessionId, input: "npm run dev\n")` → `terminal(action: "close", sessionId)`
+- Interrumpir un programa en ejecución: `terminal(action: "signal", sessionId, signal: "SIGINT")`
+- Consultar las sesiones activas: `terminal(action: "list")`
+- Escalada tras un rechazo de la sandbox: `shell(command: ..., sandbox_permissions: "workspace-write", justification: "...")`
+
+## Configuración
+
+**Ajustes de la UI web** (recomendado): Ajustes → General → «Terminal predeterminado».
+
+El `config` de la fila del plugin (sobrescribe los predeterminados y sirve de base de composición para los ajustes):
+
+| Clave | Predeterminado | Descripción |
+|----|------|------|
+| `defaultShell` | `powershell` | Backend usado cuando los ajustes no sobrescriben |
+| `timeoutMs` | 120000 | Tiempo de espera predeterminado |
+| `maxTimeoutMs` | 600000 | Límite superior del timeoutMs del llamante |
+| `pwshPath` | detección automática | Ruta fija de pwsh.exe |
+| `gitBashPath` | detección automática | Ruta fija de git bash.exe |
+| `msys2Path` | detección automática (primero `C:\msys64\usr\bin\bash.exe`, reserva en `msys2.exe`) | Ruta fija de MSYS2 bash.exe |
+| `wslPath` | detección automática | Ruta fija de wsl.exe |
+
+## Publicación (npm)
+
+La cuenta de npm tiene activada la verificación 2FA para publicar; hace falta un código de un solo uso:
+
+```powershell
+cd D:\workspace\projects\dsh-bash-terminal-ts
+npm publish --otp <código>   # el código lo da tu autenticador
+```
+
+Antes de publicar, haz un `npm pack --dry-run` para revisar el contenido y ejecuta `npm run build` para recompilar todo (compilación de servidor con tsc + bundle del cliente + compilación de los tests).
+
+## Desinstalación
+
+Basta con ejecutar:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File install.ps1 uninstall
+```
+
+Elimina las junction, restaura la allowlist de ajustes, limpia los bloques de montaje `cordis.patch.yml` heredados de versiones antiguas y retira `dsh-bash-terminal-ts` del `dsh.profile.bundles`. Después reinicia dsh web.
+
+En una desinstalación manual, además de borrar `node_modules\dsh-bash-terminal-ts`, recuerda también retirar `dsh-bash-terminal-ts` del `dsh.profile.bundles` del `package.json` del perfil.
+
+## Terminal interactivo (herramienta `terminal`)
+
+La herramienta `terminal` ofrece **sesiones interactivas persistentes** sobre la costura PTY (node-pty; en Windows, como el process inspector del `spawnTerminal` upstream solo admite POSIX, `lib/terminal.js` se conecta directamente a node-pty; fuera de Windows se sigue usando el `ctx.subprocess.spawnTerminal` oficial):
+
+- `action: open` inicia una sesión de terminal real (según tu terminal predeterminado configurado; en wsl se puede pasar `distro`) y devuelve un `sessionId`
+- `action: send` escribe la entrada y lee la nueva salida; `action: read` solo lee, sin escribir; `action: signal` envía una señal al grupo de procesos en primer plano (SIGINT = Ctrl+C)
+- `action: close` termina la sesión
+- **El estado de la sesión se conserva entre llamadas** (cwd / variables / alias), ideal para REPL, ssh y CLIs interactivos
+- `send` espera a que la salida se estabilice (300 ms de silencio, tope de 5 s) y devuelve la **respuesta completa**; con más de 1 MB de salida emite el aviso `truncated`
+- La entrada termina en `\\n` (o \\r) para representar la tecla Enter
+
+## Sandbox (conexión con el mecanismo oficial)
+
+La herramienta `shell` pasa por la costura oficial de sandbox de DSH (`ctx.sandboxPolicy` + `ctx.sandbox`):
+
+- En cada llamada se resuelve la política de sandbox vigente; las sesiones `danger-full-access` se ejecutan directamente (sin envoltura).
+- El backend PowerShell envuelve el argv mediante `ctx.sandbox.confine` — la misma semántica **fail-closed** que los ejecutores oficiales: si se pide el modo restringido y no hay backend disponible, se lanza `SandboxUnavailableError`, rechazando la ejecución desnuda.
+- El backend Git Bash no se envuelve: el runner de token restringido con ACL de Windows de DSH es incompatible con Cygwin/MSYS2 (bash aborta al arrancar con el error Win32 5 de `CreateFileMapping`); por eso Git Bash tampoco pasa por envoltura de sandbox en modo restringido; el resultado informa `enforcement: gitbash-unconfined`.
+- El backend MSYS2 tampoco se envuelve (la misma incompatibilidad de runtime Cygwin/MSYS2); el resultado informa `enforcement: msys2-unconfined`.
+- El backend WSL no se envuelve: la máquina virtual Linux independiente de WSL es por sí misma el aislamiento (el resultado informa `enforcement: wsl-isolation`).
+- Cuando la sandbox rechaza en modo restringido, el resultado lleva el marcador oficial `[sandbox: file access denied under <mode> mode]` y la pista de escalada del mismo turno; el modelo puede iniciar una escalada con `sandbox_permissions` + `justification` (aprobación del usuario vía `ctx.approval`), exactamente igual que las herramientas oficiales bash/pwsh.
+- Nota: cuando el runner de ACL de Windows de DSH está disponible, el modo restringido de PowerShell se envuelve a través de él; Git Bash y MSYS2 siguen sin envolver por la incompatibilidad Cygwin/MSYS2.
+
+## ⚠️ Notas de seguridad
+
+La herramienta `shell` en modo restringido: PowerShell se envuelve vía `ctx.sandbox.confine` (fail-closed); Git Bash y MSYS2 **no se envuelven** por la incompatibilidad entre Cygwin/MSYS2 y los tokens restringidos de ACL de Windows (mismos permisos que el proceso dsh); WSL no se envuelve gracias a su VM Linux independiente. Es una **entrada adicional multi-terminal** y no disfruta de las restricciones ConstrainedLanguage de la herramienta oficial `pwsh`. Las herramientas de manejo de archivos de DSH (read/write/edit) siguen sujetas a la sandbox de archivos. Úsala solo en sesiones de confianza; para un PowerShell protegido por la sandbox sigue usando la herramienta oficial `pwsh`.
+
+## Limitaciones conocidas del terminal interactivo (ConPTY)
+
+- **PowerShell 5.1 no puede arrancar en un ConPTY** (0x8009001d) — para PowerShell interactivo instala [PowerShell 7](https://github.com/PowerShell/PowerShell/releases) (los comandos puntuales no se ven afectados).
+- **El modo interactivo de wsl.exe puede desencadenar un error RPC del servicio WSL bajo ConPTY** (0x8007072c, intermitente) — los comandos puntuales `wsl -e bash -lc ...` funcionan con normalidad; para sesiones interactivas conviene usar directamente Windows Terminal / un terminal de WSL, o reintentar.
+- **node-pty no acepta señales con nombre en Windows**: el `SIGINT` de `signal` se mapea a Ctrl+C (`\x03`); las demás señales (`SIGTERM` / `SIGKILL` / `SIGTSTP` / `SIGHUP`) degradan a terminar la sesión.
+- Las sesiones interactivas de Git Bash funcionan por completo.
+
+## Limitaciones conocidas
+
+- Los procesos en segundo plano de WSL pueden sobrevivir brevemente dentro de la distribución tras un timeout/interrupción (la instancia de WSL se apaga sola tras la salida del último proceso).
+- Git Bash es un entorno msys2, con diferencias respecto al comportamiento Linux de WSL (mapeo de rutas, disponibilidad de paquetes).
+- El backend MSYS2 requiere MSYS2 instalado localmente (por defecto `C:\msys64`); sin instalación `shell` informa `backend unavailable`, y con `msys2Path` se puede indicar una ubicación personalizada. El orden de candidatos siempre es `bash.exe` primero y `msys2.exe` de reserva — con stdio por tubería `msys2.exe` devuelve silenciosamente cero bytes y solo sirve como último recurso.
+- Este plugin registra sus herramientas únicamente en la plataforma `win32`.
+
+## Pruebas
+
+```powershell
+cd D:\workspace\projects\dsh-bash-terminal-ts
+npm install          # instalar las dependencias (typescript incluido)
+npm run build        # compilación tsc de src/*.ts → lib/*.js; client.tsx → lib/client.js + dist/client.js; test/*.ts → test-dist/
+npm test             # node test-dist/unit.js → apply.js → client.js → terminal.js
+```
+
+El código fuente está en TypeScript (`strict` + `noUncheckedIndexedAccess`); los artefactos de compilación `lib/` y `dist/` se suben al repositorio y DSH carga directamente `lib/index.js`, listo para usar sin instalación.