La bibliothèque de pièces prêtes à l'emploi

Usage: sovrium library list [--kind <kind>] [--category <c>] [--format md|json]
       sovrium library search <query> [--limit <n>]
       sovrium library show <id>
       sovrium library add <id> [--set key=value]... [--as <name>] [--into <config>] [--dry-run] [--no-wire]
       sovrium library add <provider>/<operation> [--dry-run]
       sovrium library add <provider> --tag <group> | --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.

Chaque entrée a un article dans ce manuel, sous la section library — sovrium docs library les liste, et sovrium docs search <provider> 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 <id> 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

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/<kind>/<name>.yaml à côté de votre configuration, en l'ouvrant par une ligne # sovrium-library: <id>@<version> 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/<kind>/<name>.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=<la vôtre> (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 <name> 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/<kind>/<name>.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-<provider>, liste chaque opération, avec un titre par groupe.

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 <group> 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.