@sudobility/testomniac_runner 0.0.129 → 0.0.131

package/.env.example

@@ -1,67 +1,77 @@
 # =============================================================================
-# Testomniac Scanner Environment Variables
+# Testomniac Runner Environment Variables
 # =============================================================================
 # Copy this file to .env and fill in your values.
 
 # -----------------------------------------------------------------------------
 # Server
 # -----------------------------------------------------------------------------
+
+# Port for the health/status HTTP endpoint (Hono server)
 PORT=8030
-NODE_ENV=development
+
+# Pino log level: trace | debug | info | warn | error | fatal
 LOG_LEVEL=info
 
 # -----------------------------------------------------------------------------
-# API Connection (Required)
+# API
 # -----------------------------------------------------------------------------
-# URL of the testomniac_api instance
-TESTOMNIAC_API_URL=http://localhost:8027
 
-# Shared secret for authenticating with the API. Must match SCANNER_API_KEY in the API's .env.
+# URL of the testomniac_api instance this runner polls for pending runs
+TESTOMNIAC_API_URL=https://api.testomniac.com
+
+# Shared secret for X-Scanner-Key auth. Must match SCANNER_API_KEY in the API's .env.
 # Generate with: openssl rand -hex 32
 SCANNER_API_KEY=
 
 # -----------------------------------------------------------------------------
-# Scan Polling
+# Polling & Concurrency
 # -----------------------------------------------------------------------------
-# How often (ms) the scanner polls the API for pending runs
+
+# How often (ms) the runner polls the API for pending runs
 SCAN_POLL_INTERVAL_MS=10000
 
+# Maximum number of test runs executing in parallel
+MAX_CONCURRENT_RUNNERS=5
+
 # -----------------------------------------------------------------------------
-# OpenAI (Required for AI analysis phase)
+# Browser
 # -----------------------------------------------------------------------------
-OPENAI_API_KEY=
+
+# Path to Chrome/Chromium binary. Auto-detected from Puppeteer cache if not set.
+# Only set this to override auto-detection (e.g. Docker: /usr/bin/chromium).
+# CHROMIUM_PATH=/usr/bin/chromium
+
+# Directory for persistent browser profile (cookies, cache, etc.)
+USER_DATA_DIR=./testomniac-browser-profile
+
+# Directory for screenshots and other scan artifacts (JPEG, quality 72)
+ARTIFACT_DIR=./testomniac-artifacts
 
 # -----------------------------------------------------------------------------
-# Email Reports (Optional - only needed if sending scan report emails)
+# Email Reports (Optional — only needed if sending scan report emails)
 # -----------------------------------------------------------------------------
-# Postmark API token for sending emails
+
+# Postmark API token for sending emails. Leave empty to disable email reports.
 POSTMARK_SERVER_TOKEN=
 
-# Sender email address for report emails
+# Sender email address shown on report emails
 POSTMARK_FROM_EMAIL=
 
-# Secret key for signing deep-link JWTs in report emails.
-# If not set, deep links will use an empty key (insecure but functional).
+# Secret for signing deep-link JWTs embedded in report emails.
+# If empty, deep links use an empty key (insecure — fine for local dev).
 # Generate with: openssl rand -hex 32
 DEEP_LINK_SECRET=
 
-# Base URL of the frontend app, used for building deep-link URLs in emails
+# Base URL of the frontend app, used to build deep-link URLs in emails
 APP_BASE_URL=http://localhost:3000
 
 # -----------------------------------------------------------------------------
-# Signic Email Verification (Optional - for email-based auth scanning)
+# Signic Email Verification (Optional — for email-based auth scanning)
 # -----------------------------------------------------------------------------
-SIGNIC_INDEXER_URL=https://api.signic.email/idx
-SIGNIC_WILDDUCK_URL=https://api.signic.email/api
 
-# -----------------------------------------------------------------------------
-# Browser / Filesystem
-# -----------------------------------------------------------------------------
-# Path to Chromium binary
-CHROMIUM_PATH=/usr/bin/chromium
-
-# Directory for browser profile persistence
-USER_DATA_DIR=./browser-profile
+# Signic indexer URL for polling verification/confirmation emails
+SIGNIC_INDEXER_URL=https://api.signic.email/idx
 
-# Directory for storing screenshots and other scan artifacts
-ARTIFACT_DIR=./artifacts
+# Signic email API URL for disposable email account management
+SIGNIC_EMAIL_API_URL=https://api.signic.email/api

package/bun.lock

@@ -8,8 +8,8 @@
         "@noble/curves": "^1.0.0",
         "@noble/hashes": "^1.0.0",
         "@sudobility/signic_sdk": "^0.1.7",
-        "@sudobility/testomniac_runner_service": "^0.1.128",
-        "@sudobility/testomniac_types": "^0.0.67",
+        "@sudobility/testomniac_runner_service": "^0.1.130",
+        "@sudobility/testomniac_types": "^0.0.68",
         "hono": "^4.7.0",
         "jose": "^6.1.2",
         "openai": "^6.7.0",
@@ -172,9 +172,9 @@
 
     "@sudobility/signic_sdk": ["@sudobility/signic_sdk@0.1.7", "", {}, "sha512-5XSgHSVsmyrMQ/ui1nDywwzt9dbRCsaeJ5tX6mKw2ZXbTZ82OsMr+dqDyV9XV3pfy7IHRIZq73af5KBamx72Fw=="],
 
-    "@sudobility/testomniac_runner_service": ["@sudobility/testomniac_runner_service@0.1.128", "", { "peerDependencies": { "@sudobility/testomniac_types": "^0.0.67", "openai": ">=6.0.0", "react": ">=18.0.0" }, "optionalPeers": ["openai", "react"] }, "sha512-YWFjcMmZROSHSNUZLt9czUJeWoYmIj69JCXUP9CD9sw5/UTzFFLwIdkqtAE2lG4RDo/Yb/5heZPmffZ1EfPPqw=="],
+    "@sudobility/testomniac_runner_service": ["@sudobility/testomniac_runner_service@0.1.130", "", { "peerDependencies": { "@sudobility/testomniac_types": "^0.0.68", "openai": ">=6.0.0", "react": ">=18.0.0" }, "optionalPeers": ["openai", "react"] }, "sha512-C6I/8Zo/ZqBrOMXeiWqaAKEJIEdRI6xWvtRQoyYEtxuh51WN8CtbVyhPn5AEzDQJQTWa+RJllo9u0SxW0L/o1g=="],
 
-    "@sudobility/testomniac_types": ["@sudobility/testomniac_types@0.0.67", "", { "peerDependencies": { "@sudobility/types": "^1.9.62" } }, "sha512-kNBDk7AsFx1rqUWLq4nx0nf1alV9G7U5xbxj8qDvZKa+cCnUSiZFRtDB88ENWQzeIPVJAU8MaVo5yUKVL46eYg=="],
+    "@sudobility/testomniac_types": ["@sudobility/testomniac_types@0.0.68", "", { "peerDependencies": { "@sudobility/types": "^1.9.62" } }, "sha512-io3qbAuOLuCrjC4txkD+B21n/RGrfz2MH+W0XciAOkaxcfXagdHRUdWie/520HeItC9F91jP9SA67YAcx5aZ0A=="],
 
     "@sudobility/types": ["@sudobility/types@1.9.61", "", {}, "sha512-SODGpstB/iKfK3H/4BvJx/FBcc1h3gutUjGotyxN19VnOfWyzaDoEmW7eyoxOAYhZyXMXagSiii+NIEZvuxKog=="],
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudobility/testomniac_runner",
-  "version": "0.0.129",
+  "version": "0.0.131",
   "publishConfig": {
     "access": "public"
   },
@@ -24,8 +24,8 @@
     "@noble/curves": "^1.0.0",
     "@noble/hashes": "^1.0.0",
     "@sudobility/signic_sdk": "^0.1.7",
-    "@sudobility/testomniac_runner_service": "^0.1.128",
-    "@sudobility/testomniac_types": "^0.0.67",
+    "@sudobility/testomniac_runner_service": "^0.1.130",
+    "@sudobility/testomniac_types": "^0.0.68",
     "hono": "^4.7.0",
     "jose": "^6.1.2",
     "openai": "^6.7.0",

package/src/adapters/PuppeteerAdapter.ts

@@ -241,9 +241,10 @@ export class PuppeteerAdapter implements BrowserAdapter {
     type?: string;
     quality?: number;
   }): Promise<Uint8Array> {
+    const type = (options?.type as "jpeg" | "png") || "jpeg";
     const buffer = await this.page.screenshot({
-      type: (options?.type as "jpeg" | "png") || "jpeg",
-      quality: options?.quality || 72,
+      type,
+      ...(type === "jpeg" ? { quality: options?.quality || 72 } : {}),
     });
     return new Uint8Array(buffer);
   }

package/src/auth/signic-registrar.ts

@@ -51,7 +51,7 @@ export async function autoRegister(
 
   const client = new SignicClient({
     indexerUrl: config.signicIndexerUrl,
-    wildduckUrl: config.signicWildduckUrl,
+    wildduckUrl: config.signicEmailApiUrl,
     signMessage: async (message: string) => signEthMessage(message, privateKey),
   });
 

package/src/browser/chromium.ts

@@ -1,7 +1,66 @@
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import puppeteer, { type Browser, type Page } from "puppeteer-core";
 import type { Config } from "../config/index";
 import type { Screen } from "@sudobility/testomniac_types";
 
+/**
+ * Finds the latest Chrome for Testing binary in the Puppeteer cache.
+ * Falls back to common system paths, then to the config value.
+ */
+export function resolveChromiumPath(configPath: string): string {
+  // Explicit env var / config always wins
+  if (process.env.CHROMIUM_PATH) return process.env.CHROMIUM_PATH;
+
+  // Scan Puppeteer cache for the latest Chrome for Testing
+  const cacheDir = join(homedir(), ".cache", "puppeteer", "chrome");
+  if (existsSync(cacheDir)) {
+    const platform =
+      process.platform === "darwin"
+        ? process.arch === "arm64"
+          ? "mac_arm"
+          : "mac-x64"
+        : "linux";
+    const versions = readdirSync(cacheDir)
+      .filter(d => d.startsWith(platform + "-"))
+      .sort()
+      .reverse();
+
+    for (const version of versions) {
+      const candidates =
+        process.platform === "darwin"
+          ? [
+              join(
+                cacheDir,
+                version,
+                "chrome-mac-arm64",
+                "Google Chrome for Testing.app",
+                "Contents",
+                "MacOS",
+                "Google Chrome for Testing"
+              ),
+              join(
+                cacheDir,
+                version,
+                "chrome-mac-x64",
+                "Google Chrome for Testing.app",
+                "Contents",
+                "MacOS",
+                "Google Chrome for Testing"
+              ),
+            ]
+          : [join(cacheDir, version, "chrome-linux64", "chrome")];
+
+      for (const candidate of candidates) {
+        if (existsSync(candidate)) return candidate;
+      }
+    }
+  }
+
+  return configPath;
+}
+
 export class ChromiumManager {
   private browser: Browser | null = null;
 
@@ -9,7 +68,7 @@ export class ChromiumManager {
 
   async launch(): Promise<Browser> {
     this.browser = await puppeteer.launch({
-      executablePath: this.config.chromiumPath,
+      executablePath: resolveChromiumPath(this.config.chromiumPath),
       userDataDir: this.config.userDataDir,
       headless: true,
       args: ["--no-sandbox", "--disable-setuid-sandbox"],

package/src/config/index.test.ts

@@ -17,7 +17,7 @@ describe("config", () => {
 
   it("uses defaults for optional values", () => {
     const config = loadConfig();
-    expect(config.artifactDir).toBe("./artifacts");
-    expect(config.userDataDir).toBe("./browser-profile");
+    expect(config.artifactDir).toBe("./testomniac-artifacts");
+    expect(config.userDataDir).toBe("./testomniac-browser-profile");
   });
 });

package/src/config/index.ts

@@ -1,13 +1,12 @@
 export interface Config {
   apiUrl: string;
   scannerApiKey: string;
-  openaiApiKey: string;
   postmarkServerToken: string;
   postmarkFromEmail: string;
   deepLinkSecret: string;
   appBaseUrl: string;
   signicIndexerUrl: string;
-  signicWildduckUrl: string;
+  signicEmailApiUrl: string;
   chromiumPath: string;
   userDataDir: string;
   artifactDir: string;
@@ -16,20 +15,19 @@ export interface Config {
 
 export function loadConfig(): Config {
   return {
-    apiUrl: process.env.TESTOMNIAC_API_URL || "http://localhost:8027",
+    apiUrl: process.env.TESTOMNIAC_API_URL || "https://api.testomniac.com",
     scannerApiKey: process.env.SCANNER_API_KEY || "",
-    openaiApiKey: process.env.OPENAI_API_KEY || "",
     postmarkServerToken: process.env.POSTMARK_SERVER_TOKEN || "",
     postmarkFromEmail: process.env.POSTMARK_FROM_EMAIL || "",
     deepLinkSecret: process.env.DEEP_LINK_SECRET || "",
     appBaseUrl: process.env.APP_BASE_URL || "http://localhost:3000",
     signicIndexerUrl:
       process.env.SIGNIC_INDEXER_URL || "https://api.signic.email/idx",
-    signicWildduckUrl:
-      process.env.SIGNIC_WILDDUCK_URL || "https://api.signic.email/api",
+    signicEmailApiUrl:
+      process.env.SIGNIC_EMAIL_API_URL || "https://api.signic.email/api",
     chromiumPath: process.env.CHROMIUM_PATH || "/usr/bin/chromium",
-    userDataDir: process.env.USER_DATA_DIR || "./browser-profile",
-    artifactDir: process.env.ARTIFACT_DIR || "./artifacts",
+    userDataDir: process.env.USER_DATA_DIR || "./testomniac-browser-profile",
+    artifactDir: process.env.ARTIFACT_DIR || "./testomniac-artifacts",
     maxConcurrentRunners: Number(process.env.MAX_CONCURRENT_RUNNERS ?? 5),
   };
 }

package/src/index.ts

@@ -44,6 +44,7 @@ if (import.meta.main) {
       "runner-id": { type: "string" },
       "base-url": { type: "string" },
       "size-class": { type: "string", default: "desktop" },
+      "scan-mode": { type: "string" },
     },
     strict: false,
   });
@@ -54,6 +55,7 @@ if (import.meta.main) {
     const runnerId = Number(args["runner-id"]);
     const baseUrl = String(args["base-url"] ?? "");
     const sizeClass = String(args["size-class"] ?? "desktop");
+    const scanMode = readScanMode(args["scan-mode"]);
 
     logger.info({ scanId, runnerId }, "one-shot mode: executing test run");
     try {
@@ -63,6 +65,7 @@ if (import.meta.main) {
         scanUrl: baseUrl,
         baseUrl,
         sizeClass,
+        scanMode,
         runnerInstanceId: crypto.randomUUID(),
         runnerInstanceName: "mcp-runner",
       });
@@ -104,6 +107,14 @@ if (import.meta.main) {
   }
 }
 
+function readScanMode(
+  value: unknown
+): "full" | "partial" | "minimum" | undefined {
+  return value === "full" || value === "partial" || value === "minimum"
+    ? value
+    : undefined;
+}
+
 export default {
   port,
   fetch: app.fetch,

package/src/orchestrator.ts

@@ -40,14 +40,12 @@ export interface RunOptions {
   loginUrl?: string;
   entityCredentialId?: number;
   quickScan?: boolean;
+  scanMode?: "full" | "partial" | "minimum";
 }
 
 export async function runFullScan(options: RunOptions): Promise<void> {
   const config = loadConfig();
-  const api = getApiClient(
-    config.apiUrl + "/api/v1/scanner",
-    config.scannerApiKey
-  );
+  const api = getApiClient(config.apiUrl, config.scannerApiKey);
   const { scanUrl, baseUrl, userEmail } = options;
   const runnerName = options.runnerName || new URL(scanUrl).hostname;
   const sizeClass = (options.sizeClass as SizeClass) || SizeClass.Desktop;
@@ -115,6 +113,7 @@ export async function runFullScan(options: RunOptions): Promise<void> {
         entityCredentialId: options.entityCredentialId,
         credentials: options.credentials,
         quickScan: options.quickScan,
+        scanMode: options.scanMode,
       },
       api,
       expertises,
@@ -138,7 +137,11 @@ export async function runFullScan(options: RunOptions): Promise<void> {
       });
     }
 
-    await page.close();
+    try {
+      await page.close();
+    } catch (err) {
+      logger.debug({ err }, "page already closed during scan cleanup");
+    }
 
     logger.info(
       { scanId, sizeClass, totalDurationMs: elapsed(runStart) },
@@ -159,10 +162,7 @@ export async function runSequenceScan(
   options: SequenceRunOptions
 ): Promise<void> {
   const config = loadConfig();
-  const api = getApiClient(
-    config.apiUrl + "/api/v1/scanner",
-    config.scannerApiKey
-  );
+  const api = getApiClient(config.apiUrl, config.scannerApiKey);
 
   const runStart = Date.now();
   const sizeClass = (options.sizeClass as SizeClass) || SizeClass.Desktop;
@@ -205,7 +205,11 @@ export async function runSequenceScan(
       eventHandler
     );
 
-    await page.close();
+    try {
+      await page.close();
+    } catch (err) {
+      logger.debug({ err }, "page already closed during sequence cleanup");
+    }
 
     logger.info(
       {

package/src/runner-manager.ts

@@ -33,10 +33,7 @@ export class RunnerManager {
     this.tickInFlight = true;
     try {
       const config = loadConfig();
-      const api = getApiClient(
-        config.apiUrl + "/api/v1/scanner",
-        config.scannerApiKey
-      );
+      const api = getApiClient(config.apiUrl, config.scannerApiKey);
 
       while (this.activeRuns.size < this.maxConcurrentRunners) {
         const pendingRun = await api.getPendingTestRun();
@@ -57,23 +54,50 @@ export class RunnerManager {
         }
 
         const slotNumber = this.activeRuns.size + 1;
-        const runner = await api.getRunner(pendingRun.runnerId);
+
+        let runner;
+        try {
+          runner = await api.getRunner(pendingRun.runnerId);
+        } catch (err) {
+          logger.error(
+            { err, runnerId: pendingRun.runnerId, runId: pendingRun.id },
+            "failed to fetch runner, will retry next tick"
+          );
+          break;
+        }
         if (!runner) {
           logger.error(
             { runnerId: pendingRun.runnerId, runId: pendingRun.id },
             "runner not found for pending run"
           );
-          await api.completeTestRun(pendingRun.id, { status: "failed" });
+          try {
+            await api.completeTestRun(pendingRun.id, { status: "failed" });
+          } catch (err) {
+            logger.error(
+              { err, runId: pendingRun.id },
+              "failed to mark run as failed"
+            );
+          }
           continue;
         }
 
         const runnerInstanceId = `${this.processInstanceId}:${slotNumber}`;
         const runnerInstanceName = `${runner.title} [slot ${slotNumber}]`;
-        const claimed = await api.claimTestRun(
-          pendingRun.id,
-          runnerInstanceId,
-          runnerInstanceName
-        );
+
+        let claimed;
+        try {
+          claimed = await api.claimTestRun(
+            pendingRun.id,
+            runnerInstanceId,
+            runnerInstanceName
+          );
+        } catch (err) {
+          logger.error(
+            { err, runId: pendingRun.id },
+            "failed to claim run, will retry next tick"
+          );
+          break;
+        }
         if (!claimed) {
           logger.info(
             { runId: pendingRun.id },
@@ -106,8 +130,11 @@ export class RunnerManager {
           runnerInstanceId,
           runnerInstanceName,
           quickScan: pendingRun.quickScan ?? false,
+          scanMode: readScanMode(pendingRun),
         });
       }
+    } catch (err) {
+      logger.error({ err }, "tick failed");
     } finally {
       this.tickInFlight = false;
     }
@@ -122,6 +149,7 @@ export class RunnerManager {
     runnerInstanceId: string;
     runnerInstanceName: string;
     quickScan: boolean;
+    scanMode?: "full" | "partial" | "minimum";
   }): Promise<void> {
     const config = loadConfig();
     const api = getApiClient(
@@ -140,6 +168,7 @@ export class RunnerManager {
         runnerInstanceId: params.runnerInstanceId,
         runnerInstanceName: params.runnerInstanceName,
         quickScan: params.quickScan,
+        scanMode: params.scanMode,
       });
 
       logger.info({ runId: params.runId }, "run completed successfully");
@@ -161,3 +190,12 @@ export class RunnerManager {
     }
   }
 }
+
+function readScanMode(
+  run: unknown
+): "full" | "partial" | "minimum" | undefined {
+  const value = (run as { scanMode?: unknown }).scanMode;
+  return value === "full" || value === "partial" || value === "minimum"
+    ? value
+    : undefined;
+}