seqpulse 0.4.0 → 0.5.2

package/CI_CD_SNIPPETS_MULTI-PLATFORM.md

@@ -0,0 +1,221 @@
+# CI/CD Snippets Multi-Platform
+
+Snippets de reference pour integrer `SeqPulse` avec la meme logique sur plusieurs plateformes CI/CD:
+
+1. `trigger` avant le deploy
+2. deploy applicatif
+3. `finish` toujours execute, meme en cas d'echec
+
+Tous les snippets ci-dessous utilisent le package publie `seqpulse@0.5.1` et la sortie ciblee `--output deploymentId`.
+
+## Variables requises
+
+Definir ces secrets/variables dans votre plateforme CI:
+
+- `SEQPULSE_BASE_URL`
+- `SEQPULSE_API_KEY`
+- `SEQPULSE_METRICS_ENDPOINT`
+
+## Design cible
+
+- `trigger` reste non bloquant pour ne pas casser le deploy si SeqPulse est indisponible
+- `deploymentId` est capture dans une variable CI, pas dans un JSON parse fragile
+- `finish` recoit un statut explicite venant de la plateforme
+
+## GitHub Actions
+
+```yaml
+name: deploy
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      SEQPULSE_BASE_URL: ${{ secrets.SEQPULSE_BASE_URL }}
+      SEQPULSE_API_KEY: ${{ secrets.SEQPULSE_API_KEY }}
+      SEQPULSE_METRICS_ENDPOINT: ${{ secrets.SEQPULSE_METRICS_ENDPOINT }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install
+        run: npm ci
+
+      - name: SeqPulse Trigger
+        id: seqpulse_trigger
+        run: |
+          DEPLOYMENT_ID="$(npx -y seqpulse@0.5.1 ci trigger \
+            --env prod \
+            --branch "${GITHUB_REF_NAME}" \
+            --non-blocking true \
+            --output deploymentId)"
+          echo "deployment_id=${DEPLOYMENT_ID}" >> "$GITHUB_OUTPUT"
+
+      - name: Deploy
+        run: ./deploy.sh
+
+      - name: SeqPulse Finish
+        if: ${{ always() }}
+        run: |
+          npx -y seqpulse@0.5.1 ci finish \
+            --deployment-id "${{ steps.seqpulse_trigger.outputs.deployment_id }}" \
+            --job-status "${{ job.status }}" \
+            --non-blocking true
+```
+
+## GitLab CI
+
+```yaml
+deploy_prod:
+  image: node:20
+  stage: deploy
+  script:
+    - npm ci
+    - |
+      DEPLOYMENT_ID="$(npx -y seqpulse@0.5.1 ci trigger \
+        --env prod \
+        --branch "${CI_COMMIT_REF_NAME}" \
+        --non-blocking true \
+        --output deploymentId)"
+      printf 'SEQPULSE_DEPLOYMENT_ID=%s\n' "$DEPLOYMENT_ID" > .seqpulse.env
+    - ./deploy.sh
+  after_script:
+    - . ./.seqpulse.env 2>/dev/null || true
+    - |
+      npx -y seqpulse@0.5.1 ci finish \
+        --deployment-id "${SEQPULSE_DEPLOYMENT_ID}" \
+        --job-status "${CI_JOB_STATUS}" \
+        --non-blocking true
+```
+
+## CircleCI
+
+```yaml
+version: 2.1
+
+jobs:
+  deploy:
+    docker:
+      - image: cimg/node:20.11
+    steps:
+      - checkout
+
+      - run:
+          name: Install
+          command: npm ci
+
+      - run:
+          name: SeqPulse Trigger
+          command: |
+            DEPLOYMENT_ID="$(npx -y seqpulse@0.5.1 ci trigger \
+              --env prod \
+              --branch "${CIRCLE_BRANCH}" \
+              --non-blocking true \
+              --output deploymentId)"
+            echo "export SEQPULSE_DEPLOYMENT_ID=${DEPLOYMENT_ID}" >> "$BASH_ENV"
+
+      - run:
+          name: Deploy
+          command: |
+            set +e
+            ./deploy.sh
+            DEPLOY_EXIT_CODE=$?
+            if [ "$DEPLOY_EXIT_CODE" -eq 0 ]; then
+              echo 'export SEQPULSE_JOB_STATUS=success' >> "$BASH_ENV"
+            else
+              echo 'export SEQPULSE_JOB_STATUS=failed' >> "$BASH_ENV"
+            fi
+            exit "$DEPLOY_EXIT_CODE"
+
+      - run:
+          name: SeqPulse Finish
+          when: always
+          command: |
+            . "$BASH_ENV"
+            npx -y seqpulse@0.5.1 ci finish \
+              --deployment-id "${SEQPULSE_DEPLOYMENT_ID}" \
+              --job-status "${SEQPULSE_JOB_STATUS:-failed}" \
+              --non-blocking true
+```
+
+## Jenkins
+
+```groovy
+pipeline {
+    agent any
+
+    options {
+        disableConcurrentBuilds()
+        timestamps()
+        timeout(time: 20, unit: 'MINUTES')
+    }
+
+    environment {
+        SEQPULSE_BASE_URL = credentials('seqpulse_base_url')
+        SEQPULSE_API_KEY = credentials('seqpulse_api_key')
+        SEQPULSE_METRICS_ENDPOINT = credentials('seqpulse_metrics_endpoint')
+        SEQPULSE_DEPLOYMENT_ID = ''
+    }
+
+    stages {
+        stage('Install') {
+            steps {
+                sh 'npm ci'
+            }
+        }
+
+        stage('SeqPulse Trigger') {
+            steps {
+                script {
+                    def branch = env.CHANGE_BRANCH ?: env.BRANCH_NAME ?: env.GIT_BRANCH ?: 'main'
+                    env.SEQPULSE_DEPLOYMENT_ID = sh(
+                        script: """
+                            npx -y seqpulse@0.5.1 ci trigger \
+                              --env prod \
+                              --branch "${branch}" \
+                              --non-blocking true \
+                              --output deploymentId
+                        """,
+                        returnStdout: true
+                    ).trim()
+                }
+            }
+        }
+
+        stage('Deploy') {
+            steps {
+                sh './deploy.sh'
+            }
+        }
+    }
+
+    post {
+        always {
+            script {
+                def jobStatus = (currentBuild.currentResult ?: 'SUCCESS').toLowerCase()
+                sh """
+                    npx -y seqpulse@0.5.1 ci finish \
+                      --deployment-id "${env.SEQPULSE_DEPLOYMENT_ID ?: ''}" \
+                      --job-status "${jobStatus}" \
+                      --non-blocking true
+                """
+            }
+        }
+    }
+}
+```
+
+## Notes pratiques
+
+- Si le package est deja installe dans le projet, vous pouvez remplacer `npx -y seqpulse@0.5.1` par `npx seqpulse`.
+- Pour les deploys `prod`, ajoutez un gate explicite sur `main`/tag si votre pipeline est multi-branches.
+- Le pattern recommande est toujours le meme: `trigger -> deploy -> finish`.

package/README.md

@@ -85,22 +85,27 @@ async function runDeployment() {
 
 ```bash
 # Trigger
-npx -y seqpulse@0.4.0 ci trigger \
+DEPLOYMENT_ID="$(npx -y seqpulse@0.5.1 ci trigger \
   --env prod \
-  --github-output "$GITHUB_OUTPUT"
+  --output deploymentId)"
 
 # Finish
-npx -y seqpulse@0.4.0 ci finish \
-  --deployment-id "$SEQPULSE_DEPLOYMENT_ID" \
+npx -y seqpulse@0.5.1 ci finish \
+  --deployment-id "$DEPLOYMENT_ID" \
   --job-status "$JOB_STATUS"
 ```
 
 Notes:
 
+- `--output deploymentId` permet de capturer directement l'identifiant de deployment.
 - `--github-output` ecrit `deployment_id`, `status`, `http_status`.
 - mode par defaut: non-bloquant (`--non-blocking true`).
 - pour mode strict: `--blocking`.
 
+## Documentation
+
+- [Multi-platform CI/CD snippets](./CI_CD_SNIPPETS_MULTI-PLATFORM.md)
+
 ## Compatibility note
 
 Cette evolution **n'ecrase pas** le SDK runtime actuel:

package/bin/seqpulse.js

@@ -4,6 +4,8 @@
 const fs = require("node:fs");
 const seqpulse = require("../index.js");
 
+const BOOLEAN_FLAGS = new Set(["blocking", "help", "h"]);
+
 function printUsage() {
   console.error(`Usage:
   seqpulse ci trigger [options]
@@ -21,6 +23,7 @@ Common options:
   --env <name>                (default: prod)
   --non-blocking <true|false> (default: true)
   --blocking                  (equivalent to --non-blocking false)
+  --output <field>            (default: json)
   --github-output <path>      (writes outputs for GitHub Actions)
 
 Trigger options:
@@ -56,6 +59,9 @@ function parseArgs(argv) {
     const key = token.slice(2);
     const next = argv[i + 1];
     if (!next || next.startsWith("--")) {
+      if (!BOOLEAN_FLAGS.has(key)) {
+        throw new Error(`Option --${key} requires a value`);
+      }
       options[key] = true;
       continue;
     }
@@ -97,6 +103,42 @@ function appendGithubOutput(filePath, pairs) {
   fs.appendFileSync(filePath, `${lines}\n`);
 }
 
+function resolveOutputValue(result, output) {
+  const mode = String(output || "json").trim();
+  if (!mode || mode === "json") {
+    return JSON.stringify(result);
+  }
+
+  const aliases = {
+    deployment_id: "deploymentId",
+    http_status: "httpStatus",
+  };
+  const path = (aliases[mode] || mode).split(".");
+
+  let current = result;
+  for (const segment of path) {
+    if (current === undefined || current === null) {
+      current = "";
+      break;
+    }
+    current = current[segment];
+  }
+
+  if (current === undefined || current === null) {
+    return "";
+  }
+
+  if (typeof current === "object") {
+    return JSON.stringify(current);
+  }
+
+  return String(current);
+}
+
+function printResult(result, output) {
+  console.log(sanitizeOutput(resolveOutputValue(result, output)));
+}
+
 function resolveNonBlocking(options) {
   if (options.blocking !== undefined) return false;
   if (options["non-blocking"] !== undefined) return parseBoolean(options["non-blocking"], true);
@@ -130,7 +172,7 @@ async function runTrigger(options) {
     http_status: result.httpStatus || "",
   });
 
-  console.log(JSON.stringify({ action: "trigger", ...result }));
+  printResult({ action: "trigger", ...result }, options.output);
 
   if (!result.ok && !clientConfig.nonBlocking) {
     process.exitCode = 1;
@@ -140,7 +182,12 @@ async function runTrigger(options) {
 async function runFinish(options) {
   const clientConfig = buildClient(options);
   const deploymentId = options["deployment-id"] || process.env.SEQPULSE_DEPLOYMENT_ID || "";
-  const jobStatus = options["job-status"] || process.env.JOB_STATUS || process.env.CI_JOB_STATUS || "success";
+  const jobStatus =
+    options["job-status"] ||
+    process.env.JOB_STATUS ||
+    process.env.CI_JOB_STATUS ||
+    process.env.BUILD_RESULT ||
+    "success";
   const resultValue = options.result || seqpulse.inferResultFromPipelineStatus(jobStatus);
 
   const client = seqpulse.createCIClient(clientConfig);
@@ -154,7 +201,7 @@ async function runFinish(options) {
     http_status: result.httpStatus || "",
   });
 
-  console.log(JSON.stringify({ action: "finish", ...result }));
+  printResult({ action: "finish", ...result }, options.output);
 
   if (!result.ok && !clientConfig.nonBlocking) {
     process.exitCode = 1;

package/index.js

@@ -228,9 +228,11 @@ function buildCiIdempotencyKey() {
 
 function inferBranchName() {
   return (
+    process.env.CHANGE_BRANCH ||
     process.env.GITHUB_REF_NAME ||
     process.env.CI_COMMIT_REF_NAME ||
     process.env.CIRCLE_BRANCH ||
+    process.env.GIT_BRANCH ||
     process.env.BRANCH_NAME ||
     "unknown"
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seqpulse",
-  "version": "0.4.0",
+  "version": "0.5.2",
   "description": "SeqPulse SDK for metrics endpoint instrumentation and HMAC validation",
   "main": "index.js",
   "types": "index.d.ts",
@@ -18,6 +18,7 @@
     "index.d.ts",
     "bin/seqpulse.js",
     "README.md",
+    "CI_CD_SNIPPETS_MULTI-PLATFORM.md",
     "LICENSE",
     "scripts/smoke.js"
   ],