fix(cf): scope-bound solvedCFTargetIds lifecycle and Docker build fix (#125)

* build: add commitlint for structured commit message validation

* build: upgrade vite 8 + vitest 4.1, add prom-client as explicit dep

- Upgrade vite ^7.3.1 → ^8.0.0 and vitest ^4.0.18 → ^4.1.0
- Add prom-client ^15.1.3 as explicit dependency (was phantom dep
  that got de-hoisted when commitlint was added, causing silent
  server crash on startup)

* fix(cf): scope-bound solvedCFTargetIds lifecycle and Docker build fix

- Replace raw Set.add with scope-bound addSolvedCFTarget that auto-cleans
  entries when owning page is destroyed, preventing unbounded growth
- Add page cleanup scopes to CloudflareStateTracker with proper finalizers
- Add startup failure diagnostics to vitest integration globalSetup
- Fix Docker build: add --ignore-scripts to npm clean-install (lefthook)

Author: DivMode

docker/base/Dockerfile

@@ -94,7 +94,7 @@ RUN curl -fsSL https://bun.com/install | bash && \
 
 COPY package.json package-lock.json ./
 
-RUN npm clean-install
+RUN npm clean-install --ignore-scripts
 
 COPY assets assets
 COPY bin bin

src/session/cf/cloudflare-detector.ts

@@ -897,7 +897,7 @@ export class CloudflareDetector {
           );
           if (postSolveSnapshot._tag === 'detected') {
             for (const t of postSolveSnapshot.targets) {
-              self.state.solvedCFTargetIds.add(t.targetId);
+              yield* self.state.addSolvedCFTarget(t.targetId, targetId);
             }
           }
         })(),
@@ -989,9 +989,9 @@ export class CloudflareDetector {
               break;
           }
 
-          // Common cleanup
+          // Common cleanup — scope-bound so entries are removed when page is destroyed
           for (const t of filteredDetection.targets) {
-            self.state.solvedCFTargetIds.add(t.targetId);
+            yield* self.state.addSolvedCFTarget(t.targetId, targetId);
           }
           return;
         }

src/session/cf/cloudflare-state-tracker.ts

@@ -1,4 +1,4 @@
-import { Effect, Schedule } from 'effect';
+import { Effect, Exit, Schedule, Scope } from 'effect';
 
 import { runForkInServer } from '../../otel-runtime.js';
 import {
@@ -107,6 +107,8 @@ export class CloudflareStateTracker {
   readonly pendingRechallengeCount = new Map<TargetId, number>();
   /** Per-page reload count for widget-not-rendered recovery. Reset on solve. */
   readonly widgetReloadCount = new Map<TargetId, number>();
+  /** Per-page cleanup scopes — finalizers remove solvedCFTargetIds entries when a page is destroyed. */
+  private readonly pageCleanupScopes = new Map<TargetId, Scope.Closeable>();
   config: Required<CloudflareConfig> = { maxAttempts: 3, attemptTimeout: 30000, recordingMarkers: true };
   destroyed = false;
   /** Per-page accumulator of solved/failed phases for compound summary labels. */
@@ -355,6 +357,36 @@ export class CloudflareStateTracker {
     return this.registry.destroyAll();
   }
 
+  /**
+   * Add an OOPIF target ID to solvedCFTargetIds with scope-bound cleanup.
+   * When the owning page's cleanup scope is closed (via unregisterPage),
+   * the finalizer atomically removes the entry — preventing unbounded growth.
+   */
+  addSolvedCFTarget(oopifId: string, pageTargetId: TargetId): Effect.Effect<void> {
+    const tracker = this;
+    return Effect.suspend(() => {
+      tracker.solvedCFTargetIds.add(oopifId);
+      const scope = tracker.pageCleanupScopes.get(pageTargetId);
+      if (!scope) return Effect.void;  // safety: no scope = cleanup falls to destroy()
+      return Scope.addFinalizer(scope, Effect.sync(() => {
+        tracker.solvedCFTargetIds.delete(oopifId);
+      }));
+    });
+  }
+
+  /**
+   * Synchronous variant of addSolvedCFTarget — used in stopTargetDetection
+   * where we're outside an Effect generator context.
+   */
+  addSolvedCFTargetSync(oopifId: string, pageTargetId: TargetId): void {
+    this.solvedCFTargetIds.add(oopifId);
+    const scope = this.pageCleanupScopes.get(pageTargetId);
+    if (!scope) return;  // safety: no scope = cleanup falls to destroy()
+    Effect.runSync(Scope.addFinalizer(scope, Effect.sync(() => {
+      this.solvedCFTargetIds.delete(oopifId);
+    })));
+  }
+
   /**
    * Resolve an active detection as auto-solved (token appeared without navigation).
    * Token is provided by the CF bridge push event — no Runtime.evaluate fallback.
@@ -487,9 +519,12 @@ export class CloudflareStateTracker {
     );
   }
 
-  /** Register a page target → CDP session mapping. */
+  /** Register a page target → CDP session mapping. Creates a cleanup scope for scope-bound solvedCFTargetIds entries. */
   registerPage(targetId: TargetId, cdpSessionId: CdpSessionId): void {
     this.knownPages.set(targetId, cdpSessionId);
+    if (!this.pageCleanupScopes.has(targetId)) {
+      this.pageCleanupScopes.set(targetId, Scope.makeUnsafe());
+    }
   }
 
   /**
@@ -514,7 +549,16 @@ export class CloudflareStateTracker {
       tracker.solvedPages.delete(targetId);
       tracker.pendingIframes.delete(targetId);
       tracker.pendingRechallengeCount.delete(targetId);
+      tracker.widgetReloadCount.delete(targetId);
       tracker.summaryPhases.delete(targetId);
+
+      // Close the page's cleanup scope — atomically fires all finalizers
+      // that remove this page's entries from solvedCFTargetIds.
+      const cleanupScope = tracker.pageCleanupScopes.get(targetId);
+      if (cleanupScope) {
+        yield* Scope.close(cleanupScope, Exit.void);
+        tracker.pageCleanupScopes.delete(targetId);
+      }
     })();
   }
 
@@ -554,9 +598,18 @@ export class CloudflareStateTracker {
       this.iframeToPage.clear();
       this.knownPages.clear();
       this.bindingSolvedTargets.clear();
+
+      // Close all remaining page cleanup scopes before clearing solvedCFTargetIds.
+      // Finalizers fire first (deleting entries), then clear() sweeps any stragglers.
+      for (const scope of this.pageCleanupScopes.values()) {
+        yield* Scope.close(scope, Exit.void);
+      }
+      this.pageCleanupScopes.clear();
+
       this.solvedCFTargetIds.clear();
       this.solvedPages.clear();
       this.pendingIframes.clear();
+      this.widgetReloadCount.clear();
       this.summaryPhases.clear();
     }).bind(this));
   }

src/session/cloudflare-solver.ts

@@ -355,14 +355,14 @@ export class CloudflareSolver {
     // it from a different runtime. JS single-threadedness makes this safe.
     this.destroyedTargets.add(targetId);
 
-    // Record destroyed target — prevents stale OOPIF re-detection if Chrome
-    // fires targetDestroyed after our detection poll but before cleanup
-    this.stateTracker.solvedCFTargetIds.add(targetId as unknown as string);
-
-    // Check if this target is an OOPIF child of a page detection.
-    // If so, DON'T kill the parent page's detection fiber — it needs to
-    // continue to detect navigation/token. Only abort if click was delivered.
+    // Hoist: determine owning page for scope-based cleanup
     const parentCtx = this.stateTracker.registry.findByIframeTarget(targetId);
+    const owningPageId = parentCtx?.active.pageTargetId ?? targetId;
+
+    // Race guard: prevents stale OOPIF re-detection if Chrome fires
+    // targetDestroyed after our detection poll but before cleanup.
+    // Scope-bound — entry is removed when owning page is destroyed.
+    this.stateTracker.addSolvedCFTargetSync(targetId as unknown as string, owningPageId);
     if (parentCtx) {
       if (parentCtx.oopif && parentCtx.active.clickDelivered) {
         // Post-click: close OOPIF scope — finalizer propagates abort

vitest.integration.setup.ts

@@ -102,7 +102,43 @@ async function waitForReady(timeoutMs: number): Promise<void> {
     if (await isRunning()) return;
     await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
   }
-  throw new Error(`Browserless did not start within ${timeoutMs}ms`);
+
+  // ── Diagnostic dump on startup failure ─────────────────────────────
+  // Collect everything needed to diagnose WHY the server didn't start.
+  // Without this, vitest shows "No test files found" — zero signal.
+  const diagnostics: string[] = [`Browserless did not start within ${timeoutMs}ms`];
+
+  // Server process state
+  if (serverProcess) {
+    diagnostics.push(`  PID: ${serverProcess.pid ?? 'unknown'}`);
+    diagnostics.push(`  exitCode: ${serverProcess.exitCode}`);
+    diagnostics.push(`  killed: ${serverProcess.killed}`);
+    diagnostics.push(`  signalCode: ${serverProcess.signalCode}`);
+  }
+
+  // Port ownership
+  try {
+    const lsofOut = execFileSync('lsof', ['-ti', `:${PORT}`], { encoding: 'utf-8' });
+    diagnostics.push(`  Port ${PORT} owners: ${lsofOut.trim().replace(/\n/g, ', ')}`);
+  } catch {
+    diagnostics.push(`  Port ${PORT}: no process listening`);
+  }
+
+  // Server log tail — last 20 lines
+  const logPath = path.join(BROWSERLESS_DIR, 'test-server.log');
+  if (existsSync(logPath)) {
+    const log = readFileSync(logPath, 'utf-8');
+    const lines = log.trim().split('\n');
+    const tail = lines.slice(-20).join('\n');
+    diagnostics.push(`  Server log (last ${Math.min(20, lines.length)} lines):\n${tail}`);
+  } else {
+    diagnostics.push('  Server log: file not found');
+  }
+
+  const message = diagnostics.join('\n');
+  // Print to stderr so it's visible even if vitest swallows the error
+  console.error(`\n[globalSetup] STARTUP FAILURE DIAGNOSTICS:\n${message}\n`);
+  throw new Error(message);
 }
 
 let serverProcess: ChildProcess | null = null;
@@ -182,9 +218,20 @@ export async function setup() {
     throw new Error(`Failed to spawn browserless: ${err.message}`);
   });
 
-  serverProcess.on('exit', (code) => {
+  serverProcess.on('exit', (code, signal) => {
     if (code && code !== 0) {
-      console.error(`[globalSetup] Browserless exited with code ${code}`);
+      // Dump server log on crash — visible to any agent reading stdout
+      const logPath = path.join(BROWSERLESS_DIR, 'test-server.log');
+      let logTail = '';
+      if (existsSync(logPath)) {
+        const lines = readFileSync(logPath, 'utf-8').trim().split('\n');
+        logTail = lines.slice(-10).join('\n');
+      }
+      console.error(
+        `[globalSetup] Browserless crashed!\n` +
+        `  exit code: ${code}, signal: ${signal}\n` +
+        `  Server log (last 10 lines):\n${logTail}`,
+      );
     }
   });