# 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) | [PortuguĂȘs](README.pt.md) · CommunautĂ© : [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 DSH (DeepSeek Harness) : un outil `shell` qui exĂ©cute de maniĂšre unifiĂ©e sous Windows les commandes de **quatre** terminaux — **PowerShell / Git Bash / MSYS2 / WSL**. > **Ce dĂ©pĂŽt est une réécriture TypeScript de `MAXeaglet/dsh-bash-terminal`**, avec une prise en charge fonctionnelle de MSYS2/MINGW64. Les lignes de compatibilitĂ© sont dĂ©coupĂ©es par segment de version de l'hĂŽte DSH ; toutes les lignes partagent le nom de paquet `dsh-bash-terminal-ts` et se distinguent par un dist-tag npm : > > | Segment DSH | Branche | Version du plugin | dist-tag npm | > |--------|------|----------|--------------| > | `0.1.0-rc.2 – 0.2.1-rc.5` (Ă©numĂ©ration exacte de 20 versions) | `main` (cette branche, tronc inter-versions) | 0.8.x | `latest` | > | `>=0.2.0-rc.1 <0.2.1-0` | `compat/0.2.0` (historique, gelĂ©e) | 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` (historique, gelĂ©e) | ≀ 0.5.2 | `dsh-0.1.5` | > | 0.1.2-alpha.1 – 0.1.2-rc.x | premiers commits `main` (gelĂ©s au tag) | ≀ 0.4.2 | `dsh-0.1.2` | > > Choisissez la ligne correspondant Ă  votre version de DSH ; les sĂ©ries de versions ne se chevauchent pas, une installation avec `^` ne peut donc pas rĂ©soudre d'une ligne Ă  l'autre. | Backend | ExĂ©cution rĂ©elle | Syntaxe / chemins | Variables d'environnement | |------|----------|-------------|----------| | `powershell` (par dĂ©faut) | `pwsh -NoLogo -NoProfile -NonInteractive -Command ` | PowerShell ; `C:\...` | `$env:NAME` | | `gitbash` | `bash -lc ` du Git for Windows | POSIX ; `/d/workspace` ; PATH incluant `/usr/bin` et `/mingw64/bin` | `$NAME` | | `msys2` | `bash -lc ` MSYS2 (`C:\msys64\usr\bin\bash.exe`) | POSIX ; `/c/...` ; PATH incluant `/usr/bin` et `/mingw64/bin` (gcc / make) | `$NAME` (injection automatique de `MSYSTEM=MINGW64`) | | `wsl` | `wsl [-d ] -e bash -lc ` | Linux ; `/mnt/d/...` | `$NAME` (via WSLENV) | Chaque appel dĂ©marre un shell entiĂšrement neuf : **aucun Ă©tat n'est conservĂ©** (cwd / variables / alias) — passez `workdir` au lieu d'utiliser `cd`. ## Aperçu de l'interface La ligne « Terminal par dĂ©faut » dans ParamĂštres → GĂ©nĂ©ral : l'utilisateur choisit entre PowerShell / Git Bash / MSYS2 / WSL, et l'outil `shell` s'exĂ©cute strictement selon ce rĂ©glage, sans que le modĂšle puisse le contourner : ![Ligne de rĂ©glage du terminal par dĂ©faut](assets/shells.png) ## Points de conception - **Le terminal est dĂ©cidĂ© par l'utilisateur, l'IA ne peut pas le changer** : la page de rĂ©glages de l'UI Web (ParamĂštres → GĂ©nĂ©ral) affiche une liste dĂ©roulante « Terminal par dĂ©faut » (PowerShell / Git Bash / MSYS2 / WSL) ; l'outil `shell` utilise toujours exclusivement ce rĂ©glage et n'expose aucun paramĂštre de terminal au modĂšle. Le rĂ©glage est persistĂ© via le systĂšme de settings de DSH (settings.yaml). - **N'occupe pas le point d'extension `ctx.shell`** : l'outil `pwsh` sandboxĂ© fourni avec DSH reste disponible tel quel ; l'outil `shell` de ce plugin constitue un point d'entrĂ©e multi-terminal **supplĂ©mentaire**. - Les processus sont dĂ©rivĂ©s via le seam partagĂ© `ctx.subprocess` : arrĂȘt de l'arborescence de processus (`taskkill /T` sous Windows), SIGTERM → grĂące → SIGKILL, fichiers de spill de sortie — comportement identique Ă  celui des outils officiels `dsh-tool-bash` / `dsh-tool-pwsh`. - Les tĂąches d'arriĂšre-plan sont enregistrĂ©es dans le registre gĂ©nĂ©rique `jobs`, avec prise en charge de `run_in_background` / `job_output` / `job_kill`. - La ligne « Terminal par dĂ©faut » de la page de rĂ©glages frontale est une Ă©numĂ©ration (automatiquement rendue en liste dĂ©roulante par l'UI) ; Ă  chaque appel, le modĂšle s'exĂ©cute selon ce rĂ©glage et ne peut pas changer de terminal de son propre chef. ## Installation (profil web) ### Installation standard (aprĂšs publication npm, mĂ©canisme officiel de bundle) Le plugin embarque le manifeste officiel `dsh.bundle` (`cordis.patch.yml` dans le paquet) ; dĂšs qu'un profil liste ce paquet, DSH **applique automatiquement le montage**, sans qu'il soit nĂ©cessaire de modifier la configuration du profil Ă  la main : ```powershell # 1. Installer le paquet du plugin npm install -g dsh-bash-terminal-ts dsh plugin --profile web add dsh-bash-terminal-ts # ajout automatique aux bundles du profil et application du patch # 2. Patcher la liste blanche des rĂ©glages DSH (limitation DSH, voir l'explication ci-dessous) powershell -ExecutionPolicy Bypass -File install.ps1 install # 3. RedĂ©marrer dsh web ``` > VĂ©rifiĂ© en pratique avec un profil temporaire : `bundles: [dsh-bash-terminal-ts]` → l'entrĂ©e `tool-bash-terminal` apparaĂźt automatiquement dans le dump-config. ### Installation pour dĂ©veloppement local (junction, effet immĂ©diat des modifications du code source) ```powershell # 1. Lier le paquet du plugin aux node_modules du profil (junction, les modifications du code source prennent effet immĂ©diatement) $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. Permettre au plugin de rĂ©soudre les dĂ©pendances @deepseek-ai/* (junction vers l'arbre de dĂ©pendances du profil ; le plugin et l'hĂŽte partagent la mĂȘme instance des modules) 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. Laisser le profil monter le plugin via le bundle officiel (install.ps1 install le fait automatiquement ; Ă©quivaut Ă  ajouter "dsh-bash-terminal-ts" Ă  dsh.profile.bundles) # 4. (uniquement aprĂšs modification du code front-end) reconstruire le bundle client : # cd D:\workspace\projects\dsh-bash-terminal-ts && node scripts/build-client.mjs # 5. RedĂ©marrer dsh web ``` > ⚠ **N'exĂ©cutez pas `npm install` dans ce projet** : cela supprimerait la junction de l'Ă©tape 2 ci-dessus et installerait pour le plugin une copie **indĂ©pendante** de > `@deepseek-ai/*` — le plugin et l'hĂŽte ne partageraient alors plus les instances de modules, et aprĂšs une montĂ©e de version de l'hĂŽte, le plugin resterait bloquĂ© sur l'ancienne API > (ce projet s'est ainsi retrouvĂ© bloquĂ© sur 0.1.0-rc.6). Pour ne rafraĂźchir que le lock, utilisez `npm install --package-lock-only`. > **CompatibilitĂ©** : exige DSH ≄ **0.1.7-rc.1** (ligne `compat/0.1.7`) ou ≄ **0.2.0-rc.1** (ligne `compat/0.2.0`, cette branche). > Contexte historique : en 0.1.5, `@deepseek-ai/dsh-client-runtime` dans la table des modules client a Ă©tĂ© renommĂ© `@deepseek-ai/dsh-client-store` et n'est rĂ©solu que par correspondance exacte du nom nu ; les anciens bundles Ă©chouent sur le nouvel hĂŽte avec > `Failed to load plugins` / `require(...) missed the module table`. > > Par ailleurs : depuis 0.1.5, la surface de rĂ©glages Web repose sur l'Ă©numĂ©ration dynamique `settings.describe()` et **n'a plus de liste blanche de namespaces** > (`settings-not-exposed` n'existe plus) ; le patch de liste blanche prĂ©sent dans `install.ps1` n'est qu'un vestige historique, il peut ĂȘtre ignorĂ©. > Il n'est dĂ©sormais plus nĂ©cessaire de modifier manuellement le `cordis.patch.yml` du profil : le paquet du plugin embarque son propre `dsh.bundle.patch` (`cordis.patch.yml` dans le paquet) ; dĂšs que `dsh-bash-terminal-ts` figure dans le `dsh.profile.bundles` du profil, DSH monte automatiquement le plugin. VĂ©rifier l'arbre combinĂ© (sans redĂ©marrage) : ```powershell node "$env:APPDATA\nvm\\node_modules\@deepseek-ai\dsh\lib\bin.js" --profile web --dump-config | Select-String dsh-bash-terminal-ts ``` ## Utilisation **L'utilisateur choisit le terminal par dĂ©faut dans l'UI Web** : ouvrez les paramĂštres (roue dentĂ©e) → GĂ©nĂ©ral → liste dĂ©roulante « Terminal par dĂ©faut », puis choisissez l'un des terminaux PowerShell / Git Bash / MSYS2 / WSL. Le changement prend effet immĂ©diatement et est persistĂ©. Lorsque le modĂšle voit l'outil `shell`, il l'emploie automatiquement avec le terminal que vous avez choisi (l'outil n'expose pas de paramĂštre de terminal ; le modĂšle ne peut pas changer votre choix) : - Terminal par dĂ©faut = Git Bash : `shell(command: "git status")` passe par Git Bash - Terminal par dĂ©faut = MSYS2 : `shell(command: "gcc --version")` passe par MSYS2 (environnement MINGW64, gcc et make de `/mingw64/bin` disponibles) - Terminal par dĂ©faut = WSL : `shell(command: "ls -la /mnt/d/workspace")` passe par WSL ; `distro: "Ubuntu"` permet de prĂ©ciser la distribution - Terminal par dĂ©faut = PowerShell : `shell(command: "Get-Process node")` passe par PowerShell ## Exemples d'utilisation pour le modĂšle - Commande ponctuelle (terminal par dĂ©faut) : `shell(command: "git status", description: "voir l'Ă©tat git")` - État conservĂ© d'un tour Ă  l'autre (interactif) : `terminal(action: "open")` → noter le `sessionId` → `terminal(action: "send", sessionId, input: "cd /d/project\n")` → `terminal(action: "send", sessionId, input: "npm run dev\n")` → `terminal(action: "close", sessionId)` - Interrompre un programme en cours d'exĂ©cution : `terminal(action: "signal", sessionId, signal: "SIGINT")` - Consulter les sessions actives : `terminal(action: "list")` - Escalade aprĂšs un refus du bac Ă  sable : `shell(command: ..., sandbox_permissions: "workspace-write", justification: "...")` ## Configuration **RĂ©glages de l'UI Web** (recommandĂ©) : ParamĂštres → GĂ©nĂ©ral → « Terminal par dĂ©faut ». Le `config` de la ligne du plugin (surcharge les valeurs par dĂ©faut et sert de base de composition pour les rĂ©glages) : | ClĂ© | Par dĂ©faut | Description | |----|------|------| | `defaultShell` | `powershell` | Backend utilisĂ© lorsque les rĂ©glages ne surchargent pas | | `timeoutMs` | 120000 | DĂ©lai d'expiration par dĂ©faut | | `maxTimeoutMs` | 600000 | Plafond du timeoutMs de l'appelant | | `pwshPath` | dĂ©tection automatique | Chemin fixe de pwsh.exe | | `gitBashPath` | dĂ©tection automatique | Chemin fixe de git bash.exe | | `msys2Path` | dĂ©tection automatique (`C:\msys64\usr\bin\bash.exe` en prioritĂ©, repli sur `msys2.exe`) | Chemin fixe de MSYS2 bash.exe | | `wslPath` | dĂ©tection automatique | Chemin fixe de wsl.exe | ## Publication (npm) Le compte npm a la vĂ©rification 2FA activĂ©e pour la publication ; un code Ă  usage unique est requis : ```powershell cd D:\workspace\projects\dsh-bash-terminal-ts npm publish --otp # le code provient de votre authentificateur ``` Avant de publier, faites un `npm pack --dry-run` pour vĂ©rifier le contenu, puis lancez `npm run build` pour tout reconstruire (compilation serveur tsc + bundle client + compilation des tests). ## DĂ©sinstallation ExĂ©cutez simplement : ```powershell powershell -ExecutionPolicy Bypass -File install.ps1 uninstall ``` Cette commande supprime les junctions, restaure la liste blanche des rĂ©glages, nettoie les blocs de montage `cordis.patch.yml` laissĂ©s par les anciennes versions et retire `dsh-bash-terminal-ts` du `dsh.profile.bundles`. RedĂ©marrez ensuite dsh web. En cas de dĂ©sinstallation manuelle, outre la suppression de `node_modules\dsh-bash-terminal-ts`, pensez Ă©galement Ă  retirer `dsh-bash-terminal-ts` du `dsh.profile.bundles` du `package.json` du profil. ## Terminal interactif (outil `terminal`) L'outil `terminal` fournit des **sessions interactives persistantes** sur le seam PTY (node-pty ; sous Windows, l'inspecteur de processus du `spawnTerminal` amont ne prenant en charge que POSIX, `lib/terminal.js` se connecte directement Ă  node-pty ; hors Windows, le `ctx.subprocess.spawnTerminal` officiel reste utilisĂ©) : - `action: open` dĂ©marre une vĂ©ritable session de terminal (selon votre terminal par dĂ©faut rĂ©glĂ© ; pour wsl, `distro` peut ĂȘtre prĂ©cisĂ©) et renvoie un `sessionId` - `action: send` Ă©crit l'entrĂ©e et lit la nouvelle sortie ; `action: read` lit sans Ă©crire ; `action: signal` envoie un signal au groupe de processus de premier plan (SIGINT = Ctrl+C) - `action: close` met fin Ă  la session - **L'Ă©tat de la session persiste entre les appels** (cwd / variables / alias), idĂ©al pour les REPL, ssh et les CLI interactifs - `send` attend la stabilisation de la sortie (300 ms de silence, plafond 5 s) et renvoie la **rĂ©ponse complĂšte** ; au-delĂ  de 1 Mo de sortie, un avertissement `truncated` est Ă©mis - L'entrĂ©e se termine par `\\n` (ou \\r) pour matĂ©rialiser la touche EntrĂ©e ## Bac Ă  sable (intĂ©gration au mĂ©canisme officiel) L'outil `shell` emprunte le seam officiel de bac Ă  sable de DSH (`ctx.sandboxPolicy` + `ctx.sandbox`) : - À chaque appel, la politique de bac Ă  sable courante est rĂ©solue ; les sessions `danger-full-access` s'exĂ©cutent directement (sans enveloppement). - Le backend PowerShell enveloppe argv via `ctx.sandbox.confine` — sĂ©mantique **fail-closed** identique Ă  celle des exĂ©cuteurs officiels : si le mode restreint est demandĂ© alors qu'aucun backend n'est disponible, une `SandboxUnavailableError` est levĂ©e, refusant toute exĂ©cution nue. - Le backend Git Bash n'est pas enveloppĂ© : le runner Ă  jeton restreint ACL Windows de DSH est incompatible avec Cygwin/MSYS2 (bash s'arrĂȘte dĂšs le dĂ©marrage avec l'erreur Win32 5 de `CreateFileMapping`) ; Git Bash s'exĂ©cute donc, mĂȘme en mode restreint, sans enveloppement sandbox ; le rĂ©sultat rapporte `enforcement: gitbash-unconfined`. - Le backend MSYS2 n'est pas enveloppĂ© non plus (mĂȘme incompatibilitĂ© d'exĂ©cution Cygwin/MSYS2) ; le rĂ©sultat rapporte `enforcement: msys2-unconfined`. - Le backend WSL n'est pas enveloppĂ© : la VM Linux indĂ©pendante de WSL constitue en soi l'isolation (le rĂ©sultat rapporte `enforcement: wsl-isolation`). - En cas de refus par le bac Ă  sable en mode restreint, le rĂ©sultat porte le marqueur officiel `[sandbox: file access denied under mode]` ainsi que l'indice d'escalade du mĂȘme tour ; le modĂšle peut dĂ©clencher une escalade Ă  l'aide de `sandbox_permissions` + `justification` (approbation de l'utilisateur via `ctx.approval`), exactement comme les outils officiels bash/pwsh. - Remarque : lorsque le runner ACL Windows de DSH est disponible, le mode restreint de PowerShell est enveloppĂ© par son intermĂ©diaire ; Git Bash et MSYS2 restent non enveloppĂ©s en raison de l'incompatibilitĂ© Cygwin/MSYS2. ## ⚠ Note de sĂ©curitĂ© En mode restreint, l'outil `shell` : PowerShell est enveloppĂ© via `ctx.sandbox.confine` (fail-closed) ; Git Bash et MSYS2 ne sont **pas enveloppĂ©s** en raison de l'incompatibilitĂ© entre Cygwin/MSYS2 et les jetons restreints ACL Windows (mĂȘmes privilĂšges que le processus dsh) ; WSL n'est pas enveloppĂ© grĂące Ă  sa VM Linux indĂ©pendante. Il s'agit d'un **point d'entrĂ©e multi-terminal supplĂ©mentaire** qui ne bĂ©nĂ©ficie pas des restrictions ConstrainedLanguage de l'outil officiel `pwsh`. Les outils de manipulation de fichiers de DSH (read/write/edit) restent soumis au bac Ă  sable de fichiers. N'utilisez-le que dans des sessions de confiance ; pour un PowerShell protĂ©gĂ© par le bac Ă  sable, continuez d'utiliser l'outil officiel `pwsh`. ## Limitations connues du terminal interactif (ConPTY) - **PowerShell 5.1 ne peut pas dĂ©marrer dans un ConPTY** (0x8009001d) — pour un PowerShell interactif, installez [PowerShell 7](https://github.com/PowerShell/PowerShell/releases) (les commandes ponctuelles ne sont pas affectĂ©es). - **Le mode interactif de wsl.exe peut dĂ©clencher une erreur RPC du service WSL sous ConPTY** (0x8007072c, intermittent) — les commandes ponctuelles `wsl -e bash -lc ...` fonctionnent normalement ; pour les sessions interactives, prĂ©fĂ©rez Windows Terminal / un terminal WSL, ou rĂ©essayez. - **node-pty n'accepte pas les signaux nommĂ©s sous Windows** : `SIGINT` de `signal` est traduit en Ctrl+C (`\x03`) ; les autres signaux (`SIGTERM` / `SIGKILL` / `SIGTSTP` / `SIGHUP`) se dĂ©gradent en simple terminaison de session. - Les sessions interactives Git Bash fonctionnent parfaitement. ## Limitations connues - Les processus d'arriĂšre-plan WSL peuvent subsister briĂšvement dans la distribution aprĂšs un dĂ©passement de dĂ©lai ou une interruption (l'instance WSL s'Ă©teint automatiquement aprĂšs la sortie du dernier processus). - Git Bash est un environnement msys2, avec des diffĂ©rences par rapport au comportement Linux de WSL (mappage des chemins, disponibilitĂ© des paquets). - Le backend MSYS2 nĂ©cessite une installation locale de MSYS2 (`C:\msys64` par dĂ©faut) ; sans installation, `shell` signale `backend unavailable`, et `msys2Path` permet de prĂ©ciser un emplacement personnalisĂ©. L'ordre des candidats reste toujours `bash.exe` en prioritĂ© et `msys2.exe` en repli — avec un stdio en pipeline, `msys2.exe` renvoie silencieusement zĂ©ro octet et ne doit servir qu'en dernier recours. - Ce plugin n'enregistre ses outils que sur la plateforme `win32`. ## Tests ```powershell cd D:\workspace\projects\dsh-bash-terminal-ts npm install # installer les dĂ©pendances (typescript inclus) npm run build # compilation 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 ``` Le code source est en TypeScript (`strict` + `noUncheckedIndexedAccess`) ; les produits de compilation `lib/` et `dist/` sont commitĂ©s avec le dĂ©pĂŽt, et DSH se charge directement depuis `lib/index.js`, utilisable sans installation.