# SDK d'automatisation

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

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 :

```bash
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 :

```bash
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'automatisation | Transport | Identifiant | Propriétaire de l'enregistrement / de l'exécution métier |
| --- | --- | --- | --- |
| CI, ordonnanceur, service ou script existant | `external` | Clé API `ingest-runner` liée au job | Le SDK signale l'enregistrement ; le propriétaire existant exécute le travail |
| Job Playwright volontairement distribué par BernOps | `native` | Jeton de bouclage injecté par le worker ; aucune clé API | Worker/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.

```bash
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](/fr/docs/automation-sdk#cicd-live-monitoring).

## 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](/fr/docs/github-integration#ci-check-observation) 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) :

```bash
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](/fr/docs/workers-and-pool#worker-setup) 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

| API | Comportement |
| --- | --- |
| `run.log.debug/info/warn/error` | Capture un log structuré et retourne immédiatement son admission en file. |
| `run.step` / `run.startStep` | Cré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/duration` | Capture des métriques à faible cardinalité. Les durées sont exprimées en millisecondes. |
| `run.progress` | Signale une progression par compteur, pourcentage ou sans valeur déterminée. |
| `run.attach` | Calcule l'empreinte, téléverse et confirme de manière persistante une pièce jointe rejouable. Attendez toujours son résultat. |
| `run.flush` | Attend 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 :

| Erreur | Action habituelle |
| --- | --- |
| `BernOpsConfigurationError` | Corrigez une configuration de transport, d'URL, d'identifiant, de livraison ou de masquage incomplète ou ambiguë. |
| `BernOpsAuthenticationError` | Faites pivoter ou corrigez la clé, ou examinez l'affectation courante du worker. Ne relancez pas avec les mêmes identifiants rejetés. |
| `BernOpsValidationError` | Corrigez une télémétrie, progression, métrique ou pièce jointe invalide ou non prise en charge. |
| `BernOpsCapabilityError` | Adaptez le comportement aux capacités négociées et au propriétaire du cycle de vie. |
| `BernOpsStateError` | Arrêtez les appels d'étape ou terminaux contradictoires et vérifiez les états obsolètes. |
| `BernOpsTransportError` | Examinez `status`, `requestId`, `retryAfterMs` et `retryable`. |
| `BernOpsDeliveryError` | Examinez le `report` immuable retourné par une limite de livraison stricte. |
| `BernOpsFinalizedRunError` | Considé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ôme | Vérification |
| --- | --- |
| Le transport est incomplet ou ambigu | Sélectionnez explicitement `external` ou `native` et retirez les variables appartenant à l'autre transport. |
| L'URL externe est rejetée | Utilisez HTTPS. Pour un test local, utilisez un constructeur explicite avec une adresse de bouclage littérale et `allowInsecureLoopback: true`. |
| L'authentification échoue | Vé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 échouent | Cré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ée | Ré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 expire | Examinez `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 rouverte | Gardez les chemins et octets stables et retournez un nouveau flux non lu identique à chaque appel de la fabrique. |
| Le processus ne se termine pas | Attendez 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.

## Références associées

- [Clés API et scopes](/fr/docs/api-keys-scopes)
- [Jobs Playwright](/fr/docs/playwright-jobs)
- [Variables runtime](/fr/docs/runtime-variables)
- [Workers et exécution](/fr/docs/workers-execution)
- [Référence API REST](/fr/docs/api)

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.
