@reportforge/playwright-pdf 0.8.1 → 0.9.0

package/dist/index.mjs

@@ -10485,6 +10485,21 @@ var captureConfigSchema = external_exports.object({
   maxSteps: external_exports.number().int().min(1).max(500).default(50),
   maxConsoleLines: external_exports.number().int().min(1).max(1e3).default(50)
 }).default({});
+var liveConfigSchema = external_exports.object({
+  enabled: external_exports.boolean().default(false),
+  // Override the auto-derived run id. All shards of one run must share it.
+  runId: external_exports.string().optional(),
+  // Override the streaming/server base URL (defaults to the license serverUrl).
+  serverUrl: external_exports.string().url().optional(),
+  // Step verbosity: 'none' skips steps, 'failed' streams intent + assertions +
+  // errored steps, 'all' streams every step.
+  steps: external_exports.enum(["none", "failed", "all"]).default("failed"),
+  // Stream test stdout/stderr tails. Off by default — may leak secrets printed
+  // by tests to a token-holder.
+  console: external_exports.boolean().default(false),
+  // Debounce window for batched flushes (ms).
+  flushMs: external_exports.number().int().min(500).max(1e4).default(2e3)
+}).default({});
 var sectionFlagsShape = Object.fromEntries(
   SECTION_KEYS.map((k) => [k, external_exports.boolean().optional()])
 );
@@ -10526,6 +10541,7 @@ var ReporterOptionsSchema = external_exports.object({
   slowTestThreshold: external_exports.number().int().min(0, "slowTestThreshold must be 0 or greater").optional().default(DEFAULT_OPTIONS.slowTestThreshold),
   failureAnalysis: failureAnalysisConfigSchema,
   capture: captureConfigSchema,
+  live: liveConfigSchema,
   templatePath: external_exports.union([
     external_exports.string().regex(/\.hbs$/, "templatePath must end with .hbs").refine((v) => v.slice(0, -4).trim().length > 0, "templatePath basename must not be empty"),
     external_exports.array(
@@ -10891,13 +10907,21 @@ var LicenseClient = class {
     this.autoUpdateModel = opts.autoUpdateModel ?? true;
     this.modelVersionForServer = this.autoUpdateModel ? opts.currentModelVersion ?? 0 : Number.MAX_SAFE_INTEGER;
   }
-  async resolve() {
+  /**
+   * @param opts.requireFeature  When set, a fresh cached JWT that does NOT carry
+   *   this feature is bypassed in favour of a network refresh — so a token issued
+   *   before the feature (e.g. `'live'`) was added to entitlements doesn't gate it
+   *   off until natural TTL expiry. If the refresh also lacks it, the caller gets
+   *   a LicenseInfo without the feature (genuinely not entitled).
+   */
+  async resolve(opts = {}) {
     const key = this.rawKey || process.env.RF_LICENSE_KEY?.trim();
     const init = this._validateKey(key);
     if (!init) return null;
     const { normalized, verifier } = init;
     const { cacheValid, cached, cacheFresh, nowMs } = this._readCache(verifier);
-    if (cacheFresh && cacheValid && cached) {
+    const cacheHasFeature = !opts.requireFeature || (cacheValid?.features?.includes(opts.requireFeature) ?? false);
+    if (cacheFresh && cacheValid && cached && cacheHasFeature) {
       logger.debug("license path=jwt-cache", {
         exp: new Date(cacheValid.exp * 1e3).toISOString(),
         machinesUsed: cached.machinesUsed,
@@ -10962,7 +10986,8 @@ var LicenseClient = class {
         lastRefresh: Math.floor(Date.now() / 1e3),
         fingerprintHash: this.fingerprint.hash,
         machinesUsed: result.machinesUsed,
-        machineLimit: result.machineLimit
+        machineLimit: result.machineLimit,
+        features: payload.features
       };
       writeCache(entry);
       logger.debug(`license path=${cached ? "refresh" : "activate"} response`, {
@@ -10980,7 +11005,8 @@ var LicenseClient = class {
         jwt: result.jwt,
         expiry: new Date(payload.exp * 1e3),
         machinesUsed: result.machinesUsed,
-        machineLimit: result.machineLimit
+        machineLimit: result.machineLimit,
+        features: payload.features
       };
     } catch (err) {
       const msg = err.message;
@@ -11068,7 +11094,11 @@ function toLicenseInfo(payload, cached, normalizedKey, source) {
     // caches written by older reporter versions before these fields were
     // persisted (the next refresh will populate them).
     machinesUsed: cached.machinesUsed,
-    machineLimit: cached.machineLimit
+    machineLimit: cached.machineLimit,
+    // Prefer the signed `features` claim (authenticated) over the unauthenticated
+    // sidecar — falls back to the sidecar only for caches written before the
+    // payload was threaded through here.
+    features: payload.features ?? cached.features
   };
 }
 function normalizeUrl(url) {
@@ -11687,6 +11717,7 @@ function sortBySeverity(failures) {
 // src/utils/env.ts
 init_esm_shims();
 import { execSync } from "child_process";
+import { createHmac as createHmac2 } from "crypto";
 var COMMIT_HASH_LENGTH = 8;
 function detectCiEnv() {
   const env = process.env;
@@ -11757,6 +11788,34 @@ function detectCiEnv() {
     ciProvider: "local"
   };
 }
+var CI_RUN_SOURCES = [
+  { provider: "github.com", repoKeys: ["GITHUB_REPOSITORY"], runKeys: ["GITHUB_RUN_ID"], attemptKeys: ["GITHUB_RUN_ATTEMPT"] },
+  { provider: "gitlab.com", repoKeys: ["CI_PROJECT_PATH"], runKeys: ["CI_PIPELINE_ID"] },
+  { provider: "circleci.com", repoKeys: ["CIRCLE_PROJECT_REPONAME"], runKeys: ["CIRCLE_WORKFLOW_ID"] },
+  { provider: "buildkite.com", repoKeys: ["BUILDKITE_REPO"], runKeys: ["BUILDKITE_BUILD_ID"] },
+  { provider: "dev.azure.com", repoKeys: ["BUILD_REPOSITORY_NAME"], runKeys: ["BUILD_BUILDID"] },
+  { provider: "bitbucket.org", repoKeys: ["BITBUCKET_REPO_FULL_NAME"], runKeys: ["BITBUCKET_PIPELINE_UUID"] },
+  { provider: "jenkins", repoKeys: ["JOB_NAME"], runKeys: ["BUILD_NUMBER"] }
+];
+var RUN_ID_FALLBACK_SECRET = "rf-live-runid";
+function detectCiRunId() {
+  for (const src of CI_RUN_SOURCES) {
+    const runId = firstEnv(src.runKeys);
+    if (!runId) continue;
+    const repo = firstEnv(src.repoKeys) ?? "unknown";
+    const attempt = src.attemptKeys ? firstEnv(src.attemptKeys) ?? "1" : "1";
+    const secret = process.env.RF_LICENSE_KEY?.trim() || RUN_ID_FALLBACK_SECRET;
+    return createHmac2("sha256", secret).update(`${src.provider}:${repo}:${runId}:${attempt}`).digest("hex").slice(0, 32);
+  }
+  return null;
+}
+function firstEnv(keys) {
+  for (const k of keys) {
+    const v = process.env[k]?.trim();
+    if (v) return v;
+  }
+  return void 0;
+}
 function gitBranch() {
   try {
     return execSync("git rev-parse --abbrev-ref HEAD", { stdio: "pipe" }).toString().trim();
@@ -13489,14 +13548,313 @@ var NotificationSender = class {
   }
 };
 
+// src/live/LiveStreamer.ts
+init_esm_shims();
+var NETWORK_TIMEOUT_MS2 = 8e3;
+var LIVE_DRAIN_DEADLINE_MS = 1e4;
+var MAX_FLUSH_MS = 3e4;
+var WARN_THROTTLE_MS = 3e4;
+var LiveStreamer = class {
+  constructor(config) {
+    this.config = config;
+    this.testBuffer = [];
+    this.eventBuffer = [];
+    /** Monotonic per-shard event counter → stable `{shardKey}:{seq}` event ids. */
+    this.eventSeq = 0;
+    /**
+     * Latest status per test id (last write wins), so retries don't inflate the
+     * tallies: a flaky test that fails then passes is one entry, counted once.
+     * Counts are derived from this map, matching the collector/PDF semantics.
+     */
+    this.testStates = /* @__PURE__ */ new Map();
+    this.flushTimer = null;
+    this.inFlight = /* @__PURE__ */ new Set();
+    this.enabled = true;
+    this.gated = false;
+    this.gatePromise = null;
+    this.jwt = null;
+    this.envSent = false;
+    this.lastWarnMs = 0;
+    this.serverUrl = config.serverUrl.endsWith("/") ? config.serverUrl.slice(0, -1) : config.serverUrl;
+    this.flushMs = config.flushMs ?? 2e3;
+    this.flushMaxBatch = config.maxBatch ?? 100;
+    this.maxInFlight = config.maxInFlight ?? 4;
+    this.maxPreLicenseBuffer = config.maxPreLicenseBuffer ?? 2e3;
+  }
+  enqueueTest(update) {
+    if (!this.enabled) return;
+    this.testStates.set(update.id, { status: update.status, retry: update.retry });
+    this.testBuffer.push(update);
+    this.capPreLicenseBuffer();
+    this.scheduleFlush();
+  }
+  enqueueEvent(event) {
+    if (!this.enabled) return;
+    event.id = `${this.config.shardKey}:${this.eventSeq++}`;
+    this.eventBuffer.push(event);
+    this.capPreLicenseBuffer();
+    this.scheduleFlush();
+  }
+  /**
+   * Final flush: cancels the pending timer, emits the terminal `finished` batch,
+   * then awaits in-flight requests bounded by LIVE_DRAIN_DEADLINE_MS. Called from
+   * the reporter's `onExit`. The bound is the #16644 fix — a hung server cannot
+   * hold the process open past the deadline.
+   */
+  async drain() {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flush("finished");
+    await Promise.race([
+      Promise.allSettled([...this.inFlight]),
+      sleep(LIVE_DRAIN_DEADLINE_MS)
+    ]);
+  }
+  // ─── internals ────────────────────────────────────────────────────────────
+  snapshotCounts() {
+    const c = {
+      total: this.testStates.size,
+      running: 0,
+      passed: 0,
+      failed: 0,
+      timedOut: 0,
+      skipped: 0,
+      flaky: 0
+    };
+    for (const { status, retry } of this.testStates.values()) {
+      switch (status) {
+        case "running":
+          c.running++;
+          break;
+        case "passed":
+          retry && retry > 0 ? c.flaky++ : c.passed++;
+          break;
+        case "failed":
+          c.failed++;
+          break;
+        case "timedOut":
+          c.timedOut++;
+          break;
+        case "skipped":
+          c.skipped++;
+          break;
+        case "interrupted":
+          c.failed++;
+          break;
+      }
+    }
+    return c;
+  }
+  /** Drop-oldest cap on buffered items while the license gate is still pending. */
+  capPreLicenseBuffer() {
+    if (this.gated) return;
+    let overflow = this.testBuffer.length + this.eventBuffer.length - this.maxPreLicenseBuffer;
+    if (overflow <= 0) return;
+    const dropEvents = Math.min(overflow, this.eventBuffer.length);
+    if (dropEvents > 0) this.eventBuffer.splice(0, dropEvents);
+    overflow -= dropEvents;
+    if (overflow > 0) this.testBuffer.splice(0, overflow);
+  }
+  scheduleFlush() {
+    if (this.testBuffer.length + this.eventBuffer.length >= this.flushMaxBatch) {
+      void this.flush("running");
+      return;
+    }
+    if (this.flushTimer) return;
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      void this.flush("running");
+    }, this.flushMs);
+    if (typeof this.flushTimer.unref === "function") this.flushTimer.unref();
+  }
+  async flush(status) {
+    if (!this.enabled) return;
+    const entitled = await this.ensureGate();
+    if (!entitled) return;
+    if (status !== "finished" && this.inFlight.size >= this.maxInFlight) return;
+    const tests = this.testBuffer;
+    const events = this.eventBuffer;
+    if (status !== "finished" && tests.length === 0 && events.length === 0) return;
+    this.testBuffer = [];
+    this.eventBuffer = [];
+    const body = {
+      runId: this.config.runId,
+      shardKey: this.config.shardKey,
+      shardTotal: this.config.shardTotal,
+      status,
+      counts: this.snapshotCounts(),
+      tests,
+      events,
+      // Keep attaching env until a send actually succeeds (envSent flips in
+      // send()), so a failed first request doesn't lose the run's CI context.
+      ...this.envSent ? {} : { env: this.config.env }
+    };
+    const p = this.send(body).finally(() => {
+      this.inFlight.delete(p);
+    });
+    this.inFlight.add(p);
+  }
+  /** Runs the license entitlement check exactly once, memoized. */
+  ensureGate() {
+    return this.gatePromise ?? (this.gatePromise = this.runGate());
+  }
+  async runGate() {
+    let info = null;
+    try {
+      info = await this.config.license();
+    } catch {
+      info = null;
+    }
+    this.gated = true;
+    const features = info?.features ?? [];
+    if (!info || !info.jwt || !features.includes("live")) {
+      this.enabled = false;
+      this.testBuffer = [];
+      this.eventBuffer = [];
+      this.warn("Live streaming disabled \u2014 no active license or live entitlement.");
+      return false;
+    }
+    this.jwt = info.jwt;
+    if (this.config.watchUrl) logger.info(`Live results: ${this.config.watchUrl}`);
+    return true;
+  }
+  async send(body) {
+    if (!this.jwt) return;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), NETWORK_TIMEOUT_MS2);
+    try {
+      const res = await fetch(`${this.serverUrl}/api/live/ingest`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.jwt}`
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      await res.body?.cancel().catch(() => {
+      });
+      if (res.status === 429) {
+        this.flushMs = Math.min(this.flushMs * 2, MAX_FLUSH_MS);
+        return;
+      }
+      if (!res.ok) {
+        this.warn(`Live ingest returned HTTP ${res.status}.`);
+        return;
+      }
+      if (body.env) this.envSent = true;
+    } catch (err) {
+      this.warn(`Live ingest request failed: ${err.message}`);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  warn(msg) {
+    const now = Date.now();
+    if (now - this.lastWarnMs < WARN_THROTTLE_MS) return;
+    this.lastWarnMs = now;
+    logger.warn(msg);
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    if (typeof t.unref === "function") t.unref();
+  });
+}
+
+// src/live/runId.ts
+init_esm_shims();
+import { createHmac as createHmac3 } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
+var WATCH_TOKEN_HEX_LEN = 32;
+function deriveRunId(opts) {
+  const explicit = opts.runId?.trim();
+  if (explicit) return explicit;
+  const fromEnv = process.env.RF_LIVE_RUN_ID?.trim();
+  if (fromEnv) return fromEnv;
+  return detectCiRunId() ?? randomUUID2();
+}
+function computeWatchToken(runId) {
+  const secret = process.env.RF_LICENSE_KEY?.trim();
+  if (!secret) return null;
+  return createHmac3("sha256", secret).update(`live:${runId}`).digest("hex").slice(0, WATCH_TOKEN_HEX_LEN);
+}
+function buildWatchUrl(serverUrl, runId, token) {
+  const base = serverUrl.endsWith("/") ? serverUrl.slice(0, -1) : serverUrl;
+  return `${base}/live/${encodeURIComponent(runId)}?t=${encodeURIComponent(token)}`;
+}
+function shardKeyOf(shard) {
+  if (!shard || !shard.total) return "1/1";
+  return `${shard.current}/${shard.total}`;
+}
+
+// src/live/event-map.ts
+init_esm_shims();
+var MAX_TITLE_CHARS2 = 200;
+var MAX_STEP_TITLE_CHARS = 200;
+var MAX_CONSOLE_CHARS = 2048;
+function mapTestBegin(test, shardKey) {
+  return {
+    id: test.id,
+    title: clampWithEllipsis(test.title ?? "", MAX_TITLE_CHARS2),
+    status: "running",
+    shardKey
+  };
+}
+function mapTestEnd(test, result, shardKey) {
+  return {
+    id: test.id,
+    status: result.status,
+    durationMs: result.duration,
+    retry: result.retry,
+    shardKey
+  };
+}
+function shouldEmitStep(step, mode) {
+  if (mode === "none") return false;
+  if (!step.title) return false;
+  if (mode === "all") return true;
+  if (step.error) return true;
+  return step.category === "test.step" || step.category === "expect";
+}
+function mapStep(testId, step, phase, shardKey) {
+  return {
+    kind: "step",
+    testId,
+    title: clampWithEllipsis(step.title ?? "", MAX_STEP_TITLE_CHARS),
+    status: phase === "begin" ? "running" : step.error ? "failed" : "passed",
+    shardKey,
+    at: Date.now()
+  };
+}
+function mapConsole(kind, chunk, testId, shardKey) {
+  return {
+    kind,
+    testId,
+    text: clampWithEllipsis(chunkToString2(chunk), MAX_CONSOLE_CHARS),
+    shardKey,
+    at: Date.now()
+  };
+}
+function chunkToString2(chunk) {
+  return typeof chunk === "string" ? chunk : chunk.toString("utf8");
+}
+
 // src/reporter.ts
+var DEFAULT_SERVER_URL2 = "https://reportforge.org";
 var PdfReporter = class {
   constructor(rawOptions = {}) {
     this.cwd = process.cwd();
     this.pdfGenerator = new PdfGenerator();
+    this.liveShardKey = "1/1";
+    this.liveSteps = "failed";
+    this.liveConsole = false;
     this.options = parseOptions(rawOptions);
     this.dataCollector = new DataCollector(this.options.capture);
-    const version = true ? "0.8.1" : "0.x";
+    const version = true ? "0.9.0" : "0.x";
     logger.info(`@reportforge/playwright-pdf v${version} initialised`);
     this.licenseClient = new LicenseClient({
       licenseKey: this.options.licenseKey,
@@ -13507,12 +13865,65 @@ var PdfReporter = class {
   }
   onBegin(config, suite) {
     this.dataCollector.onBegin(config, suite);
+    if (!this.options.live.enabled) return;
+    try {
+      this.setupLive(config);
+    } catch (err) {
+      logger.warn(`Live setup failed \u2014 streaming disabled: ${err.message}`);
+    }
+  }
+  onTestBegin(test) {
+    if (!this.liveStreamer) return;
+    try {
+      this.liveStreamer.enqueueTest(mapTestBegin(test, this.liveShardKey));
+    } catch {
+    }
   }
   onTestEnd(test, result) {
     this.dataCollector.onTestEnd(test, result);
+    if (!this.liveStreamer) return;
+    try {
+      this.liveStreamer.enqueueTest(mapTestEnd(test, result, this.liveShardKey));
+    } catch {
+    }
+  }
+  onStepBegin(test, _result, step) {
+    if (!this.liveStreamer || !shouldEmitStep(step, this.liveSteps)) return;
+    try {
+      this.liveStreamer.enqueueEvent(mapStep(test.id, step, "begin", this.liveShardKey));
+    } catch {
+    }
+  }
+  onStepEnd(test, _result, step) {
+    if (!this.liveStreamer || !shouldEmitStep(step, this.liveSteps)) return;
+    try {
+      this.liveStreamer.enqueueEvent(mapStep(test.id, step, "end", this.liveShardKey));
+    } catch {
+    }
+  }
+  onStdOut(chunk, test) {
+    if (!this.liveStreamer || !this.liveConsole) return;
+    try {
+      this.liveStreamer.enqueueEvent(mapConsole("stdout", chunk, test?.id, this.liveShardKey));
+    } catch {
+    }
+  }
+  onStdErr(chunk, test) {
+    if (!this.liveStreamer || !this.liveConsole) return;
+    try {
+      this.liveStreamer.enqueueEvent(mapConsole("stderr", chunk, test?.id, this.liveShardKey));
+    } catch {
+    }
+  }
+  async onExit() {
+    if (!this.liveStreamer) return;
+    try {
+      await this.liveStreamer.drain();
+    } catch {
+    }
   }
   async onEnd(result) {
-    const licenseInfo = await this.resolveLicense();
+    const licenseInfo = await this.license();
     if (!licenseInfo) return;
     const collected = this._collectData(result);
     if (!collected) return;
@@ -13619,9 +14030,18 @@ var PdfReporter = class {
   printsToStdio() {
     return false;
   }
+  /**
+   * Memoized license resolution shared by the live stream (kicked early in
+   * onBegin) and PDF generation (awaited in onEnd) — at most one network trip.
+   */
+  license() {
+    return this.licensePromise ?? (this.licensePromise = this.resolveLicense());
+  }
   async resolveLicense() {
     try {
-      return await this.licenseClient.resolve();
+      return await this.licenseClient.resolve(
+        this.options.live.enabled ? { requireFeature: "live" } : {}
+      );
     } catch (err) {
       logger.warn(
         `License resolution errored: ${err.message}. PDF generation skipped.`
@@ -13629,6 +14049,33 @@ var PdfReporter = class {
       return null;
     }
   }
+  /**
+   * Wires up live streaming: derives the run id (shared by all shards), kicks
+   * the license resolution early, builds the streamer, and prints the watch
+   * link to the CI logs. Throws are caught by the onBegin try/catch.
+   */
+  setupLive(config) {
+    const live = this.options.live;
+    const runId = deriveRunId({ runId: live.runId });
+    const serverUrl = live.serverUrl ?? this.options.serverUrl ?? process.env.REPORTFORGE_SERVER_URL ?? DEFAULT_SERVER_URL2;
+    const shard = config.shard ?? null;
+    this.liveShardKey = shardKeyOf(shard);
+    this.liveSteps = live.steps;
+    this.liveConsole = live.console;
+    void this.license();
+    const token = computeWatchToken(runId);
+    const watchUrl = token ? buildWatchUrl(serverUrl, runId, token) : void 0;
+    this.liveStreamer = new LiveStreamer({
+      serverUrl,
+      runId,
+      shardKey: this.liveShardKey,
+      shardTotal: shard?.total ?? null,
+      license: () => this.license(),
+      env: detectCiEnv(),
+      watchUrl,
+      flushMs: live.flushMs
+    });
+  }
   resolveProjectName() {
     try {
       const pkgPath = path14.resolve(process.cwd(), "package.json");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reportforge/playwright-pdf",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Enterprise-ready PDF reports for Playwright Test — minimal, detailed, and executive templates with CI/CD integrations",
   "license": "MIT",
   "author": "ReportForge",