| 📦 Turbo JS 91999d1 k33g 11h ago | 1 | # Référence : outils JavaScript |
| 2 | |
| 3 | > Description neutre de `.turbo-js/tools.toml`, du menu JavaScript, et de ce que fait l'exécution d'une commande. |
| 4 | |
| 5 | ## Fichier |
| 6 | |
| 7 | | Propriété | Valeur | |
| 8 | | --- | --- | |
| 9 | | Chemin | `./.turbo-js/tools.toml` | |
| 10 | | Recherche | Le répertoire courant seulement. Les répertoires parents ne sont **pas** parcourus. | |
| 11 | | Lecture | À chaque ouverture de l'un de ses menus, pour les entrées | |
| 12 | | Relecture | Dès que la taille ou la date de modification du fichier change, pour l'**ensemble** des menus | |
| 13 | | Fichier absent | Pas une erreur | |
| 14 | | Fichier illisible | Une erreur, affichée dans le menu | |
| 15 | | Fichier au niveau utilisateur | **Aucun.** Contrairement aux snippets, il n'y a pas de `~/.config/turbo-js/tools.toml`. | |
| 16 | |
| 17 | ## Format du fichier |
| 18 | |
| 19 | Une table `[[tool]]` par commande. |
| 20 | |
| 21 | | Clé | Type | Obligatoire | Description | |
| 22 | | --- | --- | --- | --- | |
| 23 | | `name` | chaîne | oui | Ce que le menu affiche. Peut porter une touche chaude entre tildes, comme `"~T~est"`. | |
| 24 | | `command` | chaîne | oui | La commande shell à lancer | |
| 25 | | `output` | chaîne | non | Où va sa sortie : `popup`, `terminal` ou `editor`. Absent signifie `popup`. | |
| 26 | | `menu` | chaîne | non | Dans quel menu elle apparaît. Absent signifie `JavaScript`. N'importe quel nom ; le menu est créé pour vous. Peut porter une touche chaude entre tildes. | |
| 27 | |
| 28 | `menu` n'est pas vérifié contre une liste, parce qu'il n'y a pas de liste : un nom qu'aucun autre outil n'utilise crée simplement un menu. Un outil sans `name`, sans `command`, ou dont l'`output` nomme quelque chose qui n'existe pas rend tout le fichier erroné. Un `output` inconnu est **refusé plutôt que corrigé** : `"termnial"` aurait sinon l'air d'avoir marché tout en envoyant la sortie ailleurs. |
| 29 | |
| 30 | ### Exemple |
| 31 | |
| 32 | ```toml |
| 33 | [[tool]] |
| 34 | name = "~T~est" |
| 35 | command = "node --test" |
| 36 | output = "popup" |
| 37 | |
| 38 | [[tool]] |
| 39 | name = "~E~cho" |
| 40 | command = "echo TADA" |
| 41 | output = "terminal" |
| 42 | menu = "Tools" |
| 43 | ``` |
| 44 | |
| 45 | ## Le fichier de départ |
| 46 | |
| 47 | **JavaScript ▸ Create tools file** écrit ces sept outils, dans cet ordre : |
| 48 | |
| 49 | | Nom | Commande | Sortie | Menu | |
| 50 | | --- | --- | --- | --- | |
| 51 | | `~I~nstall` | `npm install` | `popup` | JavaScript | |
| 52 | | `~F~ormat` | `npx prettier --write .` | `popup` | JavaScript | |
| 53 | | `~L~int` | `npx eslint .` | `popup` | JavaScript | |
| 54 | | `~T~est` | `node --test` | `popup` | JavaScript | |
| 55 | | `~R~un` | `node {{script, e.g. main.js}}` | `terminal` | JavaScript | |
| 56 | | `~S~tart` | `npm start` | `terminal` | JavaScript | |
| 57 | | `~E~cho` | `echo 🎉 tada!` | `terminal` | Tools | |
| 58 | |
| 59 | `Install` vient en premier parce que c'est la première chose qu'on lance dans un clone frais, et celle qui doit avoir tourné avant qu'aucune des autres ne puisse. L'un d'eux demande une valeur avant de s'exécuter — `Run`, parce qu'un projet Node n'a pas de point d'entrée unique que l'éditeur pourrait connaître — et un nomme un `menu` à lui. Ces deux fonctionnalités sont invisibles si le fichier de départ ne les montre pas. |
| 60 | |
| 61 | `Run` et `Start` reçoivent un terminal : un script peut lire le clavier, et `npm start` est d'habitude un serveur qu'il faut interrompre par `Ctrl-C`. `Format` et `Lint` passent par `npx`, qui lance le Prettier et l'ESLint propres au projet quand `package.json` en dépend et les télécharge dans un cache sinon ; ESLint 9 a besoin d'un `eslint.config.js` dans le projet. `Test` est le lanceur de Node lui-même, qui n'a besoin de rien d'installé : il exécute chaque fichier `*.test.js`, `*.spec.js` et `test/**/*.js` sous le répertoire courant. |
| 62 | |
| 63 | Il n'y a pas de `Build`, parce que JavaScript n'a pas d'étape de compilation. `node --check {{script}}` est la vérification de syntaxe qu'ajoute qui en veut une. |
| 64 | |
| 65 | Chaque outil nomme son `output`, y compris ceux qui nomment le défaut : la clé est la partie intéressante du format, et un fichier où elle apparaît une fois est un fichier où personne ne remarque qu'elle existe. |
| 66 | |
| 67 | L'entrée est grisée une fois que le projet a un fichier d'outils, elle ne peut donc pas en écraser un. Le fichier est écrit via un fichier temporaire dans le même répertoire, renommé en place. |
| 68 | |
| 69 | ## Le menu JavaScript |
| 70 | |
| 71 | Toujours sur la barre, qu'un fichier d'outils existe ou non. Sa touche chaude est `Alt-J`. |
| 72 | |
| 73 | | Entrée | Condition | |
| 74 | | --- | --- | |
| 75 | | Une ligne par outil sans `menu`, dans l'ordre du fichier | Le fichier en contient au moins un | |
| 76 | | `Cannot read tools`, grisé | Le fichier est présent mais illisible | |
| 77 | | `Create tools file` | Le projet n'a pas de fichier d'outils | |
| 78 | | `Open tools file` | Le projet en a un | |
| 79 | |
| 80 | ## Les menus qu'un outil demande |
| 81 | |
| 82 | Un `menu` nommant autre chose que `JavaScript` met un menu de ce nom sur la barre. |
| 83 | |
| 84 | | Propriété | Valeur | |
| 85 | | --- | --- | |
| 86 | | Position | Entre JavaScript et Help | |
| 87 | | Ordre | L'ordre dans lequel chaque nom apparaît pour la première fois dans le fichier | |
| 88 | | Entrées | Une ligne par outil nommant ce menu, dans l'ordre du fichier. Rien d'autre — `Create tools file` et `Open tools file` restent dans JavaScript. | |
| 89 | | Fichier illisible | Aucun menu du tout ; le menu JavaScript porte l'erreur | |
| 90 | | Pendant que l'éditeur tourne | Ajoutés, retirés et renommés au fil des changements du fichier, sans redémarrage | |
| 91 | |
| 92 | ### Touches chaudes |
| 93 | |
| 94 | Attribuées automatiquement, parce qu'un nom venu d'un fichier ne peut pas être vérifié à l'avance contre les menus fixes. |
| 95 | |
| 96 | | Cas | Résultat | |
| 97 | | --- | --- | |
| 98 | | Pas de tilde dans le nom | La première lettre qu'aucun autre menu n'a revendiquée est marquée. `Tools` devient `~T~ools` : `T` est libre. `Format` devient `For~m~at` : `F` est à File, `o` à Options, `r` à Run. | |
| 99 | | Des tildes nommant une lettre libre | Conservés tels quels. `Doc~k~er` répond à `Alt-K`. | |
| 100 | | Des tildes nommant une lettre prise | Abandonnés, et une lettre libre choisie à la place. `~F~oo` devient `F~o~o`. | |
| 101 | | Toutes les lettres prises | Pas de touche chaude. `F10` et la souris l'ouvrent toujours. | |
| 102 | |
| 103 | Les lettres que tiennent les menus propres de l'éditeur sont `F`, `E`, `S`, `R`, `C`, `O`, `W`, `N` (Snippets), `A` (Agent), `J` (JavaScript) et `H`. |
| 104 | |
| 105 | ## Exécuter une commande |
| 106 | |
| 107 | Commun à toutes les sorties : |
| 108 | |
| 109 | | Propriété | Valeur | |
| 110 | | --- | --- | |
| 111 | | Shell | `/bin/sh -c "<commande>"` sous Linux et macOS ; `cmd.exe /S /C "<commande>"` — le shell que nomme `%COMSPEC%` — sous Windows | |
| 112 | | Répertoire | Le répertoire dans lequel l'éditeur a été lancé | |
| 113 | | Sortie d'erreur | Fusionnée dans la sortie standard, dans l'ordre où la commande les a écrites | |
| 114 | |
| 115 | Passer par un shell signifie que les tubes, les globs, `&&` et `;` marchent tous, un outil peut donc être une séquence. Sous Windows le shell est cmd.exe, qui connaît `&&`, `|` et `>` mais ne développe pas les globs, et où `;` n'est pas un séparateur. |
| 116 | |
| 117 | ### `output = "popup"` |
| 118 | |
| 119 | | Propriété | Valeur | |
| 120 | | --- | --- | |
| 121 | | S'ouvre | Immédiatement, avant que la commande soit finie | |
| 122 | | Modal | Oui : rien d'autre dans l'éditeur n'est utilisable pendant qu'il est là | |
| 123 | | Se remplit | À mesure que la sortie arrive, en la suivant jusqu'à ce que vous remontiez | |
| 124 | | Titre pendant l'exécution | `<commande> — running` | |
| 125 | | Titre une fois fini | `<commande> — ok`, ou `<commande> — exit <n>` | |
| 126 | | Sortie vide, fini | Affiche `(no output)` | |
| 127 | | Sortie vide, en cours | N'affiche rien | |
| 128 | | Plafond de sortie | 10000 lignes ; au-delà les plus anciennes partent et une ligne `… n earlier lines dropped …` le dit | |
| 129 | |
| 130 | | Touche | Effet | |
| 131 | | --- | --- | |
| 132 | | `↑` `↓` `PgUp` `PgDn` `Home` `End` | Parcourir la sortie | |
| 133 | | Molette | Idem | |
| 134 | | `Échap`, `Entrée`, **Close** | Le fermer, **en arrêtant la commande** si elle tourne encore | |
| 135 | |
| 136 | Fermer arrête la commande parce qu'il n'y a pas d'autre moyen d'interrompre une commande dont la sortie n'est pas dans un terminal. |
| 137 | |
| 138 | ### `output = "terminal"` |
| 139 | |
| 140 | | Propriété | Valeur | |
| 141 | | --- | --- | |
| 142 | | Fenêtre | Une fenêtre de terminal à elle, titrée de la commande | |
| 143 | | Environnement | Celui de l'éditeur, avec `TERM` à `xterm-256color` | |
| 144 | | Après sa fin | La fenêtre reste, montrant sa sortie | |
| 145 | | Modal | Non : l'éditeur continue à côté | |
| 146 | |
| 147 | Comme c'est un vrai terminal, les couleurs, la pagination, `Ctrl-C` et la lecture du clavier marchent tous — les coches vertes de `node --test`, un script qui lit `process.stdin`, un serveur qui journalise jusqu'à ce qu'on l'interrompe. Voir [Fenêtres de terminal](terminal.md). |
| 148 | |
| 149 | Touches dans une fenêtre de terminal **terminée** : |
| 150 | |
| 151 | | Touche | Effet | |
| 152 | | --- | --- | |
| 153 | | `Shift-PgUp`, `Shift-PgDn` | Remonter dans la sortie | |
| 154 | | `Ctrl-W` | Fermer la fenêtre | |
| 155 | | Tout le reste | Atteint l'éditeur, pas le shell mort | |
| 156 | |
| 157 | ### `output = "editor"` |
| 158 | |
| 159 | | Propriété | Valeur | |
| 160 | | --- | --- | |
| 161 | | Affiche | Un popup pendant l'exécution, comme ci-dessus | |
| 162 | | À la fermeture du popup | Une fenêtre d'édition contenant la sortie, titrée de la commande | |
| 163 | | Remplie | Une fois, quand la commande est finie — pas au fil de l'eau | |
| 164 | | La fenêtre | Une fenêtre d'édition ordinaire sans nom de fichier : `Ctrl-F` la fouille, et `Save as` la conserve | |
| 165 | |
| 166 | ## Rechargement après une commande |
| 167 | |
| 168 | Quand une commande se termine, chaque fichier ouvert est considéré. |
| 169 | |
| 170 | | Le fichier | Ce qui se passe | |
| 171 | | --- | --- | |
| 172 | | Non modifié, et changé sur le disque | Relu ; sa syntaxe est redécidée et son titre rafraîchi | |
| 173 | | Non modifié, et inchangé sur le disque | Laissé tranquille, non compté | |
| 174 | | Avec des modifications non enregistrées | Laissé tranquille et compté comme ignoré | |
| 175 | | Jamais nommé | Laissé tranquille | |
| 176 | | Disparu du disque | Laissé tranquille | |
| 177 | |
| 178 | Le curseur reste où il était, ramené dans ce que le fichier contient désormais. L'historique d'annulation est jeté, parce qu'annuler au-delà d'un rechargement restaurerait un texte que le fichier n'a plus. |
| 179 | |
| 180 | L'arbre du projet est rafraîchi au même instant — c'est ainsi que `node_modules/` et `package-lock.json`, écrits par `npm install`, y apparaissent. |
| 181 | |
| 182 | | Barre d'état | Quand | |
| 183 | | --- | --- | |
| 184 | | `Running <commande>` | La fenêtre s'ouvre | |
| 185 | | `Reloaded 2 files` | Deux fichiers ont été relus, aucun ignoré | |
| 186 | | `Reloaded 2 files; 1 file with unsaved changes left alone` | Certains ont été ignorés | |
| 187 | | `Command finished; 1 file with unsaved changes left alone` | Rien n'a été relu, quelque chose a été ignoré | |
| 188 | |
| 189 | ## Erreurs |
| 190 | |
| 191 | | Message | Cause | |
| 192 | | --- | --- | |
| 193 | | `Cannot read tools` dans le menu | Le fichier est présent mais n'est pas du TOML valide, ou contient un outil sans nom ou sans commande | |
| 194 | | `Already there: .turbo-js/tools.toml` | Création dans un projet qui en a déjà un. Inatteignable depuis le menu, qui grise l'entrée ; toujours possible pour un appelant qui n'est pas un menu. | |
| 195 | | `This project has no .turbo-js/tools.toml yet.` | Ouverture dans un projet qui n'en a pas, de même | |
| 196 | | `Cannot tell which directory this is: …` | Le répertoire courant n'a pas pu être lu | |
| 197 | | `Terminal windows are not supported on this platform yet` | Lancer une commande demande un pseudo-terminal, que Linux, macOS et Windows possèdent ; voir [Fenêtres de terminal](terminal.md) | |
| 198 | |
| 199 | ## Demander une valeur |
| 200 | |
| 201 | Un `{{libellé}}` n'importe où dans une commande est une valeur que l'éditeur demande avant de l'exécuter, dans une boîte titrée du nom de l'outil. Le texte entre les accolades est ce que la boîte demande. |
| 202 | |
| 203 | | Écrit | Demandé | Substitué | |
| 204 | | --- | --- | --- | |
| 205 | | `{{script, e.g. main.js}}` | `script, e.g. main.js` | cité pour le shell | |
| 206 | | `{{arguments...}}` | `arguments` | tel quel | |
| 207 | |
| 208 | Une valeur est **citée pour le shell** par défaut, un chemin avec un espace reste donc un seul argument. Un `...` final dans les accolades la demande telle quelle, et c'est ainsi qu'un champ peut valoir plusieurs arguments. |
| 209 | |
| 210 | ```toml |
| 211 | [[tool]] |
| 212 | name = "Run with ~a~rguments" |
| 213 | command = "node main.js {{arguments...}}" |
| 214 | output = "terminal" |
| 215 | ``` |
| 216 | |
| 217 | | Règle | Comportement | |
| 218 | | --- | --- | |
| 219 | | Plusieurs champs | Une boîte, un champ chacun, dans l'ordre d'apparition dans la commande | |
| 220 | | Le même libellé deux fois | Un champ ; chaque occurrence reçoit ce qui y est tapé | |
| 221 | | Un libellé écrit des deux façons | Demandé une fois ; chaque occurrence honore ses propres accolades | |
| 222 | | Échap, ou Cancel | La commande ne s'exécute pas | |
| 223 | | Un champ laissé vide | Substitué par du vide — la commande émet sa propre plainte | |
| 224 | | Relancer l'outil | La boîte part de ce qui a été tapé la fois précédente, pour cette session seulement | |
| 225 | | Plus de champs qu'il n'en tient à l'écran | Refusé, avec un message disant combien tiennent | |
| 226 | |
| 227 | **Doubles accolades, pas simples.** `awk '{print $1}'` et `find . -exec rm {} +` sont des commandes ordinaires, et une syntaxe à accolades simples lirait la première comme une demande de valeur appelée `print $1`. |
| 228 | |
| 229 | Rien n'est écrit sur le disque. Une valeur que quelqu'un a tapée cet après-midi n'est pas une décision prise par le projet, elle ne va donc pas dans le répertoire propre du projet. |
| 230 | |
| 231 | ### Erreurs |
| 232 | |
| 233 | | Erreur | Cause | |
| 234 | | --- | --- | |
| 235 | | `tool "X": "{{script" is never closed` | Un `{{` ouvrant sans `}}` après lui | |
| 236 | | `tool "X": {{}} asks for a value but does not say what it is` | Un champ sans libellé, ou qui n'est que `...` | |
| 237 | |
| 238 | Les deux sont refusés à la lecture du fichier, un champ à moitié tapé n'atteint donc jamais le shell avec ses accolades. |
| 239 | |
| 240 | ## Voir aussi |
| 241 | |
| 242 | - [Lancer des commandes Node depuis l'éditeur](../how-to/run-node-commands.md) |
| 243 | - [Outils JavaScript](../explanation/javascript-tools.md) |
| 244 | - [Fenêtres de terminal](terminal.md) |