Documentation
Documentation/Integrations

SDK d'automatisation

Suivi léger des automatisations existantes sans contrôler leur exécution ; limites SDK actuelles et mode worker natif séparé.

sdktypescriptexécutions externesbridge natiftélémétriesuivi légerobservation seule
Voir le Markdown
Sur cette page

BernOps ajoute une visibilité légère aux automatisations existantes : logs en direct, étapes observées, progression, métriques et résultats. Le suivi externe ne remplace ni n'exécute l'automatisation. Son ordonnanceur, système CI, service ou script existant garde le contrôle.

Le SDK TypeScript privé couvre le reporting Node.js externe et les jobs Playwright gérés par BernOps sélectionnés séparément. Ce guide décrit 0.1.0-internal.3, un artéfact privé UNLICENSED, pas un package de registre public. Les consommateurs externes installent le bundle conservé exact ; les jobs natifs utilisent l'artéfact fourni par leur opérateur worker.

Contrat de suivi externe léger

  • Conservez les commandes, le démarrage, la planification, les nouvelles tentatives métier, l'annulation, les signaux, le code de sortie et les erreurs existants.
  • Signalez des observations aux points d'événement existants. Les reprises de livraison SDK concernent uniquement la télémétrie, jamais la réexécution métier.
  • Borner le coût et les tampons du reporting ; rendre les pertes/dégradations explicites. Un heartbeat de reporting ne prouve pas la santé du travail métier.
  • N'ajoutez pas de lanceur de commandes, superviseur de processus, ordonnanceur de remplacement ou framework de récupération durable uniquement pour observer une automatisation.
Objectif et comportement actuel du SDK

client.run() attend la création distante de l'enregistrement avant d'appeler son callback. startRun() attend aussi cette ouverture ; configuration, authentification et ouverture peuvent échouer même avec failurePolicy: 'diagnostic'. Aucune de ces API ne garantit seule un démarrage passif. Ne placez pas l'unique invocation métier dans un callback SDK ou derrière l'attente de l'initialisation du reporting. Un support non bloquant manquant est une lacune SDK/produit à qualifier et corriger, pas une raison de remplacer l'automatisation par un gros framework de suivi. Cette documentation ne change pas le runtime.

Les jobs natifs volontairement distribués aux workers BernOps restent un mode d'exécution séparé ; leur worker/Playwright possède l'exécution et le statut final. L'observation externe ne donne pas cette autorité.

Prérequis et installation

  • Utilisez Node.js 22 ou 24 pour les automatisations externes et la création locale de jobs natifs. Node.js 24 est recommandé.
  • Pour une automatisation externe ou une vérification locale des types, demandez au responsable des versions BernOps les fichiers .tgz, .tgz.sha256 et .manifest.json correspondants. Conservez les trois fichiers ensemble.
  • Importez uniquement depuis @bernops/automation. Les consommateurs ESM, CommonJS et TypeScript sont pris en charge ; les imports internes ne le sont pas.

Vérifiez la somme de contrôle avant d'installer l'artéfact dans une automatisation externe ou un projet de création local :

Terminal
export SDK_ARTIFACT_DIR=/chemin/absolu/vers/la-version-conservee
export SDK_TARBALL="$SDK_ARTIFACT_DIR/bernops-automation-0.1.0-internal.3.tgz"
 
cd "$SDK_ARTIFACT_DIR"
sha256sum --check "$(basename "$SDK_TARBALL").sha256"
 
cd /chemin/absolu/vers/votre-automatisation
npm install --offline --ignore-scripts --no-audit --no-fund \
  --registry=https://registry.invalid/ "$SDK_TARBALL"
npm ls @bernops/automation

Le fichier SHA-256 doit provenir de la même version approuvée que le manifeste. Un responsable disposant de la révision source BernOps correspondante peut exécuter la vérification complète du manifeste, du contenu du package, des déclarations et des consommateurs propres :

Terminal
cd /chemin/absolu/vers/bernops/sdk/typescript
npm run artifact:verify -- --manifest \
  "$SDK_ARTIFACT_DIR/bernops-automation-0.1.0-internal.3.manifest.json"
Utilisez un seul artéfact exact

Pour les projets externes et locaux, ne remplacez pas le tarball par un lien workspace, une installation du répertoire source, un alias mutable, un import interne ou une solution de repli vers un registre public. Un job natif déployé n'utilise pas votre node_modules local ; son worker fournit le package. Si l'une de ces versions d'artéfact diffère de ce guide, utilisez la documentation et la politique de compatibilité correspondantes plutôt que de supposer sa compatibilité.

Choisir un transport

Emplacement de l'automatisationTransportIdentifiantPropriétaire de l'enregistrement / de l'exécution métier
CI, ordonnanceur, service ou script existantexternalClé API ingest-runner liée au jobLe SDK signale l'enregistrement ; le propriétaire existant exécute le travail
Job Playwright volontairement distribué par BernOpsnativeJeton de bouclage injecté par le worker ; aucune clé APIWorker/Playwright possède l'exécution distribuée et son enregistrement

Sélectionnez explicitement le transport avec BernOps.fromEnv({ transport: 'external' }) ou BernOps.fromEnv({ transport: 'native' }). Utilisez auto uniquement si le déploiement garantit une seule configuration complète. La sélection échoue de manière fermée et ne tente jamais une solution de repli après une erreur d'authentification, TLS, d'identité ou de capacité. Pour l'observation externe, cela ferme le canal de reporting, pas le processus métier existant ; isolez/signalez l'indisponibilité sans affaiblir la sécurité ni prendre le contrôle de l'exécution.

Démarrage rapide externe

Créez un job externe et une clé ingest-runner, puis stockez la clé en clair dans le gestionnaire de secrets du processus. Les scopes d'écriture minimaux sont runs:write, runs:finish, logs:write, steps:write, metrics:write, progress:write et attachments:write. Les scopes de lecture et d'administration ne sont pas requis par le SDK émetteur.

Terminal
export BERNOPS_BASE_URL=https://bernops.example
export BERNOPS_API_KEY='secret-lie-au-job'
export BERNOPS_EXTERNAL_JOB_ID='uuid-job-externe'
export AUTOMATION_RUN_ID='tentative-ordonnanceur-123'

Définissez AUTOMATION_RUN_ID depuis un ID durable fourni par l'ordonnanceur, le système CI ou la tentative métier. Réutilisez cette valeur lorsque la même tentative est relancée ; ne générez pas un nouvel ID à chaque démarrage de processus.

Construisez BernOps.fromEnv({ transport: 'external', failurePolicy: 'diagnostic' }) dans une frontière réservée au reporting. Obtenir un handle avec startRun() attend encore l'ouverture distante et peut échouer ; cela ne doit pas conditionner le démarrage de l'automatisation existante. client.run() et les étapes à callbacks restent des facilités API explicitement couplées, pas le choix passif externe par défaut.

Cet exemple d'événement en direct reçoit un handle de reporting déjà ouvert. Il n'exécute aucun travail métier, ne change pas le contrôle de processus et renvoie l'admission en file, pas la persistance. Obtenir ce handle indépendamment du démarrage demande encore une intégration qualifiée ; ce n'est pas un adaptateur passif inventé.

ts
import { type RunHandle } from '@bernops/automation';
 
export function reportObservedProgress(
  record: RunHandle,
  processed: number,
  total: number,
): boolean {
  try {
    return [
      record.log.info('Progression observée'),
      record.metric.gauge('records.processed', processed, { unit: 'items' }),
      record.progress({ current: processed, total, stage: 'import' }),
    ].every(result => result.accepted);
  } catch {
    return false; // Signaler la dégradation via le diagnostic borné existant.
  }
}

BERNOPS_EXTERNAL_JOB_ID identifie le job de reporting enregistré ; externalRunId identifie la tentative ordonnanceur/CI/métier existante. Réutilisez cette identité pour les reprises de télémétrie prises en charge. Ne créez ni ne rejouez du travail métier parce que le reporting a échoué ou que son enregistrement est terminé.

startStep(), la fin d'étape end() et les méthodes externes complete()/fail() signalent les limites/résultats réellement observés chez le propriétaire existant. Leurs promesses peuvent échouer. Isolez-les, ainsi que client.shutdown() borné, des erreurs métier et du contrôle de processus ; signalez honnêtement la télémétrie inconnue/dégradée sans inventer de résultat. L'interruption SDK peut tenter de finaliser son enregistrement en échec ; elle ne fait pas autorité sur l'annulation métier. Voir le suivi CI/CD.

Suivi SDK CI/CD en direct

Prototype retiré : huit workflows/seize profils et variantes utilisent le même processus SDK de reporting uniquement. Ni commande, stdout/stderr, reprise ou signal métier ; démarrage indépendant, SDK inchangé. Backend : trois diagnostics ; autres profils : observation ouverte, logs fixes, progression indéterminée sans pourcentage inventé.

Extension : observateur revu préinstallé (BERNOPS_CI_REPORTER_DIRECTORY), SDK exact (BERNOPS_CI_SDK_DIRECTORY), HTTPS BERNOPS_CI_BASE_URL, BERNOPS_CI_OBSERVATION_ENABLED=true. Chaque profil a un ID et une clé liée au job ; backend : BERNOPS_CI_BACKEND_JOB_ID / BERNOPS_CI_BACKEND_API_KEY. Node 22/24 existant, sélection facultative BERNOPS_CI_NODE. Identités distinctes par variante/tentative.

Clés dans des environnements protégés uniquement, jamais dans les secrets dépôt/organisation. if: main ne protège pas contre un YAML de PR modifié. Vérifiez l'admission GitHub : main seulement, hors refs PR/autres branches/tags ; conservez les approbations existantes. Sinon, webhooks seuls. Backend : push main uniquement ; autres profils : main/manuels/contrôleurs déjà autorisés. Aucune clé aux PR. La clé backend dépôt exige une bascule/remplacement/révocation coordonnés, non effectués par ce code.

FIFO privée non bloquante : pertes d'observations, jamais de travail. Requête cinq secondes/une tentative ; flush/arrêt une seconde ; attente post-métier dix secondes maximum. Même UID : pas de l'isolation. Le SDK ne finalise pas fidèlement l'annulation : observateur explicitement incomplet, sans résultat inventé. Les observations GitHub conservent les états natifs et le nettoyage post-tâche. Vérifiez la visibilité après activation autorisée ; succès CI ou NOT_CONFIRMED ne prouve pas un déploiement.

Qualifiez cette frontière ainsi que les fixtures de cycle de vie du SDK :

  1. Le travail existant démarre même si l'initialisation du reporting est indisponible ; commandes, reprises, signaux, erreurs et code de sortie restent inchangés.
  2. Des logs réels, une étape observée ouverte et la progression apparaissent dans le navigateur avant la fin métier, sans dépendre du flush final pour devenir visibles.
  3. Coût/tampons du reporting restent bornés, pertes explicites ; la reconnexion récupère les observations persistées sans dupliquer ni rejouer le travail métier.

La fixture actuelle npm run integration:live consomme un BERNOPS_SDK_ARTIFACT_MANIFEST exact sur dev-acceptance. Sa cible locale préchauffée ≤2 secondes n'est pas un SLA hébergé ; les cas backend vérifient séparément visibilité en direct, codes de sortie inchangés et ingestion indisponible. Signalez une capacité SDK manquante comme lacune produit au lieu d'ajouter une couche d'orchestration. Ce guide n'autorise aucune activation en production, installation/service ou opération de déploiement.

Après publication autorisée des docs (générer localement n'est pas déployer) :

Terminal
bernops docs search "suivi léger des automatisations"
bernops docs get automation-sdk#monitoring-contract
bernops docs get automation-sdk#cicd-live-monitoring

Démarrage rapide Playwright natif

N'ajoutez pas de tarball ni de commande d'installation de package à un job Playwright BernOps enregistré. Une fois le bootstrap privé approuvé installé, lancez bernops setup et choisissez 3 (worker d'automatisation) ou 4 (les deux) ; le menu propose par défaut l'authentification seule. La configuration unifiée du worker obtient une version immuable signée avec le SDK privé exact déjà intégré, vérifie la disponibilité réelle SDK/navigateur et exige une approbation distincte de l'espace pour native_bridge_v1 ainsi qu'une connexion worker confirmée. Ce parcours ne demande ni build depuis un checkout, ni installation publique du SDK, ni montage d'artéfact. Une installation locale du package sert seulement à la création et à la vérification des types ; elle ne configure pas le worker déployé. Les anciens workers ne sont pas actualisés silencieusement. Demandez à l'opérateur de vérifier les versions disponibles et les capacités approuvées si l'import du package ou la capacité native est indisponible.

Le worker BernOps injecte la configuration du bridge pour chaque exécution. Ne définissez et ne copiez pas AB_LOG_URL, BERNOPS_BRIDGE_TOKEN, BERNOPS_RUN_ID ou BERNOPS_PROJECT_ID, et n'ajoutez pas de BERNOPS_API_KEY au job.

ts
import { test, expect } from '@playwright/test';
import { BernOps } from '@bernops/automation';
 
test('checkout', async ({ page }) => {
  const client = BernOps.fromEnv({
    transport: 'native',
    onDiagnostic(diagnostic) {
      console.warn(`[bernops:${diagnostic.code}] ${diagnostic.message}`);
    },
  });
 
  try {
    const capabilities = await client.capabilities();
    expect(capabilities.lifecycleOwner).toBe('worker');
 
    await client.run({ name: 'checkout' }, async (run) => {
      run.log.info('ouverture du checkout');
      await run.step('soumettre la commande', async () => {
        await page.goto('/checkout');
      });
    });
  } finally {
    await client.shutdown();
  }
});

Le worker et Playwright gèrent le démarrage, le heartbeat et l'état terminal. run.complete() et run.fail() existent sur le type partagé, mais rejettent l'appel en mode natif avec BernOpsCapabilityError et code === 'lifecycle_owned_by_worker'. Appelez capabilities() avant tout comportement facultatif : les pièces jointes persistantes natives ne sont disponibles que si persistentAttachments vaut true, et les limites de taille retournées font autorité.

Télémétrie, progression et pièces jointes

APIComportement
run.log.debug/info/warn/errorCapture un log structuré et retourne immédiatement son admission en file.
run.step / run.startStepCrée des étapes gérées par callback ou terminées manuellement. Transmettez un vrai handle d'étape parente pour le travail détaché.
run.metric.gauge/count/rate/durationCapture des métriques à faible cardinalité. Les durées sont exprimées en millisecondes.
run.progressSignale une progression par compteur, pourcentage ou sans valeur déterminée.
run.attachCalcule l'empreinte, téléverse et confirme de manière persistante une pièce jointe rejouable. Attendez toujours son résultat.
run.flushAttend le travail accepté jusqu'au marqueur courant et laisse l'exécution modifiable.

La progression peut être regroupée pendant son attente ; les trous de séquence sont donc valides. Elle ne détermine jamais le succès ou l'échec et BernOps ne fabrique pas une progression à 100 % pour une exécution active. Gardez les noms et tags de métriques à faible cardinalité : n'utilisez pas d'adresses e-mail, d'ID utilisateur, d'ID de requête, d'horodatages, d'URL complètes ou de valeurs libres comme noms ou tags.

Une pièce jointe doit utiliser exactement une source rejouable : path, des données Uint8Array ou Blob, ou une fabrique open qui retourne un nouveau flux non lu à chaque tentative de livraison.

ts
// `run` est un handle de reporting existant ; ceci n'exécute aucun travail métier.
const attachment = await run.attach({
  path: '/tmp/import-summary.json',
  fileName: 'import-summary.json',
  contentType: 'application/json',
});
 
console.log(attachment.attachmentId, attachment.sizeBytes, attachment.duplicate);

Les types de contenu pris en charge sont PNG, JPEG, WebP, texte brut, JSON, CSV et PDF. Ne modifiez pas les octets du chemin ou du flux avant la fin de attach(). La confirmation représente l'enregistrement persistant des métadonnées et du stockage, pas une simple admission en file.

Livraison, erreurs et sécurité

Les méthodes de log, de métrique et de progression retournent un EnqueueResult ; accepted: true signifie uniquement que la file en mémoire a accepté l'événement. La livraison réseau s'observe avec flush(), les méthodes terminales externes et shutdown() grâce à un DeliveryReport contenant delivered, duplicate, dropped, pending, failed, timedOut et droppedByReason.

La politique par défaut failurePolicy: 'diagnostic' traite la dégradation de livraison en arrière-plan/finalisation automatique via diagnostics et rapports. Ce n'est pas une garantie générale de non-blocage : configuration, authentification, ouverture distante et opérations explicites peuvent échouer ; l'échec d'ouverture de client.run() empêche son callback. Gardez-les dans la frontière de reporting. strict couple explicitement l'échec de télémétrie aux callbacks réussis et n'est pas le choix d'observation seule. Le SDK préserve l'erreur initiale d'un callback géré ; cette garantie est plus étroite que la préservation de toute automatisation indépendante.

Testez les classes d'erreur publiques, code, retryable et les champs sûrs propres à chaque classe plutôt que de comparer le texte du message :

ErreurAction habituelle
BernOpsConfigurationErrorCorrigez une configuration de transport, d'URL, d'identifiant, de livraison ou de masquage incomplète ou ambiguë.
BernOpsAuthenticationErrorFaites pivoter ou corrigez la clé, ou examinez l'affectation courante du worker. Ne relancez pas avec les mêmes identifiants rejetés.
BernOpsValidationErrorCorrigez une télémétrie, progression, métrique ou pièce jointe invalide ou non prise en charge.
BernOpsCapabilityErrorAdaptez le comportement aux capacités négociées et au propriétaire du cycle de vie.
BernOpsStateErrorArrêtez les appels d'étape ou terminaux contradictoires et vérifiez les états obsolètes.
BernOpsTransportErrorExaminez status, requestId, retryAfterMs et retryable.
BernOpsDeliveryErrorExaminez le report immuable retourné par une limite de livraison stricte.
BernOpsFinalizedRunErrorConsidérez la tentative durable comme déjà terminée ou utilisez volontairement un nouvel ID de tentative métier.
  • Les endpoints externes exigent HTTPS. HTTP n'est accepté que pour les URL de test littérales 127.0.0.1 ou [::1], configurées explicitement avec allowInsecureLoopback: true ; les identifiants dans l'URL et les redirections sont rejetés.
  • Le masquage est une défense supplémentaire. Ne capturez jamais d'en-têtes d'autorisation, de cookies, de jetons, de données personnelles, de données de carte ou de corps de requête et de réponse non limités.
  • Les octets des pièces jointes ne sont pas masqués. Nettoyez les fichiers avant leur téléversement, évitez les captures d'écran inutiles et appliquez une rétention ainsi que des contrôles d'accès adaptés.
  • Les files et tentatives sont bornées et en mémoire ; elles ne survivent pas à SIGKILL, à un manque de mémoire, à la perte de l'hôte ou à une coupure de courant.
  • L'arrêt SDK arrête le reporting, pas le processus externe. Interrompre un callback externe actif (y compris à l'échéance d'attente) peut faire rejeter client.run() avec run_interrupted malgré un callback réussi en mode diagnostic. Traitez le nettoyage borné dans le périmètre de reporting ; préservez les règles de signaux/code de sortie de l'hôte. L'import n'installe aucun gestionnaire de signal.

Dépannage

SymptômeVérification
Le transport est incomplet ou ambiguSélectionnez explicitement external ou native et retirez les variables appartenant à l'autre transport.
L'URL externe est rejetéeUtilisez HTTPS. Pour un test local, utilisez un constructeur explicite avec une adresse de bouclage littérale et allowInsecureLoopback: true.
L'authentification échoueVérifiez l'association job/projet et la rotation de la clé. Ne relancez pas avec des identifiants rejetés inchangés.
L'identité ou les capacités natives échouentCréez un nouveau client dans l'affectation courante du worker ; ne réutilisez jamais des valeurs de bridge copiées.
Une exécution externe durable est finaliséeRéutilisez-la uniquement pour observer son résultat terminal antérieur, ou choisissez un nouvel ID pour une véritable nouvelle tentative métier.
La livraison reste en attente, est abandonnée, échoue ou expireExaminez onDiagnostic, le rapport et droppedByReason ; corrigez le transport et les délais avant d'augmenter les limites de file.
La pièce jointe change ou ne peut pas être rouverteGardez les chemins et octets stables et retournez un nouveau flux non lu identique à chaque appel de la fabrique.
Le processus ne se termine pasAttendez les pièces jointes, les limites de vidage ou terminales et client.shutdown() ; nettoyez ensuite les minuteurs et listeners gérés par l'hôte.

Ne masquez pas les erreurs permanentes avec des tentatives illimitées, des scopes plus larges, la désactivation de TLS, le suivi des redirections, la journalisation brute des corps de réponse ou des files plus grandes.

L'artéfact installé contient ses propres README.md, CHANGELOG.md, COMPATIBILITY.md, UPGRADING.md et déclarations TypeScript. Utilisez ces fichiers versionnés et les types de la racine du package dans votre IDE pour obtenir les signatures exactes ; ne copiez pas une signature d'API provenant d'une autre révision du SDK.