@showrun/core 0.1.0

package/dist/browserLauncher.js

@@ -0,0 +1,159 @@
+/**
+ * Unified browser launcher
+ *
+ * Provides a unified interface for launching browsers with different engines
+ * (Chromium, Camoufox) and persistence modes.
+ */
+import { chromium } from 'playwright';
+import { resolveBrowserDataDir } from './browserPersistence.js';
+/**
+ * Launches a browser with the specified configuration
+ *
+ * @param config - Browser launch configuration
+ * @returns Browser session with context, page, and close function
+ */
+export async function launchBrowser(config) {
+    const { browserSettings = {}, headless = true, sessionId, packPath, } = config;
+    const engine = browserSettings.engine ?? 'camoufox';
+    const persistence = browserSettings.persistence ?? 'none';
+    // Resolve user data directory based on persistence mode
+    const userDataDir = resolveBrowserDataDir({
+        persistence,
+        sessionId,
+        packPath,
+    });
+    if (engine === 'camoufox') {
+        return launchCamoufox({
+            headless,
+            userDataDir,
+            persistence,
+        });
+    }
+    // Default: Chromium
+    return launchChromium({
+        headless,
+        userDataDir,
+        persistence,
+    });
+}
+/**
+ * Launches Chromium browser
+ */
+async function launchChromium(config) {
+    const { headless, userDataDir, persistence } = config;
+    let browser;
+    let context;
+    let page;
+    if (userDataDir) {
+        // Use persistent context when user data dir is specified
+        context = await chromium.launchPersistentContext(userDataDir, {
+            headless,
+        });
+        browser = null; // Persistent context doesn't expose browser
+        page = context.pages()[0] || await context.newPage();
+    }
+    else {
+        // Ephemeral browser
+        browser = await chromium.launch({ headless });
+        context = await browser.newContext();
+        page = await context.newPage();
+    }
+    return {
+        context,
+        page,
+        browser,
+        engine: 'chromium',
+        persistence,
+        userDataDir,
+        async close() {
+            if (browser) {
+                await browser.close().catch(() => { });
+            }
+            else {
+                await context.close().catch(() => { });
+            }
+        },
+    };
+}
+/**
+ * Launches Camoufox browser (Firefox-based anti-detection)
+ *
+ * Note: When user_data_dir is provided, Camoufox returns a BrowserContext directly
+ * (not a Browser). This is different from the ephemeral case where it returns Browser.
+ */
+async function launchCamoufox(config) {
+    const { headless, userDataDir, persistence } = config;
+    // Desktop-only screen constraints to prevent mobile fingerprints
+    const screen = { minWidth: 1024, minHeight: 768 };
+    // Dynamic import to avoid loading Camoufox when not needed
+    let Camoufox;
+    try {
+        const camoufoxModule = await import('camoufox-js');
+        Camoufox = camoufoxModule.Camoufox;
+    }
+    catch (error) {
+        throw new Error('Camoufox is not available. Run "npx camoufox-js fetch" to download the browser. ' +
+            `Error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (userDataDir) {
+        // With user_data_dir, Camoufox returns BrowserContext directly (persistent context)
+        // humanize: adds human-like cursor movement delays (up to 2 seconds)
+        const context = await Camoufox({
+            headless,
+            humanize: 2.0,
+            screen,
+            user_data_dir: userDataDir,
+        });
+        const page = context.pages()[0] || await context.newPage();
+        return {
+            context,
+            page,
+            browser: null, // No browser instance with persistent context
+            engine: 'camoufox',
+            persistence,
+            userDataDir,
+            async close() {
+                await context.close().catch(() => { });
+            },
+        };
+    }
+    // Without user_data_dir, Camoufox returns Browser (ephemeral)
+    // humanize: adds human-like cursor movement delays (up to 2 seconds)
+    const browser = await Camoufox({
+        headless,
+        humanize: 2.0,
+        screen,
+    });
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    return {
+        context,
+        page,
+        browser,
+        engine: 'camoufox',
+        persistence,
+        userDataDir,
+        async close() {
+            await browser.close().catch(() => { });
+        },
+    };
+}
+/**
+ * Checks if a browser engine is available
+ */
+export async function isBrowserEngineAvailable(engine) {
+    if (engine === 'chromium') {
+        // Chromium is always available via Playwright
+        return true;
+    }
+    if (engine === 'camoufox') {
+        try {
+            await import('camoufox-js');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}

package/dist/browserPersistence.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Browser data persistence management
+ *
+ * Handles user data directory resolution for different persistence modes:
+ * - none: No persistence, browser uses ephemeral profile
+ * - session: Temp directory persistence with automatic cleanup
+ * - profile: Pack-local persistent profile
+ */
+import type { BrowserPersistence } from './types.js';
+/**
+ * Configuration for resolving browser data directory
+ */
+export interface BrowserDataDirConfig {
+    /**
+     * Persistence mode
+     */
+    persistence: BrowserPersistence;
+    /**
+     * Session ID (required for 'session' mode)
+     */
+    sessionId?: string;
+    /**
+     * Pack directory path (required for 'profile' mode)
+     */
+    packPath?: string;
+}
+/**
+ * Resolves the user data directory path based on persistence configuration
+ *
+ * @param config - Persistence configuration
+ * @returns User data directory path, or undefined for 'none' persistence
+ */
+export declare function resolveBrowserDataDir(config: BrowserDataDirConfig): string | undefined;
+/**
+ * Cleans up inactive session directories
+ *
+ * Sessions that haven't been accessed in SESSION_INACTIVITY_MS are removed.
+ * Should be called periodically (e.g., on dashboard startup or interval).
+ */
+export declare function cleanupInactiveSessions(): number;
+/**
+ * Gets the session base directory path (for testing/debugging)
+ */
+export declare function getSessionBaseDir(): string;
+/**
+ * Gets the profile directory path for a pack
+ */
+export declare function getProfileDir(packPath: string): string;
+//# sourceMappingURL=browserPersistence.d.ts.map

package/dist/browserPersistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserPersistence.d.ts","sourceRoot":"","sources":["../src/browserPersistence.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAiBrD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,WAAW,EAAE,kBAAkB,CAAC;IAChC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,GAAG,SAAS,CAkCtF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAsChD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/browserPersistence.js

@@ -0,0 +1,143 @@
+/**
+ * Browser data persistence management
+ *
+ * Handles user data directory resolution for different persistence modes:
+ * - none: No persistence, browser uses ephemeral profile
+ * - session: Temp directory persistence with automatic cleanup
+ * - profile: Pack-local persistent profile
+ */
+import { existsSync, mkdirSync, readdirSync, statSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+/**
+ * Session inactivity timeout for cleanup (30 minutes in milliseconds)
+ */
+const SESSION_INACTIVITY_MS = 30 * 60 * 1000;
+/**
+ * Base directory name for session storage in temp
+ */
+const SESSION_BASE_DIR = 'showrun-browser-sessions';
+/**
+ * Profile directory name within pack directory
+ */
+const PROFILE_DIR_NAME = '.browser-profile';
+/**
+ * Resolves the user data directory path based on persistence configuration
+ *
+ * @param config - Persistence configuration
+ * @returns User data directory path, or undefined for 'none' persistence
+ */
+export function resolveBrowserDataDir(config) {
+    const { persistence, sessionId, packPath } = config;
+    switch (persistence) {
+        case 'none':
+            return undefined;
+        case 'session': {
+            if (!sessionId) {
+                console.warn('[browserPersistence] Session persistence requires sessionId, falling back to none');
+                return undefined;
+            }
+            const baseDir = join(tmpdir(), SESSION_BASE_DIR);
+            ensureDir(baseDir);
+            const sessionDir = join(baseDir, sanitizeSessionId(sessionId));
+            ensureDir(sessionDir);
+            // Touch the directory to update mtime for activity tracking
+            touchDirectory(sessionDir);
+            return sessionDir;
+        }
+        case 'profile': {
+            if (!packPath) {
+                console.warn('[browserPersistence] Profile persistence requires packPath, falling back to none');
+                return undefined;
+            }
+            const profileDir = join(packPath, PROFILE_DIR_NAME);
+            ensureDir(profileDir);
+            return profileDir;
+        }
+        default:
+            return undefined;
+    }
+}
+/**
+ * Cleans up inactive session directories
+ *
+ * Sessions that haven't been accessed in SESSION_INACTIVITY_MS are removed.
+ * Should be called periodically (e.g., on dashboard startup or interval).
+ */
+export function cleanupInactiveSessions() {
+    const baseDir = join(tmpdir(), SESSION_BASE_DIR);
+    if (!existsSync(baseDir)) {
+        return 0;
+    }
+    const now = Date.now();
+    let cleanedCount = 0;
+    try {
+        const entries = readdirSync(baseDir);
+        for (const entry of entries) {
+            const sessionDir = join(baseDir, entry);
+            try {
+                const stats = statSync(sessionDir);
+                if (!stats.isDirectory())
+                    continue;
+                const lastAccess = stats.mtime.getTime();
+                const inactiveMs = now - lastAccess;
+                if (inactiveMs > SESSION_INACTIVITY_MS) {
+                    rmSync(sessionDir, { recursive: true, force: true });
+                    cleanedCount++;
+                    console.log(`[browserPersistence] Cleaned up inactive session: ${entry}`);
+                }
+            }
+            catch (error) {
+                // Ignore errors for individual sessions (might be in use)
+                console.warn(`[browserPersistence] Could not check/clean session ${entry}:`, error);
+            }
+        }
+    }
+    catch (error) {
+        console.warn('[browserPersistence] Error during session cleanup:', error);
+    }
+    return cleanedCount;
+}
+/**
+ * Gets the session base directory path (for testing/debugging)
+ */
+export function getSessionBaseDir() {
+    return join(tmpdir(), SESSION_BASE_DIR);
+}
+/**
+ * Gets the profile directory path for a pack
+ */
+export function getProfileDir(packPath) {
+    return join(packPath, PROFILE_DIR_NAME);
+}
+/**
+ * Ensures a directory exists
+ */
+function ensureDir(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+/**
+ * Sanitizes a session ID for use as a directory name
+ */
+function sanitizeSessionId(sessionId) {
+    // Replace unsafe characters with underscores
+    return sessionId.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+/**
+ * Touches a directory to update its mtime
+ */
+function touchDirectory(dir) {
+    try {
+        const now = new Date();
+        // Node doesn't have a direct utimes for directories, but we can use a marker file
+        const markerPath = join(dir, '.last_access');
+        const fs = require('fs');
+        fs.closeSync(fs.openSync(markerPath, 'w'));
+        fs.utimesSync(dir, now, now);
+    }
+    catch {
+        // Ignore errors - touch is best-effort for cleanup tracking
+    }
+}

package/dist/context.d.ts

@@ -0,0 +1,10 @@
+import type { Browser, Page } from 'playwright';
+import type { Logger, RunContext } from './types.js';
+import type { NetworkCaptureApi } from './networkCapture.js';
+/**
+ * Creates a RunContext for task pack execution
+ */
+export declare class RunContextFactory {
+    static create(page: Page, browser: Browser, logger: Logger, artifactsDir: string, networkCapture?: NetworkCaptureApi): RunContext;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAmB,UAAU,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,MAAM,CAAC,MAAM,CACX,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,cAAc,CAAC,EAAE,iBAAiB,GACjC,UAAU;CAyBd"}

package/dist/context.js

@@ -0,0 +1,30 @@
+import { writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+/**
+ * Creates a RunContext for task pack execution
+ */
+export class RunContextFactory {
+    static create(page, browser, logger, artifactsDir, networkCapture) {
+        // Ensure artifacts directory exists
+        mkdirSync(artifactsDir, { recursive: true });
+        const artifacts = {
+            async saveScreenshot(name) {
+                const path = join(artifactsDir, `${name}.png`);
+                await page.screenshot({ path, fullPage: true });
+                return path;
+            },
+            async saveHTML(name, html) {
+                const path = join(artifactsDir, `${name}.html`);
+                writeFileSync(path, html, 'utf-8');
+                return path;
+            },
+        };
+        return {
+            page,
+            browser,
+            logger,
+            artifacts,
+            networkCapture,
+        };
+    }
+}