@sudobility/testomniac_runner 0.0.128

package/.dockerignore

@@ -0,0 +1,75 @@
+node_modules/
+npm-debug.log*
+.pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Environment files
+.env
+.env.local
+.env.production
+
+# Temporary files
+.tmp/
+tmp/
+temp/
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Build outputs
+dist/
+build/
+
+# Logs
+logs/
+*.log
+
+# Testing
+coverage/
+
+# Git
+.git/
+.gitignore
+
+# Documentation
+*.md
+docs/
+README*
+CHANGELOG*
+plans/
+
+# Test files
+tests/
+test/
+*.test.js
+*.test.ts
+*.spec.js
+*.spec.ts
+__tests__
+
+# Development scripts
+scripts/
+
+# Docker files
+Dockerfile*
+docker-compose*.yml
+.dockerignore
+
+# Development configs
+.eslintrc*
+eslint.config.*
+.prettierrc*
+.prettierignore

package/.env.example

@@ -0,0 +1,67 @@
+# =============================================================================
+# Testomniac Scanner Environment Variables
+# =============================================================================
+# Copy this file to .env and fill in your values.
+
+# -----------------------------------------------------------------------------
+# Server
+# -----------------------------------------------------------------------------
+PORT=8030
+NODE_ENV=development
+LOG_LEVEL=info
+
+# -----------------------------------------------------------------------------
+# API Connection (Required)
+# -----------------------------------------------------------------------------
+# 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.
+# Generate with: openssl rand -hex 32
+SCANNER_API_KEY=
+
+# -----------------------------------------------------------------------------
+# Scan Polling
+# -----------------------------------------------------------------------------
+# How often (ms) the scanner polls the API for pending runs
+SCAN_POLL_INTERVAL_MS=10000
+
+# -----------------------------------------------------------------------------
+# OpenAI (Required for AI analysis phase)
+# -----------------------------------------------------------------------------
+OPENAI_API_KEY=
+
+# -----------------------------------------------------------------------------
+# Email Reports (Optional - only needed if sending scan report emails)
+# -----------------------------------------------------------------------------
+# Postmark API token for sending emails
+POSTMARK_SERVER_TOKEN=
+
+# Sender email address for 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).
+# Generate with: openssl rand -hex 32
+DEEP_LINK_SECRET=
+
+# Base URL of the frontend app, used for building deep-link URLs in emails
+APP_BASE_URL=http://localhost:3000
+
+# -----------------------------------------------------------------------------
+# 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
+
+# Directory for storing screenshots and other scan artifacts
+ARTIFACT_DIR=./artifacts

package/.github/workflows/ci-cd.yml

@@ -0,0 +1,30 @@
+---
+# CI/CD workflow for testomniac_runner
+
+name: CI/CD
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+    branches:
+      - main
+      - develop
+
+permissions:
+  contents: write
+  id-token: write
+  deployments: write
+
+jobs:
+  cicd:
+    uses: johnqh/workflows/.github/workflows/unified-cicd.yml@main
+    with:
+      docker-image-name: "testomniac_runner"
+      skip-npm-publish: false
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}

package/.prettierignore

@@ -0,0 +1,62 @@
+# Dependencies
+node_modules/
+
+# Build outputs
+dist/
+build/
+
+# Package files
+*.tgz
+*.tar.gz
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Coverage directory used by tools like istanbul
+coverage/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# ESLint cache
+.eslintcache
+
+# Prettier cache
+.prettierignore
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# IDE files
+.vscode/
+.idea/
+
+# Git
+.git/
+.gitignore
+
+# Package lock files (auto-generated)
+package-lock.json
+yarn.lock
+bun.lock
+
+# Generated types
+types/

package/.prettierrc

@@ -0,0 +1,11 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": false,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "bracketSpacing": true,
+  "arrowParens": "avoid",
+  "endOfLine": "lf"
+}

package/.vscode/settings.json

@@ -0,0 +1,29 @@
+{
+  "cSpell.enabled": false,
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[javascriptreact]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[css]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[markdown]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,170 @@
+# Testomniac Runner
+
+Thin wrapper service that launches Puppeteer, polls for pending runs, and delegates all execution logic to `@sudobility/testomniac_runner_service` via `runTestRun()`. Provides server-side concerns: browser management, test execution worker pool, email reports, auth flows, and plugin implementations.
+
+**Package**: `testomniac_runner` (private, BUSL-1.1)
+
+## Tech Stack
+
+- **Language**: TypeScript (strict mode)
+- **Runtime**: Bun
+- **Package Manager**: Bun (do not use npm/yarn/pnpm for installing dependencies)
+- **Browser**: Puppeteer-core with Chrome for Testing
+- **AI**: OpenAI SDK (GPT-4o) — passed via config to runner_service
+- **HTTP**: Hono (health endpoint)
+- **Logging**: Pino
+- **Test**: Vitest
+- **Email**: Postmark
+- **Auth**: Signic SDK (disposable email for registration testing)
+
+## Project Structure
+
+```
+src/
+├── index.ts                    # Worker entrypoint — polls API for pending runs
+├── orchestrator.ts             # Creates PuppeteerAdapter, calls runTestRun()
+├── runner-manager.ts           # Manages concurrent runs, claims pending runs
+├── config/
+│   └── index.ts                # Environment config loader (loadConfig)
+├── browser/
+│   └── chromium.ts             # Browser launch/close manager (ChromiumManager)
+├── adapters/
+│   └── PuppeteerAdapter.ts     # BrowserAdapter implementation wrapping Puppeteer page
+├── auth/
+│   ├── form-identifier.ts      # Classify forms: login vs signup vs other
+│   ├── credential-manager.ts   # Credential storage for test accounts
+│   ├── login-executor.ts       # Form-based automated login
+│   ├── signic-registrar.ts     # Auto-registration via Signic disposable email
+│   └── password-detector.ts    # Password requirement detection from forms
+├── runner/
+│   ├── executor.ts             # Maps JSON test actions to Puppeteer commands
+│   ├── worker-pool.ts          # Concurrent test execution (default 3 workers)
+│   └── reporter.ts             # Pass/fail summary computation
+├── email/
+│   ├── deep-link.ts            # JWT token generation for report deep links
+│   ├── templates.ts            # HTML/text email templates
+│   └── sender.ts               # Postmark email sending
+├── scanner/
+│   └── email-checker.ts        # Signic inbox polling for verification emails
+└── plugins/                    # Plugin implementations (concrete checks)
+    ├── types.ts                # Plugin interface (re-exported from runner_service)
+    ├── registry.ts             # Local plugin registration
+    ├── seo/                    # SEO checks: title, meta, H1, images, structured data, Open Graph
+    ├── security/               # Security checks: API keys, headers, CSRF, mixed content
+    ├── content/                # Content checks: placeholders, readability, copyright, AI spelling
+    └── ui-consistency/         # Cross-page style comparison: fonts, colors, spacing
+```
+
+### Deleted (moved to runner_service)
+
+The following directories/files were removed during refactoring. All this logic now lives in `@sudobility/testomniac_runner_service`:
+
+- `ai/` (analyzer, persona/use-case/input generators, token tracker)
+- `generation/` (all test element templates and generator)
+- `api/client.ts` (now `getApiClient` from runner_service)
+- `domain/` (types, url-ownership)
+- `config/constants.ts` (now in runner_service)
+- `browser/page-utils.ts` (normalizeHtml, computeHashes)
+- `scanner/` (most modules — only `email-checker.ts` remains locally)
+
+## Commands
+
+```bash
+bun run dev            # Start runner worker in watch mode (polls for pending runs)
+bun run build          # Bundle with Bun
+bun run start          # Run production build
+bun run test           # Run Vitest tests
+bun run test:unit      # Run unit tests only
+bun run test:watch     # Vitest watch mode
+bun run typecheck      # TypeScript check
+bun run lint           # ESLint
+bun run lint:fix       # ESLint auto-fix
+bun run format         # Prettier write
+bun run format:check   # Prettier check
+bun run verify         # typecheck + lint + test + build
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | Health endpoint port | `8030` |
+| `TESTOMNIAC_API_URL` | API server URL | `http://localhost:8027` |
+| `SCANNER_API_KEY` | Shared secret for API auth | required |
+| `OPENAI_API_KEY` | OpenAI API key for AI analysis | required for AI phase |
+| `CHROMIUM_PATH` | Path to Chrome/Chromium binary | `/usr/bin/chromium` |
+| `USER_DATA_DIR` | Browser profile directory | `./browser-profile` |
+| `ARTIFACT_DIR` | Screenshots/logs storage | `./artifacts` |
+| `SCAN_POLL_INTERVAL_MS` | Poll interval for pending runs | `10000` |
+| `MAX_CONCURRENT_RUNNERS` | Max parallel runs | `5` |
+| `LOG_LEVEL` | Pino log level | `info` |
+| `POSTMARK_SERVER_TOKEN` | Postmark email API token | optional |
+| `POSTMARK_FROM_EMAIL` | Sender email address | optional |
+| `DEEP_LINK_SECRET` | JWT secret for report deep links | optional |
+| `APP_BASE_URL` | Frontend URL for deep links | `http://localhost:3000` |
+| `SIGNIC_INDEXER_URL` | Signic email indexer URL | optional |
+| `SIGNIC_WILDDUCK_URL` | Signic WildDuck API URL | optional |
+
+## Architecture
+
+The runner is a **stateless HTTP-polling worker**. It never accesses PostgreSQL directly — all communication goes through `testomniac_api` via HTTP with `X-Scanner-Key` authentication.
+
+### Polling Loop (`src/index.ts`)
+```
+Every SCAN_POLL_INTERVAL_MS (10s):
+  GET /api/v1/scanner/runs/pending  (via getApiClient from runner_service)
+  If run found → runFullScan(runner, run)
+  On error → PATCH /runs/:id/complete with failure
+```
+
+`RunnerManager` tracks active runs and spawns up to `MAX_CONCURRENT_RUNNERS` (default 5). Within a run, test jobs execute with 3 worker threads by default.
+
+### Orchestrator (`src/orchestrator.ts`)
+
+The orchestrator is a thin wrapper around `runTestRun()` from runner_service:
+
+1. Loads config, creates `ApiClient` via `getApiClient()`
+2. Launches Chromium via `ChromiumManager`
+3. Creates `PuppeteerAdapter` wrapping a Puppeteer page
+4. Builds default expertises and event handlers
+5. Calls `runTestRun()` from `@sudobility/testomniac_runner_service`
+6. Sends email report after completion (if user email provided)
+
+All execution logic (element extraction, page analysis, test generation, expertise evaluation, finding creation) lives in runner_service.
+
+### Browser Management
+- Puppeteer-core (no bundled browser) + Chrome for Testing
+- Persistent browser profile in `USER_DATA_DIR`
+- Headless mode with `--no-sandbox`
+- `PuppeteerAdapter` implements `BrowserAdapter` from `@sudobility/testomniac_runner_service`
+- Custom `tmnc-replay:` selector scheme for robust element targeting
+
+## Related Projects
+
+- **testomniac_runner_service** (`@sudobility/testomniac_runner_service`) — Shared library containing ALL execution logic. This runner calls `runTestRun()` from it.
+- **testomniac_api** (`localhost:8027`) — REST API this runner polls and reports to. All state flows through the API.
+- **testomniac_extension** — Chrome extension that also calls `runTestRun()` from runner_service, using `ChromeAdapter` instead of `PuppeteerAdapter`.
+- **testomniac_types** (`@sudobility/testomniac_types`) — Shared type definitions.
+- **testomniac_app** — Web frontend that displays scan results.
+- **testomniac_runner_mcp** — MCP server for AI-driven browser automation (also wraps runner_service).
+
+## Coding Patterns
+
+- **Thin wrapper around `runTestRun()`**: The orchestrator builds adapter + config + handlers and delegates everything to runner_service.
+- **All type imports from runner_service or testomniac_types**: No local `domain/types.ts` or `config/constants.ts`.
+- **`getApiClient` from runner_service**: No local API client.
+- **Pino logger per module**: `const logger = pino({ name: "module-name" })`
+- **Plugin implementations are local**: Plugin interface/registry defined in runner_service, but concrete plugin code (SEO, security, content, UI consistency) lives here.
+- **Colocated tests**: `*.test.ts` files alongside source files
+- **JSON-based test actions**: Test cases store action sequences as JSONB, executor maps to Puppeteer calls
+
+## Gotchas
+
+- **`browser-profile/` and `artifacts/` are gitignored** — they contain runtime data
+- **Chrome lock files (`SingletonLock`)** can persist after crashes — delete to fix "browser already running"
+- **OpenAI calls fail silently if `OPENAI_API_KEY` is empty** — AI phase is skipped, not errored
+- **First run is slow** — creates fresh Chrome profile on first launch
+- **`puppeteer-core` needs explicit `CHROMIUM_PATH`** — it does not bundle a browser
+- **Docker needs Chromium + all dependencies** — Dockerfile installs libgtk-3, libxss1, etc. for headless Chrome
+- **Artifacts directory must be writable** — runner saves screenshots as JPEG (quality 72) to `ARTIFACT_DIR`
+- **Most scanner/ directory was deleted**: Only `email-checker.ts` remains locally. All other scanner modules are now in runner_service.

package/Dockerfile

@@ -0,0 +1,76 @@
+FROM --platform=${BUILDPLATFORM} oven/bun:latest
+ARG TARGETPLATFORM
+ARG TARGETARCH
+ARG TARGETVARIANT
+ARG NPM_TOKEN
+
+RUN printf "I'm building for TARGETPLATFORM=${TARGETPLATFORM}" \
+    && printf ", TARGETARCH=${TARGETARCH}" \
+    && printf ", TARGETVARIANT=${TARGETVARIANT} \n" \
+    && printf "With uname -s : " && uname -s \
+    && printf "and  uname -m : " && uname -m
+
+# Install system dependencies including Chromium and its required libraries
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    dumb-init \
+    curl \
+    chromium \
+    fonts-liberation \
+    libasound2 \
+    libatk-bridge2.0-0 \
+    libatk1.0-0 \
+    libatspi2.0-0 \
+    libcairo2 \
+    libcups2 \
+    libdbus-1-3 \
+    libdrm2 \
+    libgbm1 \
+    libglib2.0-0 \
+    libgtk-3-0 \
+    libnspr4 \
+    libnss3 \
+    libpango-1.0-0 \
+    libx11-6 \
+    libxcb1 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxext6 \
+    libxfixes3 \
+    libxkbcommon0 \
+    libxrandr2 \
+    xdg-utils \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set Chromium path for puppeteer-core
+ENV CHROMIUM_PATH=/usr/bin/chromium
+
+WORKDIR /app
+
+RUN groupadd -g 1001 appuser && \
+    useradd -r -u 1001 -g appuser appuser
+
+COPY package.json bun.lock* bunfig.toml* ./
+
+RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc && \
+    echo "@sudobility:registry=https://registry.npmjs.org/" >> ~/.npmrc
+
+RUN bun install --production && \
+    rm -f ~/.npmrc
+
+COPY . .
+
+RUN bun run build
+
+RUN mkdir -p /app/logs /app/artifacts /app/browser-profile && \
+    chown -R appuser:appuser /app
+
+USER appuser
+
+EXPOSE 8030
+
+HEALTHCHECK --interval=30s --timeout=15s --start-period=30s --retries=3 \
+  CMD curl -f http://localhost:${PORT:-8030}/health || exit 1
+
+ENTRYPOINT ["/usr/bin/dumb-init", "--"]
+
+CMD ["bun", "run", "start"]

package/README.md

@@ -0,0 +1,22 @@
+# testomniac_runner
+
+Scanner worker service for Testomniac.
+
+This project is responsible for:
+- polling for pending scan runs
+- driving browser automation and discovery
+- reporting progress through the shared PostgreSQL event model
+- exposing a lightweight `/health` endpoint for container orchestration
+
+## Development
+
+```bash
+bun install
+bun run dev
+```
+
+Default health endpoint:
+
+```bash
+curl http://localhost:8030/health
+```