@aluvia/sdk 1.0.0 → 1.3.0

package/dist/cjs/client/PageLoadDetection.js

@@ -0,0 +1,175 @@
+"use strict";
+// PageLoadDetection - Enhanced page load and blocking detection
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PageLoadDetection = void 0;
+const DEFAULT_BLOCKING_KEYWORDS = [
+    "captcha",
+    "blocked",
+    "access denied",
+    "forbidden",
+    "cloudflare",
+    "please verify",
+    "recaptcha",
+    "hcaptcha",
+    "bot detection",
+    "automated access",
+    "unusual activity",
+    "verify you are human",
+    "security check",
+    "access restricted",
+];
+const DEFAULT_BLOCKING_STATUS_CODES = [403, 429, 503];
+const DEFAULT_MIN_CONTENT_LENGTH = 100;
+/**
+ * PageLoadDetection handles enhanced detection of page load failures and blocking
+ */
+class PageLoadDetection {
+    constructor(config, logger) {
+        this.blockedHostnames = new Set();
+        this.logger = logger;
+        this.config = {
+            enabled: config.enabled ?? true,
+            blockingKeywords: config.blockingKeywords ?? DEFAULT_BLOCKING_KEYWORDS,
+            blockingStatusCodes: config.blockingStatusCodes ?? DEFAULT_BLOCKING_STATUS_CODES,
+            minContentLength: config.minContentLength ?? DEFAULT_MIN_CONTENT_LENGTH,
+            autoAddRules: config.autoAddRules ?? false,
+            onBlockingDetected: config.onBlockingDetected,
+        };
+    }
+    /**
+     * Update detection configuration
+     */
+    updateConfig(config) {
+        if (config.enabled !== undefined) {
+            this.config.enabled = config.enabled;
+        }
+        if (config.blockingKeywords !== undefined) {
+            this.config.blockingKeywords = config.blockingKeywords;
+        }
+        if (config.blockingStatusCodes !== undefined) {
+            this.config.blockingStatusCodes = config.blockingStatusCodes;
+        }
+        if (config.minContentLength !== undefined) {
+            this.config.minContentLength = config.minContentLength;
+        }
+        if (config.autoAddRules !== undefined) {
+            this.config.autoAddRules = config.autoAddRules;
+        }
+        if (config.onBlockingDetected !== undefined) {
+            this.config.onBlockingDetected = config.onBlockingDetected;
+        }
+    }
+    /**
+     * Check if a hostname is already marked as blocked
+     */
+    isHostnameBlocked(hostname) {
+        return this.blockedHostnames.has(hostname);
+    }
+    /**
+     * Get all blocked hostnames
+     */
+    getBlockedHostnames() {
+        return Array.from(this.blockedHostnames);
+    }
+    /**
+     * Clear blocked hostnames cache
+     */
+    clearBlockedHostnames() {
+        this.blockedHostnames.clear();
+    }
+    /**
+     * Analyze a page load and detect if it was blocked
+     */
+    async analyzePage(page, response) {
+        if (!this.config.enabled) {
+            return {
+                url: page.url(),
+                hostname: this.extractHostname(page.url()),
+                success: true,
+                blocked: false,
+            };
+        }
+        this.logger.debug("Analyzing page load for URL: " + page.url());
+        const url = page.url();
+        const hostname = this.extractHostname(url);
+        try {
+            // Check HTTP status code
+            const statusCode = response?.status?.() ?? 0;
+            if (statusCode > 0 &&
+                this.config.blockingStatusCodes.includes(statusCode)) {
+                const reason = {
+                    type: "status_code",
+                    details: `HTTP status code ${statusCode} indicates blocking`,
+                    statusCode,
+                };
+                await this.handleBlocking(hostname, reason, page);
+                return { url, hostname, success: false, blocked: true, reason };
+            }
+            // Get page content
+            const content = await page.content().catch(() => "");
+            // Check for blocking keywords first (more specific than content length)
+            const contentLower = content.toLowerCase();
+            const title = (await page.title().catch(() => "")).toLowerCase();
+            const combinedText = `${contentLower} ${title}`;
+            for (const keyword of this.config.blockingKeywords) {
+                if (combinedText.includes(keyword.toLowerCase())) {
+                    const reason = {
+                        type: "keyword",
+                        details: `Blocking keyword detected: "${keyword}"`,
+                        keyword,
+                    };
+                    await this.handleBlocking(hostname, reason, page);
+                    return { url, hostname, success: false, blocked: true, reason };
+                }
+            }
+            // Check content length (less critical than keywords)
+            if (!content || content.length < this.config.minContentLength) {
+                const reason = {
+                    type: "content_length",
+                    details: `Page content too short (${content.length} < ${this.config.minContentLength})`,
+                };
+                this.logger.warn(`Page may have failed to load: ${url} (${reason.details})`);
+                return { url, hostname, success: false, blocked: false, reason };
+            }
+            // Page loaded successfully
+            return { url, hostname, success: true, blocked: false };
+        }
+        catch (error) {
+            const reason = {
+                type: "error",
+                details: `Error analyzing page: ${error.message}`,
+            };
+            this.logger.warn(`Error checking page load status for ${url}: ${error.message}`);
+            return { url, hostname, success: false, blocked: false, reason };
+        }
+    }
+    /**
+     * Handle detected blocking
+     */
+    async handleBlocking(hostname, reason, page) {
+        this.blockedHostnames.add(hostname);
+        this.logger.warn(`Blocking detected for ${hostname}: ${reason.details}`);
+        // Trigger callback if provided
+        if (this.config.onBlockingDetected) {
+            try {
+                await this.config.onBlockingDetected(hostname, reason, page);
+            }
+            catch (error) {
+                this.logger.warn(`Error in onBlockingDetected callback: ${error.message}`);
+            }
+        }
+    }
+    /**
+     * Extract hostname from URL
+     */
+    extractHostname(url) {
+        try {
+            const parsed = new URL(url);
+            return parsed.hostname;
+        }
+        catch {
+            return url;
+        }
+    }
+}
+exports.PageLoadDetection = PageLoadDetection;

package/dist/cjs/client/ProxyServer.js

@@ -97,8 +97,10 @@ class ProxyServer {
             this.logger.debug('Could not extract hostname, going direct');
             return undefined;
         }
-        // Check if we should proxy this hostname
-        const useProxy = (0, rules_js_1.shouldProxy)(hostname, config.rules);
+        // Check if we should proxy this hostname (use pre-normalized rules if available)
+        const useProxy = config.normalizedRules
+            ? (0, rules_js_1.shouldProxyNormalized)(hostname, config.normalizedRules)
+            : (0, rules_js_1.shouldProxy)(hostname, config.rules);
         if (!useProxy) {
             this.logger.debug(`Hostname ${hostname} bypassing proxy (direct)`);
             return undefined;

package/dist/cjs/client/logger.js

@@ -32,6 +32,10 @@ class Logger {
             console.debug('[aluvia][debug]', ...args);
         }
     }
+    /** Check if debug logging is enabled. */
+    get isDebug() {
+        return this.level === 'debug';
+    }
     /**
      * Log warning messages.
      * Logs when level is not 'silent'.

package/dist/cjs/client/rules.js

@@ -2,6 +2,8 @@
 // Rule engine for hostname matching and proxy decision
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.matchPattern = matchPattern;
+exports.normalizeRules = normalizeRules;
+exports.shouldProxyNormalized = shouldProxyNormalized;
 exports.shouldProxy = shouldProxy;
 /**
  * Match a hostname against a pattern.
@@ -55,48 +57,26 @@ function matchPattern(hostname, pattern) {
     return false;
 }
 /**
- * Determine if a hostname should be proxied based on rules.
- *
- * Rules semantics:
- * - [] (empty) → no proxy (return false)
- * - ['*'] → proxy everything
- * - ['example.com'] → proxy only example.com
- * - ['*.google.com'] → proxy subdomains of google.com
- * - ['*', '-example.com'] → proxy everything except example.com
- * - ['AUTO', 'example.com'] → AUTO is placeholder (ignored), proxy example.com
- *
- * Negative patterns (prefixed with '-') exclude hosts from proxying.
- * If '*' is in rules, default is to proxy unless excluded.
- * Without '*', only explicitly matched patterns are proxied.
- *
- * @param hostname - The hostname to check
- * @param rules - Array of rule patterns
- * @returns true if the hostname should be proxied
+ * Pre-process raw rule strings into a NormalizedRules structure.
+ * Call once when config is loaded, then use shouldProxyNormalized() per request.
  */
-function shouldProxy(hostname, rules) {
-    const normalizedHostname = hostname.trim();
-    if (!normalizedHostname)
-        return false;
-    // Empty rules means no proxy
+function normalizeRules(rules) {
     if (!rules || rules.length === 0) {
-        return false;
+        return { positiveRules: [], negativeRules: [], hasCatchAll: false, empty: true };
     }
-    const normalizedRules = rules
+    const trimmed = rules
         .filter((r) => typeof r === 'string')
-        .map((r) => r.trim())
-        .filter((r) => r.length > 0);
-    // Filter out AUTO placeholder
-    const effectiveRules = normalizedRules.filter((r) => r.toUpperCase() !== 'AUTO');
-    // If no effective rules after filtering, no proxy
-    if (effectiveRules.length === 0) {
-        return false;
+        .map((r) => r.trim().toLowerCase())
+        .filter((r) => r.length > 0)
+        .filter((r) => r !== 'auto');
+    if (trimmed.length === 0) {
+        return { positiveRules: [], negativeRules: [], hasCatchAll: false, empty: true };
     }
-    // Separate positive and negative rules
     const negativeRules = [];
     const positiveRules = [];
-    for (const rule of effectiveRules) {
+    for (const rule of trimmed) {
         if (rule.startsWith('-')) {
-            const neg = rule.slice(1).trim(); // Remove the '-' prefix
+            const neg = rule.slice(1).trim();
             if (neg.length > 0)
                 negativeRules.push(neg);
         }
@@ -104,25 +84,34 @@ function shouldProxy(hostname, rules) {
             positiveRules.push(rule);
         }
     }
-    // Check if hostname matches any negative rule
-    for (const negRule of negativeRules) {
-        if (matchPattern(normalizedHostname, negRule)) {
-            // Excluded by negative rule
+    return {
+        positiveRules,
+        negativeRules,
+        hasCatchAll: positiveRules.includes('*'),
+        empty: false,
+    };
+}
+/**
+ * Fast proxy decision using pre-normalized rules.
+ */
+function shouldProxyNormalized(hostname, rules) {
+    const normalizedHostname = hostname.trim().toLowerCase();
+    if (!normalizedHostname)
+        return false;
+    if (rules.empty)
+        return false;
+    for (const negRule of rules.negativeRules) {
+        if (matchPattern(normalizedHostname, negRule))
             return false;
-        }
     }
-    // Check if we have a catch-all '*'
-    const hasCatchAll = positiveRules.includes('*');
-    if (hasCatchAll) {
-        // With catch-all, proxy everything not excluded by negative rules
+    if (rules.hasCatchAll)
         return true;
-    }
-    // Without catch-all, check if hostname matches any positive rule
-    for (const posRule of positiveRules) {
-        if (matchPattern(normalizedHostname, posRule)) {
+    for (const posRule of rules.positiveRules) {
+        if (matchPattern(normalizedHostname, posRule))
             return true;
-        }
     }
-    // No match found
     return false;
 }
+function shouldProxy(hostname, rules) {
+    return shouldProxyNormalized(hostname, normalizeRules(rules));
+}

package/dist/cjs/connect.js

@@ -0,0 +1,117 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connect = connect;
+const lock_js_1 = require("./session/lock.js");
+const errors_js_1 = require("./errors.js");
+/**
+ * Connect to a running Aluvia browser session via CDP.
+ *
+ * - No args: auto-discovers a single running session.
+ * - With session name: connects to that specific session.
+ *
+ * Requires `playwright` as a peer dependency.
+ */
+async function connect(sessionName) {
+    // 1. Import Playwright
+    let pw;
+    try {
+        pw = await Promise.resolve().then(() => __importStar(require('playwright')));
+    }
+    catch {
+        throw new errors_js_1.ConnectError('Playwright is required for connect(). Install it: npm install playwright');
+    }
+    // 2. Resolve session
+    let resolvedName;
+    if (sessionName) {
+        resolvedName = sessionName;
+    }
+    else {
+        const sessions = (0, lock_js_1.listSessions)();
+        if (sessions.length === 0) {
+            throw new errors_js_1.ConnectError('No running Aluvia sessions found. Start one with: npx aluvia-sdk session start <url>');
+        }
+        if (sessions.length > 1) {
+            const names = sessions.map((s) => s.session).join(', ');
+            throw new errors_js_1.ConnectError(`Multiple Aluvia sessions running (${names}). Specify which one: connect('${sessions[0].session}')`);
+        }
+        resolvedName = sessions[0].session;
+    }
+    // 3. Validate session state
+    const lock = (0, lock_js_1.readLock)(resolvedName);
+    if (!lock) {
+        throw new errors_js_1.ConnectError(`No Aluvia session found named '${resolvedName}'. Run 'npx aluvia-sdk session list' to list sessions.`);
+    }
+    if (!(0, lock_js_1.isProcessAlive)(lock.pid)) {
+        (0, lock_js_1.removeLock)(resolvedName);
+        throw new errors_js_1.ConnectError(`Session '${resolvedName}' is no longer running. Stale lock file removed.`);
+    }
+    if (!lock.ready) {
+        throw new errors_js_1.ConnectError(`Session '${resolvedName}' is still starting up. Try again shortly.`);
+    }
+    if (!lock.cdpUrl) {
+        throw new errors_js_1.ConnectError(`Session '${resolvedName}' has no CDP URL.`);
+    }
+    // 4. Connect over CDP
+    let browser;
+    try {
+        browser = await pw.chromium.connectOverCDP(lock.cdpUrl);
+    }
+    catch (err) {
+        throw new errors_js_1.ConnectError(`Failed to connect to session '${resolvedName}' at ${lock.cdpUrl}: ${err.message}`);
+    }
+    // 5. Get context and page
+    let context;
+    let page;
+    try {
+        context = browser.contexts()[0] ?? await browser.newContext();
+        page = context.pages()[0] ?? await context.newPage();
+    }
+    catch (err) {
+        await browser.close().catch(() => { });
+        throw new errors_js_1.ConnectError(`Connected but failed to get page: ${err.message}`);
+    }
+    return {
+        browser,
+        context,
+        page,
+        sessionName: resolvedName,
+        cdpUrl: lock.cdpUrl,
+        connectionId: lock.connectionId,
+        disconnect: async () => {
+            await browser.close();
+        },
+    };
+}

package/dist/cjs/errors.js

@@ -1,7 +1,7 @@
 "use strict";
 // Error classes for Aluvia Client
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProxyStartError = exports.ApiError = exports.InvalidApiKeyError = exports.MissingApiKeyError = void 0;
+exports.ConnectError = exports.ProxyStartError = exports.ApiError = exports.InvalidApiKeyError = exports.MissingApiKeyError = void 0;
 /**
  * Thrown when the apiKey is not provided to AluviaClient.
  */
@@ -47,3 +47,14 @@ class ProxyStartError extends Error {
     }
 }
 exports.ProxyStartError = ProxyStartError;
+/**
+ * Thrown by connect() when it cannot establish a CDP connection to a running session.
+ */
+class ConnectError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConnectError';
+        Object.setPrototypeOf(this, ConnectError.prototype);
+    }
+}
+exports.ConnectError = ConnectError;

package/dist/cjs/index.js

@@ -2,15 +2,19 @@
 // Aluvia Client Node
 // Main entry point
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProxyStartError = exports.ApiError = exports.InvalidApiKeyError = exports.MissingApiKeyError = exports.AluviaApi = exports.AluviaClient = void 0;
+exports.ConnectError = exports.ProxyStartError = exports.ApiError = exports.InvalidApiKeyError = exports.MissingApiKeyError = exports.connect = exports.AluviaApi = exports.AluviaClient = void 0;
 // Public class
 var AluviaClient_js_1 = require("./client/AluviaClient.js");
 Object.defineProperty(exports, "AluviaClient", { enumerable: true, get: function () { return AluviaClient_js_1.AluviaClient; } });
 var AluviaApi_js_1 = require("./api/AluviaApi.js");
 Object.defineProperty(exports, "AluviaApi", { enumerable: true, get: function () { return AluviaApi_js_1.AluviaApi; } });
+// Connect helper
+var connect_js_1 = require("./connect.js");
+Object.defineProperty(exports, "connect", { enumerable: true, get: function () { return connect_js_1.connect; } });
 // Public error classes
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "MissingApiKeyError", { enumerable: true, get: function () { return errors_js_1.MissingApiKeyError; } });
 Object.defineProperty(exports, "InvalidApiKeyError", { enumerable: true, get: function () { return errors_js_1.InvalidApiKeyError; } });
 Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return errors_js_1.ApiError; } });
 Object.defineProperty(exports, "ProxyStartError", { enumerable: true, get: function () { return errors_js_1.ProxyStartError; } });
+Object.defineProperty(exports, "ConnectError", { enumerable: true, get: function () { return errors_js_1.ConnectError; } });

package/dist/cjs/session/lock.js

@@ -0,0 +1,186 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeLock = writeLock;
+exports.readLock = readLock;
+exports.removeLock = removeLock;
+exports.isProcessAlive = isProcessAlive;
+exports.getLogFilePath = getLogFilePath;
+exports.validateSessionName = validateSessionName;
+exports.generateSessionName = generateSessionName;
+exports.toLockData = toLockData;
+exports.listSessions = listSessions;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+const LOCK_DIR = path.join(os.tmpdir(), 'aluvia-sdk');
+const ADJECTIVES = [
+    'swift', 'bold', 'calm', 'keen', 'warm', 'bright', 'silent', 'rapid', 'steady', 'clever',
+    'vivid', 'agile', 'noble', 'lucid', 'crisp', 'gentle', 'fierce', 'nimble', 'sturdy', 'witty',
+];
+const NOUNS = [
+    'falcon', 'tiger', 'river', 'maple', 'coral', 'cedar', 'orbit', 'prism', 'flint', 'spark',
+    'ridge', 'ember', 'crane', 'grove', 'stone', 'brook', 'drift', 'crest', 'sage', 'lynx',
+];
+function lockFileName(sessionName) {
+    return `cli-${sessionName ?? 'default'}.lock`;
+}
+function logFileName(sessionName) {
+    return `cli-${sessionName ?? 'default'}.log`;
+}
+function writeLock(data, sessionName) {
+    fs.mkdirSync(LOCK_DIR, { recursive: true });
+    const filePath = path.join(LOCK_DIR, lockFileName(sessionName));
+    const tmpPath = filePath + '.tmp';
+    try {
+        fs.writeFileSync(tmpPath, JSON.stringify(data), 'utf-8');
+        try {
+            // On Windows, rename may fail to overwrite an existing file; remove it first.
+            fs.rmSync(filePath, { force: true });
+        }
+        catch {
+            // Ignore errors removing the existing lock file.
+        }
+        fs.renameSync(tmpPath, filePath);
+    }
+    finally {
+        try {
+            // Ensure no leftover temp file remains if rename fails.
+            fs.rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // Ignore cleanup errors.
+        }
+    }
+}
+function readLock(sessionName) {
+    try {
+        const filePath = path.join(LOCK_DIR, lockFileName(sessionName));
+        const raw = fs.readFileSync(filePath, 'utf-8').trim();
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.pid === 'number' && Number.isFinite(parsed.pid)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function removeLock(sessionName) {
+    try {
+        const filePath = path.join(LOCK_DIR, lockFileName(sessionName));
+        fs.unlinkSync(filePath);
+    }
+    catch {
+        // ignore
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0); // signal 0 = check existence
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function getLogFilePath(sessionName) {
+    fs.mkdirSync(LOCK_DIR, { recursive: true });
+    return path.join(LOCK_DIR, logFileName(sessionName));
+}
+function validateSessionName(name) {
+    return /^[a-zA-Z0-9_-]+$/.test(name);
+}
+function generateSessionName() {
+    const maxAttempts = 10;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const adj = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
+        const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)];
+        const name = attempt === 0 ? `${adj}-${noun}` : `${adj}-${noun}-${attempt}`;
+        const filePath = path.join(LOCK_DIR, lockFileName(name));
+        if (!fs.existsSync(filePath)) {
+            return name;
+        }
+        // Lock file exists — check if the process is still alive
+        const lock = readLock(name);
+        if (!lock || !isProcessAlive(lock.pid)) {
+            // Stale lock, we can reuse this name
+            removeLock(name);
+            return name;
+        }
+    }
+    // Fallback: use timestamp
+    return `session-${Date.now()}`;
+}
+function toLockData(info) {
+    const { session: _session, ...lock } = info;
+    return lock;
+}
+function listSessions() {
+    fs.mkdirSync(LOCK_DIR, { recursive: true });
+    const files = fs.readdirSync(LOCK_DIR);
+    const sessions = [];
+    for (const file of files) {
+        const match = file.match(/^cli-(.+)\.lock$/);
+        if (!match)
+            continue;
+        const sessionName = match[1];
+        const lock = readLock(sessionName);
+        if (!lock) {
+            // Corrupt lock file, clean up
+            removeLock(sessionName);
+            continue;
+        }
+        if (!isProcessAlive(lock.pid)) {
+            // Stale lock, clean up
+            removeLock(sessionName);
+            continue;
+        }
+        sessions.push({
+            session: sessionName,
+            pid: lock.pid,
+            connectionId: lock.connectionId,
+            cdpUrl: lock.cdpUrl,
+            proxyUrl: lock.proxyUrl,
+            url: lock.url,
+            ready: lock.ready,
+            blockDetection: lock.blockDetection,
+            autoUnblock: lock.autoUnblock,
+            lastDetection: lock.lastDetection,
+        });
+    }
+    return sessions;
+}