hauntview 0.0.0-stage → 0.0.6

package/package.json

@@ -1,6 +1,122 @@
 {
   "name": "hauntview",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.6",
+  "type": "module",
+  "description": "Local-first website resilience, accessibility, failure-mode and visual regression testing with Playwright and MCP.",
+  "bin": {
+    "haunt": "dist/cli.js",
+    "hauntview": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src/core",
+    "!src/core/__tests__",
+    "src/engine.ts",
+    "src/profiles",
+    "!src/profiles/__tests__",
+    "src/reports",
+    "src/types",
+    "src/version.ts",
+    "scripts/postinstall.mjs",
+    "VERSION",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.12.0",
+    "npm": ">=10.0.0"
+  },
+  "scripts": {
+    "dev": "node init && next dev --hostname 127.0.0.1",
+    "postinstall": "node scripts/postinstall.mjs",
+    "build:cli": "node scripts/build-cli.mjs",
+    "build": "node init && node scripts/build-cli.mjs && next build",
+    "start": "node init && next start --hostname 0.0.0.0",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check": "pnpm run typecheck && pnpm run lint && pnpm run format:check",
+    "test": "pnpm run test:unit",
+    "test:unit": "jest --runInBand",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage --runInBand",
+    "test:all": "pnpm run test:unit && pnpm run test:e2e",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:headed": "playwright test --headed",
+    "test:report": "playwright show-report",
+    "browsers:install": "playwright install chromium firefox webkit",
+    "mcp": "tsx src/mcp/server.ts",
+    "presubmit": "node scripts/presubmit.mjs",
+    "version:bump": "node scripts/bump-version.mjs",
+    "version:check": "node scripts/check-version.mjs",
+    "setup:hooks": "husky",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx,mjs,cjs}": [
+      "eslint --fix",
+      "prettier --write",
+      "eslint"
+    ],
+    "*.{json,md,mdx,css,yml,yaml}": [
+      "prettier --write"
+    ]
+  },
+  "dependencies": {
+    "@axe-core/playwright": "^4.14.0",
+    "@heroicons/react": "^2.2.0",
+    "@inquirer/prompts": "^8.7.5",
+    "@modelcontextprotocol/server": "^2.4.0",
+    "@sparticuz/chromium": "^153.0.0",
+    "@types/jszip": "^3.4.1",
+    "better-sqlite3": "^13.0.3",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "commander": "^15.0.0",
+    "ipaddr.js": "^2.5.0",
+    "jszip": "^3.10.2",
+    "lucide-react": "^1.69.0",
+    "next": "16.4.3",
+    "nextjs-toploader": "^3.9.17",
+    "p-limit": "^7.3.3",
+    "pixelmatch": "^8.0.0",
+    "playwright": "^1.65.0",
+    "pngjs": "^7.0.0",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "sonner": "^2.0.8",
+    "tailwind-merge": "^3.7.0",
+    "zod": "^4.6.7",
+    "zustand": "^5.0.16"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@playwright/test": "^1.65.0",
+    "@tailwindcss/postcss": "^4.3.4",
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^24.19.2",
+    "@types/pngjs": "^6.0.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "esbuild": "^0.28.2",
+    "eslint": "^10.14.0",
+    "eslint-config-next": "16.4.3",
+    "eslint-config-prettier": "^10.1.8",
+    "fast-check": "^4.10.2",
+    "husky": "^9.1.7",
+    "jest": "^29.7.0",
+    "jest-environment-node": "^29.7.0",
+    "lint-staged": "^17.6.0",
+    "postcss": "^8.5.32",
+    "prettier": "^3.9.10",
+    "prettier-plugin-tailwindcss": "^0.6.14",
+    "tailwindcss": "^4.3.4",
+    "ts-jest": "^29.4.15",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3"
+  }
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * postinstall.mjs
+ *
+ * Installs Playwright's Chromium browser in local development only,
+ * and only when it isn't already installed for the current Playwright version.
+ *
+ * Skip conditions:
+ *   - RENDER=true   → Render build/runtime (uses @sparticuz/chromium instead)
+ *   - CI=true       → GitHub Actions and most hosted CI (no browsers needed for lint/build)
+ *   - SKIP_PLAYWRIGHT_INSTALL=1 → manual opt-out
+ *
+ * Idempotency:
+ *   We ask `playwright install --dry-run chromium` first. If it exits 0 with
+ *   no output (nothing to install), we skip. This avoids re-downloading on
+ *   every `pnpm install` when the binary is already cached.
+ */
+
+import { execSync, spawnSync } from 'node:child_process';
+
+const isRender = process.env.RENDER === 'true';
+const isCI = process.env.CI === 'true';
+const isSkipped = process.env.SKIP_PLAYWRIGHT_INSTALL === '1';
+
+if (isRender || isCI || isSkipped) {
+  const reason = isRender ? 'RENDER=true' : isCI ? 'CI=true' : 'SKIP_PLAYWRIGHT_INSTALL=1';
+  console.log(`[postinstall] Skipping Playwright install (${reason}).`);
+  process.exit(0);
+}
+
+// Check if Chromium is already installed for this exact Playwright version.
+// `playwright install --dry-run` prints what *would* be downloaded.
+// If stdout is empty (or only whitespace), everything is already cached.
+const dryRun = spawnSync('pnpm', ['exec', 'playwright', 'install', '--dry-run', 'chromium'], {
+  encoding: 'utf8',
+});
+
+const dryRunOutput = (dryRun.stdout ?? '').trim();
+const alreadyInstalled = dryRun.status === 0 && dryRunOutput === '';
+
+if (alreadyInstalled) {
+  console.log('[postinstall] Playwright Chromium already installed — nothing to do.');
+  process.exit(0);
+}
+
+console.log('[postinstall] Installing Playwright Chromium...');
+execSync('pnpm exec playwright install chromium', { stdio: 'inherit' });

package/src/core/browser-launch.ts

@@ -0,0 +1,60 @@
+/**
+ * browser-launch.ts
+ *
+ * Resolves the correct Chromium launch options for the current environment.
+ *
+ * - Production / Render: uses @sparticuz/chromium, which ships its own binary
+ *   compatible with serverless/constrained Linux environments (0.5 CPU, 512MB RAM).
+ * - Local development: returns undefined executablePath so Playwright uses its own bundled binary.
+ */
+
+export interface BrowserLaunchConfig {
+  executablePath?: string;
+  args: string[];
+}
+
+/**
+ * Returns Chromium launch options (executablePath + required flags) for the current environment.
+ */
+export async function getChromiumLaunchOptions(): Promise<BrowserLaunchConfig> {
+  const isRender = process.env.RENDER === 'true';
+  const isCI = process.env.CI === 'true';
+
+  if (isRender || isCI) {
+    // Dynamically import to avoid loading the binary in dev where it's unneeded.
+    const { default: sparticuzChromium } = await import('@sparticuz/chromium');
+
+    sparticuzChromium.setGraphicsMode = false;
+
+    const executablePath = await sparticuzChromium.executablePath();
+    const args = [
+      ...sparticuzChromium.args,
+      '--headless=new',
+      '--no-sandbox',
+      '--disable-setuid-sandbox',
+      '--disable-dev-shm-usage',
+      '--disable-gpu',
+      '--single-process',
+      '--no-zygote',
+    ];
+
+    return {
+      executablePath,
+      args,
+    };
+  }
+
+  // Local development: standard Playwright flags
+  return {
+    executablePath: undefined,
+    args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
+  };
+}
+
+/**
+ * Backward-compatible helper returning just the executable path.
+ */
+export async function getChromiumExecutablePath(): Promise<string | undefined> {
+  const config = await getChromiumLaunchOptions();
+  return config.executablePath;
+}

package/src/core/browser-pool.ts

@@ -0,0 +1,267 @@
+/**
+ * BrowserPool - Manages Playwright browser instances and page lifecycle
+ * Handles browser instance pooling, page reuse, and resource cleanup
+ */
+
+import { Browser, BrowserContext, Page } from 'playwright';
+import { BrowserPoolConfig, ProfileContext } from '../types';
+
+interface PooledBrowser {
+  browser: Browser;
+  pages: Page[];
+  activePages: Set<Page>;
+  lastUsed: number;
+}
+
+interface PooledPage {
+  page: Page;
+  context: BrowserContext;
+  profileContext?: ProfileContext;
+  inUse: boolean;
+  lastUsed?: number;
+}
+
+export class BrowserPool {
+  private browsers: Map<string, PooledBrowser> = new Map();
+  private pagePool: PooledPage[] = [];
+  private config: BrowserPoolConfig;
+  private cleanupInterval: NodeJS.Timeout | null = null;
+
+  constructor(config: BrowserPoolConfig) {
+    this.config = {
+      maxBrowsers: config.maxBrowsers ?? 3,
+      maxPagesPerBrowser: config.maxPagesPerBrowser ?? 5,
+      idleTimeout: config.idleTimeout ?? 30000,
+      launchOptions: config.launchOptions,
+    };
+
+    // Start cleanup interval
+    this.startCleanupInterval();
+  }
+
+  /**
+   * Acquire a page from the pool or create a new one
+   */
+  async acquirePage(
+    browserKey: string,
+    profileContext: ProfileContext,
+    playwrightBrowser: Browser
+  ): Promise<Page> {
+    let pooledBrowser = this.browsers.get(browserKey);
+    if (!pooledBrowser) {
+      this.registerBrowser(browserKey, playwrightBrowser);
+      pooledBrowser = this.browsers.get(browserKey)!;
+    }
+
+    // Clean up closed pages
+    pooledBrowser.pages = pooledBrowser.pages.filter((p) => !p.isClosed());
+    for (const p of pooledBrowser.activePages) {
+      if (p.isClosed()) {
+        pooledBrowser.activePages.delete(p);
+      }
+    }
+
+    // If active pages count exceeds limit, clean up idle pages
+    if (pooledBrowser.pages.length >= this.config.maxPagesPerBrowser) {
+      const idlePages = this.pagePool.filter((p) => !p.inUse);
+      for (const idle of idlePages) {
+        try {
+          if (!idle.page.isClosed()) {
+            await idle.page.close();
+          }
+          await idle.context.close();
+        } catch {
+          // Already closed
+        }
+        this.pagePool = this.pagePool.filter((p) => p !== idle);
+        pooledBrowser.pages = pooledBrowser.pages.filter((p) => p !== idle.page);
+        pooledBrowser.activePages.delete(idle.page);
+      }
+    }
+
+    const context = await playwrightBrowser.newContext({
+      viewport: {
+        width: profileContext.viewport.width,
+        height: profileContext.viewport.height,
+      },
+      isMobile: profileContext.viewport.isMobile,
+      hasTouch: profileContext.viewport.hasTouch,
+      userAgent: profileContext.userAgent,
+      locale: profileContext.locale,
+      timezoneId: profileContext.timezone,
+    });
+
+    const page = await context.newPage();
+    const pooledPage: PooledPage = {
+      page,
+      context,
+      profileContext,
+      inUse: true,
+      lastUsed: Date.now(),
+    };
+
+    pooledBrowser.pages.push(page);
+    pooledBrowser.activePages.add(page);
+    this.pagePool.push(pooledPage);
+
+    page.on('close', () => {
+      pooledBrowser?.activePages.delete(page);
+    });
+
+    return page;
+  }
+
+  /**
+   * Release a page back to the pool
+   */
+  releasePage(page: Page): void {
+    const pooledPageIndex = this.pagePool.findIndex((p) => p.page === page);
+    if (pooledPageIndex !== -1) {
+      const [pooledPage] = this.pagePool.splice(pooledPageIndex, 1);
+      pooledPage.inUse = false;
+
+      // Close page and context asynchronously to free browser memory
+      Promise.all([
+        !page.isClosed() ? page.close().catch(() => {}) : Promise.resolve(),
+        pooledPage.context.close().catch(() => {}),
+      ]).finally(() => {
+        for (const pooledBrowser of this.browsers.values()) {
+          pooledBrowser.pages = pooledBrowser.pages.filter((p) => p !== page);
+          pooledBrowser.activePages.delete(page);
+        }
+      });
+    }
+  }
+
+  /**
+   * Register a browser instance
+   */
+  registerBrowser(key: string, browser: Browser): void {
+    if (this.browsers.has(key)) {
+      const existing = this.browsers.get(key)!;
+      existing.browser = browser;
+      existing.lastUsed = Date.now();
+      return;
+    }
+
+    if (this.browsers.size >= this.config.maxBrowsers) {
+      throw new Error(`Browser pool full: max ${this.config.maxBrowsers} browsers reached`);
+    }
+
+    this.browsers.set(key, {
+      browser,
+      pages: [],
+      activePages: new Set(),
+      lastUsed: Date.now(),
+    });
+  }
+
+  /**
+   * Close all resources in the pool
+   */
+  async closeAll(): Promise<void> {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+    }
+
+    // Close all pages
+    for (const pooledPage of this.pagePool) {
+      try {
+        await pooledPage.context.close();
+      } catch {
+        // Already closed
+      }
+    }
+
+    // Close all browsers
+    for (const pooledBrowser of this.browsers.values()) {
+      try {
+        await pooledBrowser.browser.close();
+      } catch {
+        // Already closed
+      }
+    }
+
+    this.pagePool = [];
+    this.browsers.clear();
+  }
+
+  /**
+   * Get pool statistics
+   */
+  getStats(): {
+    totalBrowsers: number;
+    totalPages: number;
+    activePages: number;
+    availablePages: number;
+  } {
+    let totalPages = 0;
+    let activePages = 0;
+
+    for (const pooledBrowser of this.browsers.values()) {
+      totalPages += pooledBrowser.pages.length;
+      activePages += pooledBrowser.activePages.size;
+    }
+
+    return {
+      totalBrowsers: this.browsers.size,
+      totalPages,
+      activePages,
+      availablePages: totalPages - activePages,
+    };
+  }
+
+  /**
+   * Start periodic cleanup of idle resources
+   */
+  private startCleanupInterval(): void {
+    this.cleanupInterval = setInterval(() => {
+      this.cleanupIdleResources();
+    }, 10000); // Check every 10 seconds
+
+    // Unref to not keep process alive
+    if (this.cleanupInterval.unref) {
+      this.cleanupInterval.unref();
+    }
+  }
+
+  /**
+   * Clean up idle pages and browsers
+   */
+  private async cleanupIdleResources(): Promise<void> {
+    const now = Date.now();
+
+    // Remove idle pages
+    const idlePages = this.pagePool.filter(
+      (p) => !p.inUse && now - (p.lastUsed || now) > this.config.idleTimeout
+    );
+
+    for (const pooledPage of idlePages) {
+      try {
+        await pooledPage.context.close();
+        this.pagePool = this.pagePool.filter((p) => p !== pooledPage);
+      } catch {
+        // Already closed
+      }
+    }
+
+    // Remove idle browsers
+    for (const [key, pooledBrowser] of this.browsers.entries()) {
+      const isIdle =
+        pooledBrowser.activePages.size === 0 &&
+        now - pooledBrowser.lastUsed > this.config.idleTimeout;
+
+      if (isIdle) {
+        try {
+          await pooledBrowser.browser.close();
+          this.browsers.delete(key);
+
+          // Clean up associated pages
+          this.pagePool = this.pagePool.filter((p) => !pooledBrowser.pages.includes(p.page));
+        } catch {
+          // Already closed
+        }
+      }
+    }
+  }
+}

package/src/core/concurrency-resolver.ts

@@ -0,0 +1,154 @@
+/**
+ * src/core/concurrency-resolver.ts
+ *
+ * Implements Phase 1 concurrency resolution, hosted-environment guards,
+ * and deterministic bounded-concurrency execution pool.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { ConcurrencyOptions } from '../types/contracts';
+
+export interface ResolvedConcurrency {
+  concurrency: boolean;
+  concurrencyAmount: number;
+  isHosted: boolean;
+  downgradedDueToHosted: boolean;
+}
+
+/**
+ * Detects whether the current process is running in a constrained hosted environment
+ * (Render.com or any service with HAUNT_HOSTED=1).
+ */
+export function isHostedEnvironment(): boolean {
+  return (
+    process.env.RENDER === 'true' ||
+    process.env.HAUNT_HOSTED === '1' ||
+    process.env.HAUNT_HOSTED === 'true'
+  );
+}
+
+/**
+ * Checks whether an operator has explicitly authorized concurrency in a hosted environment.
+ */
+export function isConcurrencyAllowedInHosted(): boolean {
+  return (
+    process.env.HAUNT_ALLOW_CONCURRENCY === '1' || process.env.HAUNT_ALLOW_CONCURRENCY === 'true'
+  );
+}
+
+/**
+ * Attempts to load stored user config from ~/.hauntview/config.json
+ */
+export function loadUserConfig(): Partial<ConcurrencyOptions> | null {
+  try {
+    const configPath = path.join(os.homedir(), '.hauntview', 'config.json');
+    if (fs.existsSync(configPath)) {
+      const content = fs.readFileSync(configPath, 'utf8');
+      return JSON.parse(content);
+    }
+  } catch {
+    // Ignore invalid/unreadable config files
+  }
+  return null;
+}
+
+/**
+ * Resolves concurrency options according to the strict 4-level precedence:
+ * 1. Explicit per-call options
+ * 2. Environment variables: HAUNT_CONCURRENCY and HAUNT_CONCURRENCY_AMOUNT
+ * 3. User configuration file (~/.hauntview/config.json)
+ * 4. Built-in defaults: concurrency=false, concurrencyAmount=2
+ *
+ * Hosted Guard: If running in a hosted environment without explicit override,
+ * concurrency is forced to false.
+ */
+export function resolveConcurrency(
+  options?: Partial<ConcurrencyOptions>,
+  configOverride?: Partial<ConcurrencyOptions>
+): ResolvedConcurrency {
+  const isHosted = isHostedEnvironment();
+  const allowHosted = isConcurrencyAllowedInHosted();
+  const userConfig = configOverride ?? loadUserConfig() ?? {};
+
+  // 1. Resolve raw concurrency boolean
+  let rawConcurrency: boolean;
+  if (options?.concurrency !== undefined) {
+    rawConcurrency = Boolean(options.concurrency);
+  } else if (process.env.HAUNT_CONCURRENCY !== undefined) {
+    rawConcurrency =
+      process.env.HAUNT_CONCURRENCY === 'true' || process.env.HAUNT_CONCURRENCY === '1';
+  } else if (userConfig.concurrency !== undefined) {
+    rawConcurrency = Boolean(userConfig.concurrency);
+  } else {
+    rawConcurrency = false;
+  }
+
+  // 2. Resolve raw concurrency amount (int >= 1, default 2)
+  let rawAmount: number;
+  if (options?.concurrencyAmount !== undefined) {
+    rawAmount = Math.max(1, Math.floor(Number(options.concurrencyAmount)));
+  } else if (process.env.HAUNT_CONCURRENCY_AMOUNT !== undefined) {
+    const parsed = parseInt(process.env.HAUNT_CONCURRENCY_AMOUNT, 10);
+    rawAmount = Number.isNaN(parsed) || parsed < 1 ? 2 : parsed;
+  } else if (userConfig.concurrencyAmount !== undefined) {
+    rawAmount = Math.max(1, Math.floor(Number(userConfig.concurrencyAmount)));
+  } else {
+    rawAmount = 2;
+  }
+
+  // 3. Apply Hosted Guard
+  let effectiveConcurrency = rawConcurrency;
+  let downgradedDueToHosted = false;
+
+  if (isHosted && !allowHosted && rawConcurrency) {
+    effectiveConcurrency = false;
+    downgradedDueToHosted = true;
+  }
+
+  return {
+    concurrency: effectiveConcurrency,
+    concurrencyAmount: rawAmount,
+    isHosted,
+    downgradedDueToHosted,
+  };
+}
+
+/**
+ * Executes a list of async task factories with a bounded concurrency pool.
+ * Guarantees:
+ * - Active concurrency never exceeds `concurrencyLimit`.
+ * - Result ordering strictly matches the input task order.
+ * - Failure isolation: exceptions handled via `onFailure` without aborting other tasks.
+ */
+export async function executeWithConcurrency<T>(
+  tasks: (() => Promise<T>)[],
+  concurrencyLimit: number,
+  options?: { onFailure?: (index: number, error: unknown) => T }
+): Promise<T[]> {
+  const limit = Math.max(1, concurrencyLimit);
+  const results: T[] = new Array(tasks.length);
+  let nextTaskIndex = 0;
+
+  async function worker() {
+    while (nextTaskIndex < tasks.length) {
+      const currentIndex = nextTaskIndex++;
+      try {
+        results[currentIndex] = await tasks[currentIndex]();
+      } catch (err) {
+        if (options?.onFailure) {
+          results[currentIndex] = options.onFailure(currentIndex, err);
+        } else {
+          throw err;
+        }
+      }
+    }
+  }
+
+  const workerCount = Math.min(limit, tasks.length);
+  const workers = Array.from({ length: workerCount }, () => worker());
+
+  await Promise.all(workers);
+  return results;
+}