seqpulse 0.3.0 → 0.5.1

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 `@nassir_gouomba/seqpulse@0.5.0` 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 @nassir_gouomba/seqpulse@0.5.0 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 @nassir_gouomba/seqpulse@0.5.0 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 @nassir_gouomba/seqpulse@0.5.0 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 @nassir_gouomba/seqpulse@0.5.0 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 @nassir_gouomba/seqpulse@0.5.0 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 @nassir_gouomba/seqpulse@0.5.0 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 @nassir_gouomba/seqpulse@0.5.0 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 @nassir_gouomba/seqpulse@0.5.0 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 @nassir_gouomba/seqpulse@0.5.0` 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

@@ -3,21 +3,21 @@
 SeqPulse Node SDK couvre deux usages:
 
 - Runtime application: instrumentation HTTP + endpoint metrics + validation HMAC v2
-- CI/CD integration: client `trigger/finish` pour orchestrer un deployment SeqPulse
+- CI/CD integration: client `trigger/finish` + CLI `seqpulse ci ...`
 
 ## Install
 
 ```bash
-npm install seqpulse
+npm install @nassir_gouomba/seqpulse
 # or
-pnpm add seqpulse
+pnpm add @nassir_gouomba/seqpulse
 ```
 
 ## Runtime (Express)
 
 ```js
 const express = require("express");
-const seqpulse = require("seqpulse");
+const seqpulse = require("@nassir_gouomba/seqpulse");
 
 const app = express();
 
@@ -53,7 +53,7 @@ app.listen(3000, () => {
 ## CI/CD client (trigger/finish)
 
 ```js
-const seqpulse = require("seqpulse");
+const seqpulse = require("@nassir_gouomba/seqpulse");
 
 const client = seqpulse.createCIClient({
   baseUrl: process.env.SEQPULSE_BASE_URL,
@@ -66,7 +66,7 @@ const client = seqpulse.createCIClient({
 async function runDeployment() {
   const trigger = await client.trigger({
     branch: process.env.GITHUB_REF_NAME,
-    idempotencyKey: `gha-${process.env.GITHUB_RUN_ID}-${process.env.GITHUB_RUN_ATTEMPT}`,
+    idempotencyKey: seqpulse.buildCiIdempotencyKey(),
   });
 
   // Deploy your app here...
@@ -81,11 +81,30 @@ async function runDeployment() {
 }
 ```
 
-### CI behavior
+## CI/CD CLI (short YAML)
 
-- `nonBlocking: true` (default): returns a skipped/error result instead of throwing.
-- `nonBlocking: false`: throws on API/config errors.
-- idempotency key helper available: `seqpulse.buildCiIdempotencyKey()`.
+```bash
+# Trigger
+DEPLOYMENT_ID="$(npx -y @nassir_gouomba/seqpulse@0.5.0 ci trigger \
+  --env prod \
+  --output deploymentId)"
+
+# Finish
+npx -y @nassir_gouomba/seqpulse@0.5.0 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
 
@@ -93,7 +112,7 @@ Cette evolution **n'ecrase pas** le SDK runtime actuel:
 
 - l'endpoint `/seqpulse-metrics` reste le meme
 - la logique HMAC runtime reste la meme
-- le client CI est ajoute en couche supplementaire
+- la CLI CI est une surcouche du client SDK existant
 
 ## Local smoke test
 

package/bin/seqpulse.js

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const seqpulse = require("../index.js");
+
+function printUsage() {
+  console.error(`Usage:
+  seqpulse ci trigger [options]
+  seqpulse ci finish [options]
+
+Commands:
+  ci trigger   Trigger SeqPulse deployment in CI
+  ci finish    Finish SeqPulse deployment in CI
+
+Common options:
+  --base-url <url>
+  --api-key <key>
+  --metrics-endpoint <url>
+  --timeout-ms <number>
+  --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:
+  --branch <name>
+  --idempotency-key <key>
+
+Finish options:
+  --deployment-id <id>
+  --result <success|failed>
+  --job-status <status>
+`);
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  const options = {};
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith("--")) {
+      positional.push(token);
+      continue;
+    }
+
+    const eq = token.indexOf("=");
+    if (eq > -1) {
+      const key = token.slice(2, eq);
+      const value = token.slice(eq + 1);
+      options[key] = value;
+      continue;
+    }
+
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith("--")) {
+      options[key] = true;
+      continue;
+    }
+
+    options[key] = next;
+    i += 1;
+  }
+
+  return { positional, options };
+}
+
+function parseBoolean(value, defaultValue) {
+  if (value === undefined) return defaultValue;
+  if (typeof value === "boolean") return value;
+  const normalized = String(value).trim().toLowerCase();
+  if (["1", "true", "yes", "y", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "n", "off"].includes(normalized)) return false;
+  throw new Error(`Invalid boolean value: ${value}`);
+}
+
+function parseNumber(value, defaultValue) {
+  if (value === undefined) return defaultValue;
+  const num = Number(value);
+  if (!Number.isFinite(num) || num <= 0) {
+    throw new Error(`Invalid numeric value: ${value}`);
+  }
+  return num;
+}
+
+function sanitizeOutput(value) {
+  return String(value === undefined || value === null ? "" : value).replace(/[\r\n]/g, "");
+}
+
+function appendGithubOutput(filePath, pairs) {
+  if (!filePath) return;
+  const lines = Object.entries(pairs)
+    .map(([k, v]) => `${k}=${sanitizeOutput(v)}`)
+    .join("\n");
+  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);
+  if (options.nonblocking !== undefined) return parseBoolean(options.nonblocking, true);
+  return true;
+}
+
+function buildClient(options) {
+  return {
+    baseUrl: options["base-url"],
+    apiKey: options["api-key"],
+    metricsEndpoint: options["metrics-endpoint"],
+    env: options.env || "prod",
+    timeoutMs: parseNumber(options["timeout-ms"], undefined),
+    nonBlocking: resolveNonBlocking(options),
+  };
+}
+
+async function runTrigger(options) {
+  const clientConfig = buildClient(options);
+  const client = seqpulse.createCIClient(clientConfig);
+  const result = await client.trigger({
+    env: options.env || clientConfig.env || "prod",
+    branch: options.branch,
+    idempotencyKey: options["idempotency-key"] || seqpulse.buildCiIdempotencyKey(),
+  });
+
+  appendGithubOutput(options["github-output"], {
+    deployment_id: result.ok ? result.deploymentId || "" : "",
+    status: result.status || result.error || "",
+    http_status: result.httpStatus || "",
+  });
+
+  printResult({ action: "trigger", ...result }, options.output);
+
+  if (!result.ok && !clientConfig.nonBlocking) {
+    process.exitCode = 1;
+  }
+}
+
+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 ||
+    process.env.BUILD_RESULT ||
+    "success";
+  const resultValue = options.result || seqpulse.inferResultFromPipelineStatus(jobStatus);
+
+  const client = seqpulse.createCIClient(clientConfig);
+  const result = await client.finish({
+    deploymentId,
+    result: resultValue,
+  });
+
+  appendGithubOutput(options["github-output"], {
+    status: result.status || result.error || "",
+    http_status: result.httpStatus || "",
+  });
+
+  printResult({ action: "finish", ...result }, options.output);
+
+  if (!result.ok && !clientConfig.nonBlocking) {
+    process.exitCode = 1;
+  }
+}
+
+async function main() {
+  const { positional, options } = parseArgs(process.argv.slice(2));
+  const [scope, command] = positional;
+
+  if (options.help || options.h) {
+    printUsage();
+    process.exit(0);
+    return;
+  }
+
+  if (!scope || !command) {
+    printUsage();
+    process.exit(1);
+    return;
+  }
+
+  if (scope !== "ci") {
+    throw new Error(`Unsupported scope: ${scope}`);
+  }
+
+  if (command === "trigger") {
+    await runTrigger(options);
+    return;
+  }
+
+  if (command === "finish") {
+    await runFinish(options);
+    return;
+  }
+
+  throw new Error(`Unsupported command: ${command}`);
+}
+
+main().catch((error) => {
+  console.error(`[seqpulse] ${error && error.message ? error.message : String(error)}`);
+  process.exit(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,9 +1,12 @@
 {
   "name": "seqpulse",
-  "version": "0.3.0",
+  "version": "0.5.1",
   "description": "SeqPulse SDK for metrics endpoint instrumentation and HMAC validation",
   "main": "index.js",
   "types": "index.d.ts",
+  "bin": {
+    "seqpulse": "bin/seqpulse.js"
+  },
   "exports": {
     ".": {
       "require": "./index.js",
@@ -13,7 +16,9 @@
   "files": [
     "index.js",
     "index.d.ts",
+    "bin/seqpulse.js",
     "README.md",
+    "CI_CD_SNIPPETS_MULTI-PLATFORM.md",
     "LICENSE",
     "scripts/smoke.js"
   ],