Recettes

Les modifications les plus courantes, pas à pas. Chacune renvoie à la page qui en explique le pourquoi. Dans tous les cas, finir par npm run lint, npm test, npm run build, une vérification dans le navigateur, et la documentation dans le même commit.

Ajouter un texte à l'interface

1. Ajouter la clé dans src/i18n/messages/en.ts, à sa place dans l'arborescence (fileExplorer.…, git.dialogs.…).
2. L'ajouter dans les neuf autres langues (fr, de, es, it, pt, nl, pl, ru, uk), avec leurs formes de pluriel si le message a un count.
3. L'utiliser : t('ma.cle', { name }) dans un service ou un store, i18nStore.t(…) dans un composant.

Le typage refuse une clé inexistante ; tests/interface/i18n.spec.ts refuse une langue incomplète. Voir Langues de l'interface.

Ajouter une action de l'IDE (menu, palette, raccourci)

1. Déclarer une Command dans une source de src/commands/catalog.ts : id stable, category, title: () => t('commands.…'), icon, éventuellement keybinding (Mod-k), enabled(), checked(), et run(), qui appelle un store ou un composable.
2. Pour la faire figurer dans un menu, ajouter son id dans src/commands/menus.ts.
3. Si elle concerne Git, la mettre dans gitCommands : elle disparaîtra quand la page hôte désactive Git.

tests/interface/commands.spec.ts vérifie que chaque entrée de menu existe et qu'aucun raccourci n'est attribué deux fois. Voir Commandes.

Ajouter une commande au terminal

1. Écrire un ShellCommand dans le module de sa famille (src/services/terminal/fs/, git/, python/, system.ts) :

   export const hello: ShellCommand = {
     name: 'hello',
     group: 'system',
     usage: 'terminal.cmd.hello.usage',
     summary: 'terminal.cmd.hello.summary',
     run: (args, ctx) => stdout(t('terminal.hello', { dir: ctx.ws.relative(ctx.cwd) })),
   }

2. L'ajouter au registre COMMANDS (src/services/terminal/index.ts) : l'aide et la complétion la proposent seules.

3. Ses textes (usage, summary, sorties) dans les dix langues.

4. Un test dans tests/terminal/ avec createShell() (tests/helpers/terminal.ts).

La commande ne touche que le TerminalContext (ctx.ws, ctx.cwd, ctx.io…), jamais un store. Voir Terminal.

Ajouter un langage

1. Créer src/languages/<langage>.ts qui exporte un LanguageSupport (extensions, coloration, et ce qu'il sait faire : exécution, analyse, formatage, plan).
2. L'ajouter à LANGUAGES (src/languages/index.ts).
3. S'il s'exécute par un noyau Basthon : ajouter le paquet @basthon/kernel-<x> (même version que les autres), son entrée dans KERNEL_CLASSES (src/services/kernels.ts) et dans vite-plugin-basthon.ts.
4. Son icône dans src/utils/fileIcons.ts si besoin.

Voir Langages.

Modifier ce qui s'écrit dans le workspace

1. Écrire par vfs (ou workspace.fs), ou par gitService pour une opération Git.
2. Plusieurs écritures : les envelopper dans vfs.batch (ou workspace.batch si Git est concerné).
3. Ne rien rafraîchir à la main ; si un nouvel état doit suivre le workspace, l'abonner dans son store : onScopeDispose(vfs.onChange(…)).
4. Si isomorphic-git écrit des fichiers de travail hors de gitService, appeler vfs.notifyChange().

Voir Stores et synchronisation.

Faire évoluer le format des liens de partage

Le format d'instantané est versionné (SNAPSHOT_VERSION, src/services/project/snapshot.ts).

1. Augmenter SNAPSHOT_VERSION et décrire le nouveau format dans ProjectSnapshot.
2. Adapter isProjectSnapshot ; pour garder les anciens liens, convertir l'ancienne version plutôt que de l'accepter telle quelle.
3. Mettre à jour tests/project/project-snapshot.spec.ts et Le projet et ses formats.

Ajouter une option réglable par la page hôte

1. L'ajouter à EmbeddingOptions, DEFAULT_EMBEDDING_OPTIONS et parseOptions (src/services/embedding.ts).
2. L'exposer dans le store embedding, puis l'appliquer par abonnement réactif dans les stores concernés.
3. La tester dans tests/interface/embedding.spec.ts et la décrire dans Intégration dans une page hôte : c'est le contrat avec Capytale.

Ajouter une extension intégrée

1. Déclarer son identifiant dans ExtensionId (src/services/extensions/types.ts).
2. Définir sa fiche dans BUILTIN_EXTENSIONS (src/services/extensions/index.ts) : id, nameKey, descriptionKey, author, version, icon (icône Lucide ou logo SVG officiel), et son activation par défaut (defaultEnabled: boolean).
3. Ajouter ses libellés traduits dans les dix langues (src/i18n/messages/).
4. Conditionner l'apparition de ses commandes, boutons ou panneaux avec extensionsStore.isEnabled(id).
5. Tester son activation, sa persistance et ses effets dans tests/interface/extensions.spec.ts.

Ajouter un composant

1. Le ranger dans le dossier de sa zone (layout/, sidebar/, editor/, console/, common/) ; s'il grossit, ses sous-composants vont dans un dossier à son nom.
2. Il lit les stores et appelle leurs actions lui-même ; ses textes passent par i18nStore.t.
3. Fenêtre modale : BaseDialog. Menu : MenuButton. Arbre : useTreeNavigation. Poignée : useSeparator. Champ qui capture Tab : useTabEscape.
4. Couleurs de texte par les jetons text-vscode-* ; icône seule en aria-hidden, avec un aria-label sur son bouton.
5. L'ajouter à l'audit de tests/accessibility/accessibility-axe.spec.ts, et ses touches à keyboard-navigation.spec.ts.

Voir Accessibilité et Interface et composants.

Enregistrer une préférence

Par src/utils/storage.ts (readPreference, readNumberPreference, readBooleanPreference, writePreference…), jamais localStorage : le stockage peut être absent ou refusé, et une valeur lue est validée (bornes, valeur par défaut). La préférence vit dans le store qui la concerne (layout, theme, i18n).

Mettre à jour Basthon

1. Changer la version de tous les paquets @basthon/* dans package.json (la même partout), puis npm install.
2. Lancer npm run test:e2e : seuls les tests de bout en bout exercent le vrai noyau.
3. Vérifier dans le navigateur un programme Python avec input(), une sortie turtle et matplotlib, un fichier SQL et un fichier OCaml.

Le dossier publié (basthon/<version>-<empreinte>/) change seul : les navigateurs téléchargent les nouveaux noyaux, et le service worker supprime l'ancien cache. Voir Intégration de Basthon.

Écrire un test

• Comportement de CapyCode (stores, services, composants) : Vitest, dans tests/<domaine>/, avec le faux noyau si l'exécution est en jeu.
• Comportement qui dépend du vrai Python (paquets, tracebacks, input()) : Playwright, dans tests/e2e/<domaine>/.
• Un commentaire en français en tête du fichier ; le README.md du dossier mis à jour.

Voir Tests.