navcli 0.1.0__py3-none-any.whl

navcli/server/routes/navigation.py

@@ -0,0 +1,133 @@
+"""Navigation routes: goto, back, forward, reload."""
+
+from typing import Optional
+from fastapi import APIRouter, HTTPException, Query
+
+from navcli.core.models import CommandResult, Feedback
+from navcli.server.browser import get_page, get_current_state, start_browser, wait_for_network_idle
+from navcli.utils import normalize_url
+
+router = APIRouter()
+
+
+@router.post("/goto")
+async def goto(
+    url: str = Query(..., description="URL to navigate to"),
+    wait_until: str = Query("networkidle", description="wait condition: load, domcontentloaded, networkidle")
+) -> CommandResult:
+    """Navigate to a URL."""
+    try:
+        if not url:
+            raise HTTPException(status_code=400, detail="url is required")
+
+        normalized_url = normalize_url(url)
+
+        # Start browser if not started
+        await start_browser()
+        page = get_page()
+
+        # Navigate
+        await page.goto(normalized_url, wait_until=wait_until)
+
+        # Wait for network idle
+        await wait_for_network_idle(3.0)
+
+        # Get new state
+        state = await get_current_state()
+
+        return CommandResult(
+            success=True,
+            command="goto",
+            state=state,
+            feedback=Feedback(
+                action=f"navigated to {normalized_url}",
+                result="page loaded",
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="goto",
+            error=str(e),
+        )
+
+
+@router.post("/back")
+async def back() -> CommandResult:
+    """Go back in history."""
+    try:
+        page = get_page()
+        await page.go_back()
+        await wait_for_network_idle(3.0)
+
+        state = await get_current_state()
+
+        return CommandResult(
+            success=True,
+            command="back",
+            state=state,
+            feedback=Feedback(
+                action="went back",
+                result=f"navigated to {state.url}",
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="back",
+            error=str(e),
+        )
+
+
+@router.post("/forward")
+async def forward() -> CommandResult:
+    """Go forward in history."""
+    try:
+        page = get_page()
+        await page.go_forward()
+        await wait_for_network_idle(3.0)
+
+        state = await get_current_state()
+
+        return CommandResult(
+            success=True,
+            command="forward",
+            state=state,
+            feedback=Feedback(
+                action="went forward",
+                result=f"navigated to {state.url}",
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="forward",
+            error=str(e),
+        )
+
+
+@router.post("/reload")
+async def reload() -> CommandResult:
+    """Reload the current page."""
+    try:
+        page = get_page()
+        await page.reload()
+        await wait_for_network_idle(3.0)
+
+        state = await get_current_state()
+
+        return CommandResult(
+            success=True,
+            command="reload",
+            state=state,
+            feedback=Feedback(
+                action="reloaded page",
+                result=f"reloaded {state.url}",
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="reload",
+            error=str(e),
+        )

navcli/server/routes/query.py

@@ -0,0 +1,303 @@
+"""Query routes: elements, text, html, screenshot, state."""
+
+from typing import Optional, List
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from navcli.core.models import CommandResult, Feedback
+from navcli.server.browser import get_page, get_current_state, start_browser
+from navcli.utils import encode_screenshot
+
+router = APIRouter()
+
+
+@router.get("/elements")
+async def get_elements() -> CommandResult:
+    """Get interactive elements on the page."""
+    try:
+        await start_browser()
+        state = await get_current_state()
+
+        return CommandResult(
+            success=True,
+            command="elements",
+            state=state,
+            feedback=Feedback(
+                action="got elements",
+                result=f"found {len(state.dom.elements)} interactive elements",
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="elements",
+            error=str(e),
+        )
+
+
+@router.get("/text")
+async def get_text() -> CommandResult:
+    """Get page text content."""
+    try:
+        page = get_page()
+        text = await page.inner_text("body")
+
+        await start_browser()
+        state = await get_current_state()
+
+        return CommandResult(
+            success=True,
+            command="text",
+            state=state,
+            feedback=Feedback(
+                action="got text",
+                result=f"text length: {len(text)} chars",
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="text",
+            error=str(e),
+        )
+
+
+class TextRequest(BaseModel):
+    selectors: Optional[List[str]] = None
+
+
+@router.get("/html")
+async def get_html() -> CommandResult:
+    """Get page HTML content."""
+    try:
+        page = get_page()
+        html = await page.content()
+
+        await start_browser()
+        state = await get_current_state()
+
+        return CommandResult(
+            success=True,
+            command="html",
+            state=state,
+            feedback=Feedback(
+                action="got html",
+                result=f"html length: {len(html)} chars",
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="html",
+            error=str(e),
+        )
+
+
+@router.get("/screenshot")
+async def get_screenshot() -> CommandResult:
+    """Get page screenshot as base64."""
+    try:
+        page = get_page()
+        screenshot_bytes = await page.screenshot()
+        screenshot_base64 = encode_screenshot(screenshot_bytes)
+
+        await start_browser()
+        state = await get_current_state()
+
+        return CommandResult(
+            success=True,
+            command="screenshot",
+            state=state,
+            feedback=Feedback(
+                action="took screenshot",
+                result=f"screenshot size: {len(screenshot_bytes)} bytes",
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="screenshot",
+            error=str(e),
+        )
+
+
+@router.get("/state")
+async def get_state() -> CommandResult:
+    """Get full page state."""
+    try:
+        await start_browser()
+        state = await get_current_state()
+
+        return CommandResult(
+            success=True,
+            command="state",
+            state=state,
+            feedback=Feedback(
+                action="got state",
+                result=f"url: {state.url}, title: {state.title}",
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="state",
+            error=str(e),
+        )
+
+
+@router.get("/url")
+async def get_url() -> CommandResult:
+    """Get current URL."""
+    try:
+        page = get_page()
+        url = page.url
+
+        await start_browser()
+        state = await get_current_state()
+
+        return CommandResult(
+            success=True,
+            command="url",
+            state=state,
+            feedback=Feedback(
+                action="got url",
+                result=url,
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="url",
+            error=str(e),
+        )
+
+
+@router.get("/title")
+async def get_title() -> CommandResult:
+    """Get page title."""
+    try:
+        page = get_page()
+        title = await page.title()
+
+        await start_browser()
+        state = await get_current_state()
+
+        return CommandResult(
+            success=True,
+            command="title",
+            state=state,
+            feedback=Feedback(
+                action="got title",
+                result=title,
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="title",
+            error=str(e),
+        )
+
+
+@router.get("/evaluate")
+async def evaluate(expr: str) -> CommandResult:
+    """Evaluate JavaScript expression.
+
+    Usage: /query/evaluate?expr=<js_expression>
+    """
+    try:
+        await start_browser()
+        page = get_page()
+
+        result = await page.evaluate(expr)
+
+        state = await get_current_state()
+
+        return CommandResult(
+            success=True,
+            command="evaluate",
+            state=state,
+            feedback=Feedback(
+                action=f"evaluated: {expr[:50]}...",
+                result=str(result)[:100],
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="evaluate",
+            error=str(e),
+        )
+
+
+@router.get("/links")
+async def get_links() -> CommandResult:
+    """Get all links on the page."""
+    try:
+        await start_browser()
+        page = get_page()
+
+        links = await page.evaluate("""
+            Array.from(document.querySelectorAll('a[href]')).map(a => ({
+                href: a.href,
+                text: a.innerText.trim().substring(0, 100),
+                visible: a.offsetParent !== null
+            }))
+        """)
+
+        state = await get_current_state()
+
+        return CommandResult(
+            success=True,
+            command="links",
+            state=state,
+            feedback=Feedback(
+                action="got links",
+                result=f"found {len(links)} links",
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="links",
+            error=str(e),
+        )
+
+
+@router.get("/forms")
+async def get_forms() -> CommandResult:
+    """Get all forms on the page."""
+    try:
+        await start_browser()
+        page = get_page()
+
+        forms = await page.evaluate("""
+            Array.from(document.querySelectorAll('form')).map(form => ({
+                action: form.action,
+                method: form.method,
+                inputs: Array.from(form.querySelectorAll('input, select, textarea')).map(i => ({
+                    name: i.name,
+                    type: i.type,
+                    id: i.id,
+                    placeholder: i.placeholder || ''
+                }))
+            }))
+        """)
+
+        state = await get_current_state()
+
+        return CommandResult(
+            success=True,
+            command="forms",
+            state=state,
+            feedback=Feedback(
+                action="got forms",
+                result=f"found {len(forms)} forms",
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="forms",
+            error=str(e),
+        )

navcli/server/routes/session.py

@@ -0,0 +1,177 @@
+"""Session routes: cookies, save_session, load_session."""
+
+from typing import Optional, List, Dict, Any
+from fastapi import APIRouter, HTTPException, Query
+from pydantic import BaseModel
+
+from navcli.core.models import CommandResult, Feedback
+from navcli.server.browser import (
+    get_cookies,
+    set_cookie,
+    clear_cookies,
+    save_session,
+    load_session,
+)
+
+router = APIRouter()
+
+
+class CookieSetRequest(BaseModel):
+    """Request body for setting a cookie."""
+    name: str
+    value: str
+    domain: str
+    path: str = "/"
+    expires: Optional[int] = None
+    http_only: bool = False
+    secure: bool = False
+    same_site: Optional[str] = None
+
+
+@router.get("/cookies")
+async def query_cookies() -> CommandResult:
+    """Get all current cookies.
+
+    Returns list of cookies with name, value, domain, path, etc.
+    """
+    try:
+        cookies = await get_cookies()
+
+        return CommandResult(
+            success=True,
+            command="cookies",
+            feedback=Feedback(
+                action="got cookies",
+                result=f"found {len(cookies)} cookies",
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="cookies",
+            error=str(e),
+        )
+
+
+@router.post("/cookies/set")
+async def set_cookie_route(request: CookieSetRequest) -> CommandResult:
+    """Set a single cookie.
+
+    Usage: POST /cmd/cookies/set with JSON body
+    """
+    try:
+        await set_cookie(
+            name=request.name,
+            value=request.value,
+            domain=request.domain,
+            path=request.path,
+            expires=request.expires,
+            http_only=request.http_only,
+            secure=request.secure,
+            same_site=request.same_site,
+        )
+
+        return CommandResult(
+            success=True,
+            command="set_cookie",
+            feedback=Feedback(
+                action="set cookie",
+                result=f"cookie '{request.name}' set for {request.domain}",
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="set_cookie",
+            error=str(e),
+        )
+
+
+@router.delete("/cookies/clear")
+async def clear_cookies_route() -> CommandResult:
+    """Clear all cookies.
+
+    Returns the number of cookies that were cleared.
+    """
+    try:
+        count = await clear_cookies()
+
+        return CommandResult(
+            success=True,
+            command="clear_cookies",
+            feedback=Feedback(
+                action="cleared cookies",
+                result=f"cleared {count} cookies",
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="clear_cookies",
+            error=str(e),
+        )
+
+
+@router.post("/session/save")
+async def save_session_route(path: str = Query(".navcli_session.json")) -> CommandResult:
+    """Save session to file.
+
+    Saves cookies, localStorage, and sessionStorage to a JSON file.
+
+    Args:
+        path: File path to save session (default: .navcli_session.json)
+    """
+    try:
+        storage_state = await save_session(path)
+
+        cookie_count = len(storage_state.get("cookies", []))
+        origin_count = len(storage_state.get("origins", []))
+
+        return CommandResult(
+            success=True,
+            command="save_session",
+            feedback=Feedback(
+                action="saved session",
+                result=f"saved to {path}: {cookie_count} cookies, {origin_count} origins",
+            ),
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="save_session",
+            error=str(e),
+        )
+
+
+@router.post("/session/load")
+async def load_session_route(path: str = Query(".navcli_session.json")) -> CommandResult:
+    """Load session from file.
+
+    Loads cookies, localStorage, and sessionStorage from a JSON file.
+
+    Args:
+        path: File path to load session from (default: .navcli_session.json)
+    """
+    try:
+        await load_session(path)
+
+        return CommandResult(
+            success=True,
+            command="load_session",
+            feedback=Feedback(
+                action="loaded session",
+                result=f"loaded session from {path}",
+            ),
+        )
+    except FileNotFoundError:
+        return CommandResult(
+            success=False,
+            command="load_session",
+            error=f"Session file not found: {path}",
+        )
+    except Exception as e:
+        return CommandResult(
+            success=False,
+            command="load_session",
+            error=str(e),
+        )

navcli/utils/__init__.py

@@ -0,0 +1,20 @@
+"""Common utilities for NavCLI."""
+
+from .selector import build_selector, parse_selector
+from .image import decode_screenshot, encode_screenshot
+from .url import normalize_url
+from .js import escape_js_string
+from .time import format_timeout, wait_for_condition
+from .text import parse_key_value
+
+__all__ = [
+    'parse_selector',
+    'build_selector',
+    'decode_screenshot',
+    'encode_screenshot',
+    'normalize_url',
+    'escape_js_string',
+    'format_timeout',
+    'wait_for_condition',
+    'parse_key_value',
+]

navcli/utils/image.py

@@ -0,0 +1,30 @@
+"""Image encoding/decoding utilities."""
+
+import base64
+
+
+def decode_screenshot(base64_data: str) -> bytes:
+    """Decode base64 screenshot data.
+
+    Args:
+        base64_data: Base64 encoded image data
+
+    Returns:
+        Raw image bytes
+    """
+    if ',' in base64_data:
+        base64_data = base64_data.split(',', 1)[1]
+    return base64.b64decode(base64_data)
+
+
+def encode_screenshot(image_bytes: bytes) -> str:
+    """Encode image bytes to base64 with prefix.
+
+    Args:
+        image_bytes: Raw image bytes
+
+    Returns:
+        Base64 string with data URL prefix
+    """
+    b64 = base64.b64encode(image_bytes).decode('utf-8')
+    return f"data:image/png;base64,{b64}"

navcli/utils/js.py

@@ -0,0 +1,13 @@
+"""JavaScript related utilities."""
+
+
+def escape_js_string(s: str) -> str:
+    """Escape a string for use in JavaScript.
+
+    Args:
+        s: String to escape
+
+    Returns:
+        Escaped string safe for JS
+    """
+    return s.replace('\\', '\\\\').replace('"', '\\"').replace("'", "\\'").replace('\n', '\\n').replace('\r', '\\r')