profclaw 0.0.1-beta.1

package/dist/browser/extensions.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Browser Extensions Support
+ *
+ * Chrome extension loading, CDP proxy with bypass handling,
+ * user data directory / profile management, auth bridge registry,
+ * and extension manifest validation.
+ */
+export interface ExtensionManifest {
+    manifest_version: number;
+    name: string;
+    version: string;
+    description?: string;
+    permissions?: string[];
+    host_permissions?: string[];
+    content_scripts?: Array<{
+        matches: string[];
+        js?: string[];
+        css?: string[];
+        run_at?: 'document_start' | 'document_end' | 'document_idle';
+    }>;
+    background?: {
+        service_worker?: string;
+        scripts?: string[];
+    };
+    action?: {
+        default_popup?: string;
+        default_icon?: string | Record<string, string>;
+    };
+}
+export interface ExtensionInfo {
+    id: string;
+    path: string;
+    manifest: ExtensionManifest;
+    enabled: boolean;
+    valid: boolean;
+    validationErrors: string[];
+}
+export interface BrowserProfile {
+    id: string;
+    name: string;
+    userDataDir: string;
+    extensions: string[];
+    cookies?: boolean;
+    localStorage?: boolean;
+    createdAt: string;
+}
+export interface AuthBridgeEntry {
+    id: string;
+    domain: string;
+    provider: string;
+    cookieNames?: string[];
+    tokenStorage?: 'cookie' | 'localStorage' | 'sessionStorage';
+    enabled: boolean;
+}
+export interface CDPProxyConfig {
+    enabled: boolean;
+    port: number;
+    bypassDomains: string[];
+    interceptPatterns: string[];
+}
+export declare class ExtensionManager {
+    private extensions;
+    private profiles;
+    private authBridges;
+    private cdpConfig;
+    constructor();
+    /**
+     * Load a Chrome extension from a directory
+     */
+    loadExtension(extensionPath: string): ExtensionInfo;
+    /**
+     * Scan a directory for extensions
+     */
+    scanExtensionsDir(dir: string): ExtensionInfo[];
+    /**
+     * Get Playwright launch args for loaded extensions
+     */
+    getExtensionLaunchArgs(): string[];
+    /**
+     * List loaded extensions
+     */
+    listExtensions(): ExtensionInfo[];
+    /**
+     * Enable/disable an extension
+     */
+    toggleExtension(extensionId: string, enabled: boolean): boolean;
+    validateManifest(manifest: ExtensionManifest): string[];
+    /**
+     * Create a browser profile with user data directory
+     */
+    createProfile(name: string, options?: {
+        extensions?: string[];
+    }): BrowserProfile;
+    /**
+     * Get a browser profile
+     */
+    getProfile(profileId: string): BrowserProfile | undefined;
+    /**
+     * List all profiles
+     */
+    listProfiles(): BrowserProfile[];
+    /**
+     * Delete a profile (metadata only, doesn't delete user data dir)
+     */
+    deleteProfile(profileId: string): boolean;
+    /**
+     * Register an auth bridge for a domain
+     */
+    registerAuthBridge(entry: AuthBridgeEntry): void;
+    /**
+     * Get auth bridge for a domain
+     */
+    getAuthBridgeForDomain(domain: string): AuthBridgeEntry | undefined;
+    /**
+     * List auth bridges
+     */
+    listAuthBridges(): AuthBridgeEntry[];
+    /**
+     * Remove an auth bridge
+     */
+    removeAuthBridge(id: string): boolean;
+    /**
+     * Update CDP proxy configuration
+     */
+    setCDPConfig(config: Partial<CDPProxyConfig>): void;
+    /**
+     * Get current CDP proxy configuration
+     */
+    getCDPConfig(): CDPProxyConfig;
+    /**
+     * Add a domain to the CDP bypass list
+     */
+    addBypassDomain(domain: string): void;
+    /**
+     * Remove a domain from the CDP bypass list
+     */
+    removeBypassDomain(domain: string): boolean;
+    /**
+     * Check if a domain should bypass the CDP proxy
+     */
+    shouldBypass(domain: string): boolean;
+}
+export declare function getExtensionManager(): ExtensionManager;
+//# sourceMappingURL=extensions.d.ts.map

package/dist/browser/extensions.js

@@ -0,0 +1,251 @@
+/**
+ * Browser Extensions Support
+ *
+ * Chrome extension loading, CDP proxy with bypass handling,
+ * user data directory / profile management, auth bridge registry,
+ * and extension manifest validation.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { logger } from '../utils/logger.js';
+// Extension Manager
+export class ExtensionManager {
+    extensions = new Map();
+    profiles = new Map();
+    authBridges = new Map();
+    cdpConfig;
+    constructor() {
+        this.cdpConfig = {
+            enabled: false,
+            port: parseInt(process.env.CDP_PROXY_PORT ?? '9222', 10),
+            bypassDomains: [],
+            interceptPatterns: [],
+        };
+    }
+    // Chrome Extension Support
+    /**
+     * Load a Chrome extension from a directory
+     */
+    loadExtension(extensionPath) {
+        const absPath = resolve(extensionPath);
+        const manifestPath = join(absPath, 'manifest.json');
+        if (!existsSync(manifestPath)) {
+            throw new Error(`No manifest.json found at ${absPath}`);
+        }
+        const manifestRaw = readFileSync(manifestPath, 'utf-8');
+        const manifest = JSON.parse(manifestRaw);
+        const validationErrors = this.validateManifest(manifest);
+        const id = `ext_${manifest.name.toLowerCase().replace(/\s+/g, '-')}_${manifest.version}`;
+        const info = {
+            id,
+            path: absPath,
+            manifest,
+            enabled: true,
+            valid: validationErrors.length === 0,
+            validationErrors,
+        };
+        this.extensions.set(id, info);
+        logger.info(`[Browser] Extension loaded: ${manifest.name} v${manifest.version}`, { component: 'ExtensionManager' });
+        return info;
+    }
+    /**
+     * Scan a directory for extensions
+     */
+    scanExtensionsDir(dir) {
+        const absDir = resolve(dir);
+        if (!existsSync(absDir))
+            return [];
+        const loaded = [];
+        const entries = readdirSync(absDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const extPath = join(absDir, entry.name);
+            if (existsSync(join(extPath, 'manifest.json'))) {
+                try {
+                    loaded.push(this.loadExtension(extPath));
+                }
+                catch (err) {
+                    logger.warn(`[Browser] Failed to load extension at ${extPath}: ${err instanceof Error ? err.message : 'unknown'}`, { component: 'ExtensionManager' });
+                }
+            }
+        }
+        return loaded;
+    }
+    /**
+     * Get Playwright launch args for loaded extensions
+     */
+    getExtensionLaunchArgs() {
+        const enabledPaths = Array.from(this.extensions.values())
+            .filter((ext) => ext.enabled && ext.valid)
+            .map((ext) => ext.path);
+        if (enabledPaths.length === 0)
+            return [];
+        return [
+            `--disable-extensions-except=${enabledPaths.join(',')}`,
+            `--load-extension=${enabledPaths.join(',')}`,
+        ];
+    }
+    /**
+     * List loaded extensions
+     */
+    listExtensions() {
+        return Array.from(this.extensions.values());
+    }
+    /**
+     * Enable/disable an extension
+     */
+    toggleExtension(extensionId, enabled) {
+        const ext = this.extensions.get(extensionId);
+        if (!ext)
+            return false;
+        ext.enabled = enabled;
+        return true;
+    }
+    // Extension Manifest Validation
+    validateManifest(manifest) {
+        const errors = [];
+        if (!manifest.manifest_version || ![2, 3].includes(manifest.manifest_version)) {
+            errors.push('manifest_version must be 2 or 3');
+        }
+        if (!manifest.name || typeof manifest.name !== 'string') {
+            errors.push('name is required and must be a string');
+        }
+        if (!manifest.version || !/^\d+\.\d+(\.\d+)?$/.test(manifest.version)) {
+            errors.push('version must be in semver format (x.y or x.y.z)');
+        }
+        // Check for dangerous permissions
+        const dangerousPerms = ['debugger', 'nativeMessaging', 'proxy'];
+        const requestedPerms = manifest.permissions ?? [];
+        for (const perm of dangerousPerms) {
+            if (requestedPerms.includes(perm)) {
+                errors.push(`Dangerous permission requested: ${perm}`);
+            }
+        }
+        // Check host permissions for overly broad access
+        const hostPerms = manifest.host_permissions ?? [];
+        if (hostPerms.includes('<all_urls>') || hostPerms.includes('*://*/*')) {
+            errors.push('Extension requests access to all URLs - review carefully');
+        }
+        // MV3 validation
+        if (manifest.manifest_version === 3) {
+            if (manifest.background?.scripts) {
+                errors.push('MV3 extensions must use service_worker, not background scripts');
+            }
+        }
+        return errors;
+    }
+    // User Data Directory / Profile Management
+    /**
+     * Create a browser profile with user data directory
+     */
+    createProfile(name, options) {
+        const id = `profile_${name.toLowerCase().replace(/\s+/g, '-')}`;
+        const userDataDir = join(homedir(), '.profclaw', 'browser-profiles', id);
+        const profile = {
+            id,
+            name,
+            userDataDir,
+            extensions: options?.extensions ?? [],
+            cookies: true,
+            localStorage: true,
+            createdAt: new Date().toISOString(),
+        };
+        this.profiles.set(id, profile);
+        logger.info(`[Browser] Profile created: ${name} at ${userDataDir}`, { component: 'ExtensionManager' });
+        return profile;
+    }
+    /**
+     * Get a browser profile
+     */
+    getProfile(profileId) {
+        return this.profiles.get(profileId);
+    }
+    /**
+     * List all profiles
+     */
+    listProfiles() {
+        return Array.from(this.profiles.values());
+    }
+    /**
+     * Delete a profile (metadata only, doesn't delete user data dir)
+     */
+    deleteProfile(profileId) {
+        return this.profiles.delete(profileId);
+    }
+    // Auth Bridge Registry
+    /**
+     * Register an auth bridge for a domain
+     */
+    registerAuthBridge(entry) {
+        this.authBridges.set(entry.id, entry);
+        logger.info(`[Browser] Auth bridge registered: ${entry.domain} via ${entry.provider}`, { component: 'ExtensionManager' });
+    }
+    /**
+     * Get auth bridge for a domain
+     */
+    getAuthBridgeForDomain(domain) {
+        return Array.from(this.authBridges.values()).find((b) => b.enabled && (b.domain === domain || domain.endsWith(`.${b.domain}`)));
+    }
+    /**
+     * List auth bridges
+     */
+    listAuthBridges() {
+        return Array.from(this.authBridges.values());
+    }
+    /**
+     * Remove an auth bridge
+     */
+    removeAuthBridge(id) {
+        return this.authBridges.delete(id);
+    }
+    // CDP Proxy Configuration
+    /**
+     * Update CDP proxy configuration
+     */
+    setCDPConfig(config) {
+        this.cdpConfig = { ...this.cdpConfig, ...config };
+        logger.info(`[Browser] CDP config updated: port=${this.cdpConfig.port}, enabled=${this.cdpConfig.enabled}`, { component: 'ExtensionManager' });
+    }
+    /**
+     * Get current CDP proxy configuration
+     */
+    getCDPConfig() {
+        return { ...this.cdpConfig };
+    }
+    /**
+     * Add a domain to the CDP bypass list
+     */
+    addBypassDomain(domain) {
+        if (!this.cdpConfig.bypassDomains.includes(domain)) {
+            this.cdpConfig.bypassDomains.push(domain);
+        }
+    }
+    /**
+     * Remove a domain from the CDP bypass list
+     */
+    removeBypassDomain(domain) {
+        const idx = this.cdpConfig.bypassDomains.indexOf(domain);
+        if (idx >= 0) {
+            this.cdpConfig.bypassDomains.splice(idx, 1);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Check if a domain should bypass the CDP proxy
+     */
+    shouldBypass(domain) {
+        return this.cdpConfig.bypassDomains.some((d) => domain === d || domain.endsWith(`.${d}`));
+    }
+}
+// Singleton
+let extensionManager = null;
+export function getExtensionManager() {
+    if (!extensionManager) {
+        extensionManager = new ExtensionManager();
+    }
+    return extensionManager;
+}
+//# sourceMappingURL=extensions.js.map

package/dist/browser/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Browser Automation Module
+ *
+ * Playwright-based browser automation for profClaw AI agents.
+ *
+ * @example
+ * ```typescript
+ * import { getBrowserService } from './browser/index.js';
+ *
+ * const browser = getBrowserService();
+ *
+ * // Navigate to a page
+ * const { pageId } = await browser.navigate('https://example.com');
+ *
+ * // Get accessibility snapshot
+ * const snapshot = await browser.snapshot({ pageId });
+ *
+ * // Click an element
+ * await browser.click({ ref: 'e3', pageId });
+ *
+ * // Type into an input
+ * await browser.type({ ref: 'e5', text: 'Hello', pageId });
+ *
+ * // Search for elements
+ * const results = await browser.search({ pattern: 'Submit', pageId });
+ * ```
+ */
+export type { BrowserPage, ElementRef, SnapshotNode, PageSnapshot, SearchResult, SearchResponse, NavigateOptions, NavigateResult, SnapshotOptions, ClickOptions, ClickResult, TypeOptions, TypeResult, ContentSearchOptions, ScreenshotOptions, ScreenshotResult, BrowserConfig, } from './types.js';
+export { BrowserError } from './types.js';
+export { BrowserService, getBrowserService, resetBrowserService, formatSnapshotResponse, formatSearchResponse, } from './service.js';
+export { RefTracker, getRefTracker, resetRefTracker, clearAllTrackers, } from './refs.js';
+export { captureSnapshot } from './snapshot.js';
+export { searchSnapshot, searchByRole, findInteractiveElements, commonPatterns, } from './search.js';
+export { compressTree, treeToYaml, getCompressionStats, } from './compression.js';
+export { BROWSER_TOOLS, BROWSER_TOOL_NAMES, SAFE_BROWSER_TOOLS, SAFE_BROWSER_TOOL_NAMES, type BrowserToolDefinition, type BrowserToolResult, } from './tools.js';
+export { MCP_BROWSER_TOOLS, handleMCPBrowserTool, CHAT_BROWSER_TOOLS, getChatBrowserTool, } from './adapters.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/browser/index.js

@@ -0,0 +1,43 @@
+/**
+ * Browser Automation Module
+ *
+ * Playwright-based browser automation for profClaw AI agents.
+ *
+ * @example
+ * ```typescript
+ * import { getBrowserService } from './browser/index.js';
+ *
+ * const browser = getBrowserService();
+ *
+ * // Navigate to a page
+ * const { pageId } = await browser.navigate('https://example.com');
+ *
+ * // Get accessibility snapshot
+ * const snapshot = await browser.snapshot({ pageId });
+ *
+ * // Click an element
+ * await browser.click({ ref: 'e3', pageId });
+ *
+ * // Type into an input
+ * await browser.type({ ref: 'e5', text: 'Hello', pageId });
+ *
+ * // Search for elements
+ * const results = await browser.search({ pattern: 'Submit', pageId });
+ * ```
+ */
+export { BrowserError } from './types.js';
+// Service
+export { BrowserService, getBrowserService, resetBrowserService, formatSnapshotResponse, formatSearchResponse, } from './service.js';
+// Ref tracking
+export { RefTracker, getRefTracker, resetRefTracker, clearAllTrackers, } from './refs.js';
+// Snapshot
+export { captureSnapshot } from './snapshot.js';
+// Search
+export { searchSnapshot, searchByRole, findInteractiveElements, commonPatterns, } from './search.js';
+// Compression
+export { compressTree, treeToYaml, getCompressionStats, } from './compression.js';
+// Tools (Single Source of Truth)
+export { BROWSER_TOOLS, BROWSER_TOOL_NAMES, SAFE_BROWSER_TOOLS, SAFE_BROWSER_TOOL_NAMES, } from './tools.js';
+// Adapters (MCP + Chat Execution)
+export { MCP_BROWSER_TOOLS, handleMCPBrowserTool, CHAT_BROWSER_TOOLS, getChatBrowserTool, } from './adapters.js';
+//# sourceMappingURL=index.js.map

package/dist/browser/refs.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Element Reference Tracking
+ *
+ * Manages element refs (e1, e2, etc.) for accessibility tree snapshots.
+ * Refs allow AI agents to target elements without complex selectors.
+ */
+import type { ElementRef } from './types.js';
+export declare class RefTracker {
+    private refs;
+    private counter;
+    private pageId;
+    constructor(pageId: string);
+    /**
+     * Generate a new ref for an element
+     */
+    generateRef(role: string, name: string, selector: string, attributes?: Record<string, string>): string;
+    /**
+     * Get element info by ref
+     */
+    getRef(ref: string): ElementRef | undefined;
+    /**
+     * Get all refs
+     */
+    getAllRefs(): Map<string, ElementRef>;
+    /**
+     * Reset refs for new snapshot
+     */
+    reset(): void;
+    /**
+     * Get count of tracked refs
+     */
+    get count(): number;
+    /**
+     * Build a Playwright locator from a ref
+     *
+     * Priority order:
+     * 1. getByRole with name (most accessible)
+     * 2. getByText (for links/buttons)
+     * 3. CSS selector (fallback)
+     */
+    buildLocatorCode(ref: string): string | null;
+}
+export declare function getRefTracker(pageId: string): RefTracker;
+export declare function resetRefTracker(pageId: string): void;
+export declare function clearAllTrackers(): void;
+//# sourceMappingURL=refs.d.ts.map

package/dist/browser/refs.js

@@ -0,0 +1,120 @@
+/**
+ * Element Reference Tracking
+ *
+ * Manages element refs (e1, e2, etc.) for accessibility tree snapshots.
+ * Refs allow AI agents to target elements without complex selectors.
+ */
+export class RefTracker {
+    refs = new Map();
+    counter = 0;
+    pageId;
+    constructor(pageId) {
+        this.pageId = pageId;
+    }
+    /**
+     * Generate a new ref for an element
+     */
+    generateRef(role, name, selector, attributes) {
+        this.counter++;
+        const ref = `e${this.counter}`;
+        this.refs.set(ref, {
+            ref,
+            role,
+            name,
+            selector,
+            attributes,
+        });
+        return ref;
+    }
+    /**
+     * Get element info by ref
+     */
+    getRef(ref) {
+        return this.refs.get(ref);
+    }
+    /**
+     * Get all refs
+     */
+    getAllRefs() {
+        return new Map(this.refs);
+    }
+    /**
+     * Reset refs for new snapshot
+     */
+    reset() {
+        this.refs.clear();
+        this.counter = 0;
+    }
+    /**
+     * Get count of tracked refs
+     */
+    get count() {
+        return this.refs.size;
+    }
+    /**
+     * Build a Playwright locator from a ref
+     *
+     * Priority order:
+     * 1. getByRole with name (most accessible)
+     * 2. getByText (for links/buttons)
+     * 3. CSS selector (fallback)
+     */
+    buildLocatorCode(ref) {
+        const element = this.refs.get(ref);
+        if (!element)
+            return null;
+        const { role, name, selector } = element;
+        // Prefer role-based locators
+        const roleLocators = {
+            'button': 'button',
+            'link': 'link',
+            'textbox': 'textbox',
+            'checkbox': 'checkbox',
+            'radio': 'radio',
+            'combobox': 'combobox',
+            'listbox': 'listbox',
+            'slider': 'slider',
+            'spinbutton': 'spinbutton',
+            'searchbox': 'searchbox',
+            'switch': 'switch',
+            'tab': 'tab',
+            'menuitem': 'menuitem',
+            'option': 'option',
+            'heading': 'heading',
+            'img': 'img',
+        };
+        if (roleLocators[role] && name) {
+            const escapedName = name.replace(/'/g, "\\'");
+            return `page.getByRole('${roleLocators[role]}', { name: '${escapedName}' })`;
+        }
+        if (name && (role === 'link' || role === 'button')) {
+            const escapedName = name.replace(/'/g, "\\'");
+            return `page.getByText('${escapedName}')`;
+        }
+        // Fallback to CSS selector
+        if (selector) {
+            const escapedSelector = selector.replace(/'/g, "\\'");
+            return `page.locator('${escapedSelector}')`;
+        }
+        return null;
+    }
+}
+/**
+ * Global ref tracker registry (per page)
+ */
+const pageTrackers = new Map();
+export function getRefTracker(pageId) {
+    let tracker = pageTrackers.get(pageId);
+    if (!tracker) {
+        tracker = new RefTracker(pageId);
+        pageTrackers.set(pageId, tracker);
+    }
+    return tracker;
+}
+export function resetRefTracker(pageId) {
+    pageTrackers.delete(pageId);
+}
+export function clearAllTrackers() {
+    pageTrackers.clear();
+}
+//# sourceMappingURL=refs.js.map

package/dist/browser/search.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Content Search
+ *
+ * Search page snapshots for text/patterns using regex.
+ * Returns matching elements with their refs for interaction.
+ */
+import type { SnapshotNode, SearchResult, SearchResponse, ContentSearchOptions } from './types.js';
+/**
+ * Search a snapshot tree for matching content
+ */
+export declare function searchSnapshot(tree: SnapshotNode, options: ContentSearchOptions): SearchResponse;
+/**
+ * Format search results for MCP response
+ */
+export declare function formatSearchResponse(response: SearchResponse): string;
+/**
+ * Search by role
+ */
+export declare function searchByRole(tree: SnapshotNode, role: string): SearchResult[];
+/**
+ * Find interactive elements
+ */
+export declare function findInteractiveElements(tree: SnapshotNode): SearchResult[];
+/**
+ * Search for specific patterns commonly needed
+ */
+export declare const commonPatterns: {
+    textInputs: (tree: SnapshotNode) => SearchResult[];
+    buttons: (tree: SnapshotNode) => SearchResult[];
+    links: (tree: SnapshotNode) => SearchResult[];
+    checkboxes: (tree: SnapshotNode) => SearchResult[];
+    prices: (tree: SnapshotNode) => SearchResponse;
+    emails: (tree: SnapshotNode) => SearchResponse;
+    phones: (tree: SnapshotNode) => SearchResponse;
+};
+//# sourceMappingURL=search.d.ts.map