Libretto

Libretto est une boîte à outils pour construire des intégrations web robustes. Elle offre à votre agent de codage un navigateur en direct et une interface CLI économe en tokens pour :

• Inspecter des pages en direct avec un minimum de contexte
• Capturer le trafic réseau afin de rétro‑ingénierer les API d’un site
• Enregistrer les actions d’un utilisateur et les rejouer sous forme de scripts d’automatisation
• Déboguer des workflows défaillants de manière interactive sur le site réel

Nous, chez Saffron Health, avons créé Libretto pour nous aider à maintenir nos intégrations navigateur avec les logiciels de santé courants. Nous l’open‑sourceons pour que d’autres équipes puissent en faire de même plus facilement.

https://github.com/user-attachments/assets/9b9a0ab3-5133-4b20-b3be-459943349d18

Liens rapides

• Site web : libretto.sh
• Documentation : libretto.sh/docs
• Dépôt : github.com/saffron-health/libretto
• Discord : discord.gg/NYrG56hVDt

Installation

# Ajoute Libretto à votre projet. Nécessite Node.js et npm.
npm install libretto

# Première configuration : installe les compétences et télécharge Chromium
npx libretto setup

# Vérifie l’état de préparation de l’espace de travail à tout moment
npx libretto status

setup crée le répertoire .libretto/, installe les compétences de l’agent et télécharge Chromium sauf si vous passez --skip-browsers.

Cas d’utilisation

Libretto est conçu pour être utilisé comme une compétence via votre agent de codage. Voici quelques exemples d’invites :

Génération de script en un coup

Utilise la compétence Libretto. Va sur LinkedIn et récupère les 10 premiers posts avec leur contenu, l’auteur, le nombre de réactions, les 25 premiers commentaires et les 25 premiers repartages.

Votre agent de codage ouvrira une fenêtre pour que vous vous connectiez à LinkedIn, puis commencera automatiquement à explorer.

Construction interactive de script

Je vais te montrer un workflow dans l’EHR eClinicalWorks pour obtenir l’ID d’assurance primaire d’un patient. Utilise la compétence Libretto pour le transformer en script Playwright qui prend le nom et la date de naissance du patient et renvoie l’ID d’assurance. L’URL est…

Libretto peut lire les actions que vous effectuez dans le navigateur, vous pouvez donc exécuter un workflow, puis lui demander d’utiliser vos actions pour reconstruire le workflow.

Convertir l’automatisation navigateur en requêtes réseau

Nous avons un script navigateur dans ./integration.ts qui automatise la visite de Hacker News et récupère les 10 premiers posts. Convertis‑le en scripts réseau directs à la place. Utilise la compétence Libretto.

Libretto peut lire les requêtes réseau depuis le navigateur, ce qui lui permet de rétro‑ingénierer l’API et de créer un script qui appelle directement ces requêtes. Les appels API directs sont plus rapides et plus fiables que l’automatisation de l’interface utilisateur. Vous pouvez également demander à Libretto d’effectuer une analyse de sécurité qui examine les requêtes pour détecter les cookies de sécurité courants, afin de comprendre si une approche par requêtes réseau sera sûre.

Réparer des intégrations cassées

Nous avons un script navigateur dans ./integration.ts censé aller sur Availity et effectuer une vérification d’éligibilité pour un patient. Mais j’obtiens une erreur de sélecteur cassé quand je l’exécute. Corrige‑le. Utilise la compétence Libretto.

Les agents peuvent utiliser Libretto pour reproduire l’échec, mettre le workflow en pause à tout moment, inspecter la page en direct et corriger les problèmes, le tout de manière autonome.

Utilisation en ligne de commande

Vous pouvez également utiliser Libretto directement depuis le terminal. Toutes les commandes acceptent --session <nom> pour cibler une session spécifique.

npx libretto open <url>                    # lance le navigateur et ouvre une URL
npx libretto run ./integration.ts --headless # exécute un workflow et ferme le navigateur en cas de succès
npx libretto run ./integration.ts --headless --stay-open-on-success # garde l’exécution réussie inspectable
npx libretto snapshot --session <nom>      # capture une capture d’écran et un arbre d’accessibilité compact
npx libretto exec "<code>"                 # exécute du TypeScript Playwright sur la page ouverte
npx libretto close                         # ferme le navigateur

Les sessions run sont inspectables via les mêmes commandes basées sur un démon que les sessions open. Les exécutions réussies ferment le navigateur par défaut ; passez --stay-open-on-success pour conserver le navigateur ouvert pour pages, snapshot et exec. Les workflows en échec ou en pause laissent le navigateur ouvert afin que vous puissiez inspecter l’état exact de la page avant de corriger ou de reprendre le workflow.

Exécutez npx libretto help pour la liste complète des commandes.

Configuration

Tout l’état de Libretto se trouve dans un répertoire .libretto/ à la racine de votre projet. Consultez la documentation de configuration pour plus de détails sur les fichiers de configuration, les sessions et les profils.

Télémétrie

Libretto enregistre des données de télémétrie CLI pour comprendre l’utilisation de la CLI et nous aider à prioriser les améliorations. Chaque commande résolue peut envoyer uniquement un identifiant d’installation, un horodatage, un nom d’événement de commande tel que libretto run, un booléen d’erreur, la version du paquet, le canal de build (node_modules, source ou unknown) et, lorsque connecté à Libretto Cloud, l’identifiant utilisateur cloud configuré. Libretto n’envoie pas les arguments de commande, les URL, les chemins de projet, les cookies de session, les clés API, les messages d’erreur ou leurs détails, ni les e‑mails.

L’identifiant d’installation est stocké dans le fichier de télémétrie à ~/.libretto/telemetry.json. L’implémentation se trouve dans packages/libretto/src/cli/core/telemetry.ts.

Pour désactiver la télémétrie, définissez LIBRETTO_TELEMETRY_DISABLED=1, définissez DO_NOT_TRACK=1, exécutez avec CI=1, ou modifiez ~/.libretto/telemetry.json et définissez "enabled": false.

Rejoignez la communauté

Rejoignez notre Discord pour échanger avec d’autres développeurs, obtenir de l’aide et partager ce que vous avez construit :

Pour des discussions plus longues, rendez‑vous sur GitHub Discussions. Vous avez trouvé un bug ? Ouvrez un ticket.

Licence

Licence MIT — utilisez‑la librement dans des projets commerciaux et open‑source.

Développement

Pour le développement local dans ce dépôt :

pnpm i
pnpm build
pnpm type-check
pnpm test

Structure des sources :

• packages/libretto/src/cli/ — commandes CLI
• packages/libretto/src/runtime/ — environnement d’exécution du navigateur (réseau, récupération, téléchargements)
• packages/libretto/src/shared/ — utilitaires partagés (configuration, client LLM, journalisation, état)
• packages/libretto/test/ — fichiers de test (*.spec.ts)
• packages/libretto/README.template.md — source de vérité pour le dépôt et les README des paquets
• packages/libretto/skills/libretto/ — source de vérité pour la compétence Libretto

Exécutez pnpm sync:mirrors après avoir modifié packages/libretto/README.template.md ou tout ce qui se trouve sous packages/libretto/skills/libretto/.

Pour vérifier que les README générés, les miroirs des compétences et les métadonnées de version des compétences sont synchronisés sans les corriger, exécutez pnpm check:mirrors. Pour publier, exécutez pnpm prepare-release.

[!NOTE] Il s’agit d’un projet en phase précoce, en cours de développement actif. Les API peuvent changer avant la version 1.0. Nous recommandons d’épingler des versions spécifiques en production.

Construit par l’équipe de Saffron Health.