@reportforge/playwright-pdf 0.8.1 → 0.10.0

package/dist/index.js

@@ -10484,6 +10484,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()])
 );
@@ -10525,6 +10540,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(
@@ -10890,13 +10906,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,
@@ -10961,7 +10985,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`, {
@@ -10979,7 +11004,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;
@@ -11067,7 +11093,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) {
@@ -11686,6 +11716,7 @@ function sortBySeverity(failures) {
 // src/utils/env.ts
 init_cjs_shims();
 var import_child_process = require("child_process");
+var import_crypto5 = require("crypto");
 var COMMIT_HASH_LENGTH = 8;
 function detectCiEnv() {
   const env = process.env;
@@ -11756,6 +11787,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 (0, import_crypto5.createHmac)("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 (0, import_child_process.execSync)("git rev-parse --abbrev-ref HEAD", { stdio: "pipe" }).toString().trim();
@@ -12678,11 +12737,11 @@ init_cjs_shims();
 var import_fs7 = __toESM(require("fs"));
 var import_os4 = __toESM(require("os"));
 var import_path4 = __toESM(require("path"));
-var import_crypto5 = __toESM(require("crypto"));
+var import_crypto6 = __toESM(require("crypto"));
 var HtmlWriter = class {
   async write(html) {
     const tmpDir = import_os4.default.tmpdir();
-    const filename = `rf-report-${import_crypto5.default.randomBytes(8).toString("hex")}.html`;
+    const filename = `rf-report-${import_crypto6.default.randomBytes(8).toString("hex")}.html`;
     this.tempPath = import_path4.default.join(tmpDir, filename);
     await import_fs7.default.promises.writeFile(this.tempPath, html, "utf8");
     return this.tempPath;
@@ -12726,7 +12785,7 @@ var import_child_process3 = require("child_process");
 var import_fs8 = __toESM(require("fs"));
 var import_path5 = __toESM(require("path"));
 var import_os5 = __toESM(require("os"));
-var import_crypto6 = __toESM(require("crypto"));
+var import_crypto7 = __toESM(require("crypto"));
 var PdfEncryptor = class {
   async encrypt(pdfPath, password) {
     if (!password) return;
@@ -12737,7 +12796,7 @@ var PdfEncryptor = class {
       return;
     }
     const tmpPath = import_path5.default.join(import_os5.default.tmpdir(), `rf-encrypted-${Date.now()}.pdf`);
-    const pwFile = import_path5.default.join(import_os5.default.tmpdir(), `rf-pw-${import_crypto6.default.randomBytes(8).toString("hex")}`);
+    const pwFile = import_path5.default.join(import_os5.default.tmpdir(), `rf-pw-${import_crypto7.default.randomBytes(8).toString("hex")}`);
     try {
       import_fs8.default.writeFileSync(pwFile, `${password}
 ${password}`, { mode: 384 });
@@ -13260,6 +13319,22 @@ _${name}_`
 
 // src/notify/formatters/teams.ts
 init_cjs_shims();
+function buildTeamsSimpleMessage(text) {
+  return {
+    type: "message",
+    attachments: [
+      {
+        contentType: "application/vnd.microsoft.card.adaptive",
+        content: {
+          $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
+          type: "AdaptiveCard",
+          version: "1.4",
+          body: [{ type: "TextBlock", text, wrap: true }]
+        }
+      }
+    ]
+  };
+}
 function buildTeamsPayload(stats, pdfPaths, reportTitle) {
   const label = statusLabel(stats.verdict);
   const name = reportName(pdfPaths, reportTitle);
@@ -13466,6 +13541,30 @@ var NotificationSender = class {
     }
     return result;
   }
+  /**
+   * Fire-and-forget "live run started" ping to the enabled chat channels, carrying
+   * the watch URL so teammates can open the live view without hunting through CI
+   * logs. Only channels with `on: 'always'` receive it — a start ping has no
+   * pass/fail outcome, so a `failure`/`success`-only channel is left alone. Never
+   * touches the email channel (too heavy for a start signal). Resolves even if
+   * every post fails; live is best-effort.
+   */
+  async sendLiveStarted(notifyConfig, watchUrl, branch) {
+    if (!notifyConfig) return;
+    const line = `ReportForge: live test run started${branch ? ` on ${branch}` : ""}. Watch: ${watchUrl}`;
+    const payloads = {
+      slack: { text: line },
+      teams: buildTeamsSimpleMessage(line),
+      discord: { content: line }
+    };
+    await Promise.allSettled(
+      Object.keys(payloads).map((name) => {
+        const channel = notifyConfig[name];
+        if (!channel || !channel.enabled || channel.on !== "always") return Promise.resolve();
+        return this.post(`${name} (live-start)`, channel.url, payloads[name]);
+      })
+    );
+  }
   async post(name, url, payload, result) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), 1e4);
@@ -13478,24 +13577,341 @@ var NotificationSender = class {
       });
       if (!res.ok) throw new Error(`HTTP ${res.status}`);
       logger.info(`[notify] ${name}: sent`);
-      result.sent.push(name);
+      result?.sent.push(name);
     } catch (err) {
       logger.warn(`[notify] ${name}: ${err instanceof Error ? err.message : String(err)}`);
-      result.failed.push(name);
+      result?.failed.push(name);
     } finally {
       clearTimeout(timeoutId);
     }
   }
 };
 
+// src/live/LiveStreamer.ts
+init_cjs_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;
+    const prevRetry = this.testStates.get(update.id)?.retry;
+    this.testStates.set(update.id, { status: update.status, retry: update.retry ?? prevRetry });
+    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;
+    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_cjs_shims();
+var import_crypto8 = require("crypto");
+var import_crypto9 = require("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() ?? (0, import_crypto9.randomUUID)();
+}
+function computeWatchToken(runId) {
+  const secret = process.env.RF_LICENSE_KEY?.trim();
+  if (!secret) return null;
+  return (0, import_crypto8.createHmac)("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 formatLiveBanner(url) {
+  const label = "Live Tracker";
+  const link = `Watch live: ${url}`;
+  const width = Math.max(label.length, link.length);
+  const rule = "\u2500".repeat(width + 2);
+  return [rule, ` ${label.padEnd(width)} `, ` ${link.padEnd(width)} `, rule].join("\n");
+}
+function shardKeyOf(shard) {
+  if (!shard || !shard.total) return "1/1";
+  return `${shard.current}/${shard.total}`;
+}
+
+// src/live/event-map.ts
+init_cjs_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 isCurrentStep(step) {
+  return step.category === "test.step" && !!step.title;
+}
+function mapCurrentStep(testId, step, shardKey) {
+  return {
+    id: testId,
+    status: "running",
+    shardKey,
+    currentStep: clampWithEllipsis(step.title ?? "", MAX_STEP_TITLE_CHARS)
+  };
+}
+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.10.0" : "0.x";
     logger.info(`@reportforge/playwright-pdf v${version} initialised`);
     this.licenseClient = new LicenseClient({
       licenseKey: this.options.licenseKey,
@@ -13506,12 +13922,70 @@ 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) return;
+    try {
+      if (this.liveSteps !== "none" && isCurrentStep(step)) {
+        this.liveStreamer.enqueueTest(mapCurrentStep(test.id, step, this.liveShardKey));
+      }
+      if (shouldEmitStep(step, this.liveSteps)) {
+        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;
@@ -13618,9 +14092,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.`
@@ -13628,6 +14111,54 @@ 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;
+    const env = detectCiEnv();
+    if (watchUrl) void this.announceLive(watchUrl, env, shard).catch(() => {
+    });
+    this.liveStreamer = new LiveStreamer({
+      serverUrl,
+      runId,
+      shardKey: this.liveShardKey,
+      shardTotal: shard?.total ?? null,
+      license: () => this.license(),
+      env,
+      flushMs: live.flushMs
+    });
+  }
+  /**
+   * Announces the watch link once the run is confirmed live-entitled. Gating on
+   * the SAME resolved entitlement the streamer requires (`jwt` + the `'live'`
+   * feature) guarantees the link is never printed or posted for a run that will
+   * never stream — no dead links. The chat ping fires from the primary shard only
+   * (unsharded, or `shard.current === 1`) so an N-way matrix posts one message,
+   * not N. The banner still prints from every shard's own log.
+   */
+  async announceLive(watchUrl, env, shard) {
+    const info = await this.license();
+    if (!info?.jwt || !info.features?.includes("live")) return;
+    logger.info(`Live Tracker: ${watchUrl}`);
+    console.log(formatLiveBanner(watchUrl));
+    const isPrimaryShard = !shard || shard.current === 1;
+    const notify = this.options.notify;
+    if (isPrimaryShard && notify) {
+      await new NotificationSender().sendLiveStarted(notify, watchUrl, env?.branch);
+    }
+  }
   resolveProjectName() {
     try {
       const pkgPath = import_path12.default.resolve(process.cwd(), "package.json");