wavexis 2.2.4__tar.gz → 2.2.6__tar.gz

{wavexis-2.2.4 → wavexis-2.2.6}/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to wavexis are documented in this file.
 
+## v2.2.6 — 2026-07-07
+
+### Added
+
+- Named sessions: `--name` flag stores sessions in `~/.wavexis/sessions/`
+- `wavexis session list` — list all saved named sessions with size and modification date
+- `wavexis session delete --name <name>` — delete a named session
+- Named sessions persist between runs, enabling stateful workflows
+
+## v2.2.5 — 2026-07-07
+
+### Improved
+
+- Error messages now include actionable hints for common failures
+- `ElementNotFoundError` suggests `wavexis dom` and `wavexis screenshot` for debugging
+- `WaitTimeoutError` suggests increasing `--timeout` and alternative wait strategies
+- `NavigationError` suggests checking URL, `--timeout`, and `--proxy`
+- `SessionNotInitializedError` suggests `--headed` and checking Chromium installation
+- `BackendNotAvailableError` shows install commands for both backends
+- `MultiConfigError` suggests `--dry-run` to validate config
+
 ## v2.2.4 — 2026-07-07
 
 ### Added

{wavexis-2.2.4 → wavexis-2.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavexis
-Version: 2.2.4
+Version: 2.2.6
 Summary: Browser automation CLI — wraps cdpwave and bidiwave, no Node.js, no Chromium download
 Project-URL: Homepage, https://github.com/MathiasPaulenko/wavexis
 Project-URL: Repository, https://github.com/MathiasPaulenko/wavexis

{wavexis-2.2.4 → wavexis-2.2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wavexis"
-version = "2.2.4"
+version = "2.2.6"
 description = "Browser automation CLI — wraps cdpwave and bidiwave, no Node.js, no Chromium download"
 readme = "README.md"
 license = { text = "MIT" }

{wavexis-2.2.4 → wavexis-2.2.6}/wavexis/__init__.py

@@ -1,3 +1,3 @@
 """wavexis — CLI de automatización de navegador."""
 
-__version__ = "2.2.4"
+__version__ = "2.2.6"

{wavexis-2.2.4 → wavexis-2.2.6}/wavexis/cli/_session.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import time
 from pathlib import Path
 from typing import Any
 
@@ -21,7 +22,7 @@ from wavexis.config import WaitStrategy
 @app.command()
 def session(
     action: str = typer.Argument(
-        ..., help="Session action: save, load"
+        ..., help="Session action: save, load, list, delete"
     ),
     url: str = typer.Argument(
         "", help="URL to navigate to (for save) or load before navigating (for load)"
@@ -29,18 +30,60 @@ def session(
     output: str = typer.Option(
         "session.json", "--output", "-o", help="Session file path"
     ),
+    name: str = typer.Option(
+        "", "--name", "-n", help="Named session (stored in ~/.wavexis/sessions/)"
+    ),
 ) -> None:
     """Save or load browser session state (cookies + localStorage + sessionStorage).
 
     \b
     Save:  wavexis session save https://app.com -o mysession.json
     Load:  wavexis session load mysession.json https://app.com
+    Named: wavexis session save https://app.com --name mysession
+    List:  wavexis session list
+    Delete: wavexis session delete --name mysession
     """
     from wavexis.actions.session import SessionLoadAction, SessionSaveAction
 
-    session_path = Path(output)
+    sessions_dir = Path.home() / ".wavexis" / "sessions"
+
+    def _session_path() -> Path:
+        if name:
+            return sessions_dir / f"{name}.json"
+        return Path(output)
+
+    if action == "list":
+        if not sessions_dir.exists():
+            typer.echo("No saved sessions found.")
+            return
+        sessions = list(sessions_dir.glob("*.json"))
+        if not sessions:
+            typer.echo("No saved sessions found.")
+            return
+        typer.echo(f"Saved sessions ({len(sessions)}):")
+        for s in sorted(sessions):
+            stat = s.stat()
+            modified = time.strftime("%Y-%m-%d %H:%M", time.localtime(stat.st_mtime))
+            typer.echo(f"  {s.stem}  ({stat.st_size} bytes, {modified})")
+        return
+
+    if action == "delete":
+        if not name:
+            typer.echo("Error: --name required for delete", err=True)
+            raise typer.Exit(1)
+        target = _session_path()
+        if not target.exists():
+            typer.echo(f"Error: session '{name}' not found", err=True)
+            raise typer.Exit(1)
+        target.unlink()
+        typer.echo(f"Deleted session '{name}'")
+        return
+
+    session_path = _session_path()
 
     if action == "save":
+        if name:
+            sessions_dir.mkdir(parents=True, exist_ok=True)
         if not url:
             typer.echo("Error: URL required for session save", err=True)
             raise typer.Exit(1)
@@ -56,11 +99,11 @@ def session(
                 await backend.close()
 
         _run_async(_save_session())
-        typer.echo(f"Session saved to {output}")
+        typer.echo(f"Session saved to {session_path}")
 
     elif action == "load":
         if not session_path.exists():
-            typer.echo(f"Error: session file not found: {output}", err=True)
+            typer.echo(f"Error: session file not found: {session_path}", err=True)
             raise typer.Exit(1)
 
         async def _load_session() -> Any:
@@ -80,10 +123,13 @@ def session(
         result = _run_async(_load_session())
         if result is None:
             return
-        typer.echo(f"Session loaded from {output}: {result}")
+        typer.echo(f"Session loaded from {session_path}: {result}")
 
     else:
-        typer.echo(f"Error: unknown session action '{action}'. Use save or load.", err=True)
+        typer.echo(
+            f"Error: unknown session action '{action}'. Use save, load, list, or delete.",
+            err=True,
+        )
         raise typer.Exit(1)
 
 

{wavexis-2.2.4 → wavexis-2.2.6}/wavexis/cli/_shared.py

@@ -21,6 +21,7 @@ from wavexis.exceptions import (
     ElementNotFoundError,
     MultiConfigError,
     NavigationError,
+    SessionNotInitializedError,
     WaitTimeoutError,
     WavexisError,
 )
@@ -39,6 +40,7 @@ __all__ = [
     "MultiConfigError",
     "NavigationError",
     "Output",
+    "SessionNotInitializedError",
     "WaitTimeoutError",
     "WavexisError",
     "_browser_options",
@@ -209,20 +211,28 @@ def _handle_error(e: Exception) -> None:
     """
     if isinstance(e, BackendNotAvailableError):
         Output.error(
-            "No backend available. Install cdpwave: pip install wavexis[cdp]"
+            "No backend available.\n"
+            "Hint: Install cdpwave with `pip install wavexis[cdp]`, "
+            "or bidiwave with `pip install wavexis[bidi]`."
         )
         raise typer.Exit(EXIT_BACKEND_ERROR) from e
+    if isinstance(e, SessionNotInitializedError):
+        Output.error(str(e))
+        raise typer.Exit(EXIT_BROWSER_ERROR) from e
     if isinstance(e, NavigationError):
-        Output.error(f"Navigation failed: {e}")
+        Output.error(str(e))
         raise typer.Exit(EXIT_BROWSER_ERROR) from e
     if isinstance(e, WaitTimeoutError):
-        Output.error(f"Timeout waiting: {e}")
+        Output.error(str(e))
         raise typer.Exit(EXIT_BROWSER_ERROR) from e
     if isinstance(e, ElementNotFoundError):
-        Output.error(f"Element not found: {e}")
+        Output.error(str(e))
         raise typer.Exit(EXIT_BROWSER_ERROR) from e
     if isinstance(e, MultiConfigError):
-        Output.error(f"Invalid multi config: {e}")
+        Output.error(
+            f"Invalid multi config: {e}\n"
+            "Hint: Run `wavexis multi <config> --dry-run` to validate the config."
+        )
         raise typer.Exit(EXIT_CONFIG_ERROR) from e
     if isinstance(e, WavexisError):
         Output.error(str(e))

{wavexis-2.2.4 → wavexis-2.2.6}/wavexis/exceptions.py

@@ -41,6 +41,21 @@ class BackendNotSupportedError(WavexisError):
 class SessionNotInitializedError(WavexisError):
     """Raised when a backend method is called before launch()."""
 
+    def __init__(self, msg: str | None = None) -> None:
+        """Initialize the error.
+
+        Args:
+            msg: Optional custom message.
+        """
+        if msg:
+            super().__init__(msg)
+        else:
+            super().__init__(
+                "Browser session not initialized. Call launch() first.\n"
+                "Hint: This usually means the browser failed to start. "
+                "Try --headed to see the browser window, or check if Chromium is installed."
+            )
+
 
 class NavigationError(WavexisError):
     """Raised when navigation fails or times out."""
@@ -52,7 +67,11 @@ class NavigationError(WavexisError):
             url: The URL that failed to navigate to.
             reason: The failure reason.
         """
-        super().__init__(f"Navigation to '{url}' failed: {reason}")
+        super().__init__(
+            f"Navigation to '{url}' failed: {reason}\n"
+            f"Hint: Check the URL is reachable, try --timeout 60000, "
+            f"or use --proxy if behind a firewall."
+        )
 
 
 class WaitTimeoutError(WavexisError):
@@ -66,7 +85,9 @@ class WaitTimeoutError(WavexisError):
             timeout_ms: The timeout duration in milliseconds.
         """
         super().__init__(
-            f"Wait strategy '{strategy}' timed out after {timeout_ms}ms"
+            f"Wait strategy '{strategy}' timed out after {timeout_ms}ms\n"
+            f"Hint: Increase timeout with --timeout {max(timeout_ms * 2, 60000)}, "
+            f"or use a different wait strategy (load, domcontentloaded, networkidle)."
         )
 
 
@@ -79,7 +100,11 @@ class ElementNotFoundError(WavexisError):
         Args:
             selector: The CSS selector that matched no elements.
         """
-        super().__init__(f"No element found matching selector: {selector}")
+        super().__init__(
+            f"No element found matching selector: {selector}\n"
+            f"Hint: Verify the selector with `wavexis dom --selector '{selector}'`, "
+            f"or use `wavexis screenshot` to inspect the page visually."
+        )
 
 
 class ActionError(WavexisError):