# La bibliothèque de pièces prêtes à l'emploi ```text Usage: sovrium library list [--kind ] [--category ] [--format md|json] sovrium library search [--limit ] sovrium library show sovrium library add [--set key=value]... [--as ] [--into ] [--dry-run] [--no-wire] sovrium library add / [--dry-run] sovrium library add --tag | --all [--yes] [--dry-run] ``` Le chemin le plus rapide vers une bonne configuration consiste à partir d'une pièce que quelqu'un a déjà bien écrite : une section d'accroche, une connexion avec le bon en-tête d'authentification, une automatisation qui envoie chaque inscription à votre outil d'e-mailing. La bibliothèque est ce catalogue, vérifié par rapport au binaire qui l'embarque, et consultable hors ligne. | Type | S'installe dans | Exemple | | ------------ | --------------- | ---------------------- | | `block` | `components` | `block/hero-centered` | | `connection` | `connections` | `connection/qonto` | | `recipe` | `automations` | `recipe/form-to-brevo` | Chaque entrée a un article dans ce manuel, sous la section `library` — `sovrium docs library` les liste, et `sovrium docs search ` en trouve une par son nom. ## Trouver une entrée `sovrium library list` affiche chaque entrée avec son type, sa catégorie et son titre ; `--kind` restreint la liste à un seul type. `sovrium library search brevo` classe les entrées correspondant à un fournisseur, à une étiquette ou à un mot du titre, la meilleure en premier. `sovrium library show ` affiche une entrée en entier : ce qu'elle installe et où, ses paramètres et leurs valeurs par défaut, les variables d'environnement qu'elle lit, ce qu'elle requiert, le lien vers la documentation du fournisseur et la date à laquelle l'entrée a été vérifiée pour la dernière fois par rapport à celle-ci. Ajoutez `--format json` à l'une de ces trois commandes pour obtenir un tableau ou un objet exploitable par une machine. ## Installer une entrée ```bash sovrium library add block/hero-centered --set headline="Handmade bindings that last" ``` La commande trouve votre configuration comme le fait `sovrium start` — `app.yaml`, `app.yml` ou `app.ts` dans le répertoire courant — ou utilise celle que nomme `--into`, qui doit se trouver à l'intérieur du répertoire courant. Ensuite, elle : 1. **Écrit le fragment** dans `library//.yaml` à côté de votre configuration, en l'ouvrant par une ligne `# sovrium-library: @` pour que vous sachiez toujours d'où il vient. Le fichier vous appartient : modifiez-le comme n'importe quelle autre partie de votre configuration. 2. **Le raccorde** en ajoutant exactement une ligne, `- $ref: ./library//.yaml`, à la fin de la liste `components`, `connections` ou `automations` — en créant la clé à la fin du fichier lorsqu'elle manque. Rien d'autre ne bouge dans `app.yaml` : les commentaires, l'ordre et les guillemets restent tels que vous les avez écrits. 3. **Liste les secrets** que lit une entrée en ajoutant leurs noms — jamais une valeur — à `.env.example`. `.env` n'est jamais lu ni écrit. Une recette qui a besoin d'une connexion l'installe aussi, sauf si votre configuration en définit déjà une de ce nom. Une entrée qui lit des données se lie à une table que votre configuration possède déjà : `library show` liste la table et les champs qu'elle attend, `--set table=` (et tout paramètre de champ) la relie à une autre, et `add` refuse — sans rien écrire — lorsque la table ou un champ manque. La bibliothèque ne crée jamais de table. `--set key=value` renseigne un paramètre que déclare l'entrée, et `--as ` l'installe sous un autre nom. `--dry-run` affiche les fichiers et la ligne qui seraient écrits, sans rien écrire. `--no-wire` écrit le fragment et affiche la ligne, à vous de la placer. ## Ce qu'elle refuse, et ce qu'elle laisse intact La configuration est décodée avant toute modification. Si elle n'était pas valide au départ, rien n'est écrit et le problème existant est signalé comme le signale `sovrium validate` — corrigez-le d'abord. La configuration modifiée est ensuite décodée à nouveau, avec le nouveau fragment en place, avant qu'un seul octet n'atteigne le disque ; une modification qui ne serait pas valide est refusée en bloc. Elle n'écrase jamais un fragment que vous avez modifié, et elle refuse une entrée dont votre configuration utilise déjà le nom — en indiquant `--as` comme porte de sortie. Ajouter une entrée déjà installée et raccordée ne change rien, et la commande le dit. Lorsque la clé cible est écrite sous une forme qu'une seule ligne ne peut pas étendre sans risque — `components: []`, un `$ref` vers un autre fichier, une ancre —, le fragment est tout de même écrit, votre configuration reste exactement telle qu'elle était, et la ligne à ajouter est affichée avec la clé sous laquelle elle doit aller. Une configuration TypeScript n'est jamais modifiée : le fragment est écrit sous la forme `library//.ts` et l'`import` à coller est affiché. ## Installer les opérations d'une API une par une Plusieurs connexions sont livrées avec les points de terminaison de l'API de leur fournisseur, générés à partir de la description d'API publiée par l'éditeur lui-même : `sovrium library search campaign` liste celles qui correspondent sous leur fournisseur, vingt au plus sauf si `--limit` demande un autre nombre, et `sovrium library show lemlist/get-campaigns` en affiche une avec sa méthode, son chemin, ses paramètres et la documentation de l'éditeur. L'article de la connexion, `sovrium docs library/connection-`, liste chaque opération, avec un titre par groupe. ```bash sovrium library add lemlist/get-campaigns ``` Cette commande déclare l'opération, exactement telle que la bibliothèque la livre, sous `operations` dans `library/connection/lemlist.yaml`, en installant et en raccordant d'abord la connexion lemlist lorsque votre configuration ne l'a pas. Une deuxième opération est ajoutée après celles déjà présentes ; une opération déjà déclarée ne change rien. `--tag ` déclare un groupe entier — `sovrium library add lemlist --tag campaigns` — et un groupe inconnu est refusé avec la liste des groupes existants. `--all` déclare toutes les opérations du fournisseur, et demande `--yes` lorsqu'il y en a plus de cinquante. `--dry-run` affiche les opérations qui seraient ajoutées, sans rien écrire. Le fragment de connexion n'est réécrit que tant qu'il est encore exactement ce que la bibliothèque a écrit. Une fois que vous l'avez modifié, il est laissé tel quel, octet pour octet, et les opérations sont affichées pour que vous les colliez vous-même sous `operations`. L'application entière est décodée avec les nouvelles opérations en place avant que quoi que ce soit ne soit écrit. La bibliothèque n'exécute jamais rien à l'installation, n'accède jamais au réseau et n'est pas chargée au démarrage de votre application.