seqpulse 0.3.0 → 0.4.0

package/README.md

@@ -3,7 +3,7 @@
 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
 
@@ -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,25 @@ 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
+npx -y seqpulse@0.4.0 ci trigger \
+  --env prod \
+  --github-output "$GITHUB_OUTPUT"
+
+# Finish
+npx -y seqpulse@0.4.0 ci finish \
+  --deployment-id "$SEQPULSE_DEPLOYMENT_ID" \
+  --job-status "$JOB_STATUS"
+```
+
+Notes:
+
+- `--github-output` ecrit `deployment_id`, `status`, `http_status`.
+- mode par defaut: non-bloquant (`--non-blocking true`).
+- pour mode strict: `--blocking`.
 
 ## Compatibility note
 
@@ -93,7 +107,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,200 @@
+#!/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)
+  --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 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 || "",
+  });
+
+  console.log(JSON.stringify({ action: "trigger", ...result }));
+
+  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 || "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 || "",
+  });
+
+  console.log(JSON.stringify({ action: "finish", ...result }));
+
+  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/package.json

@@ -1,9 +1,12 @@
 {
   "name": "seqpulse",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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,6 +16,7 @@
   "files": [
     "index.js",
     "index.d.ts",
+    "bin/seqpulse.js",
     "README.md",
     "LICENSE",
     "scripts/smoke.js"