navcli 0.1.0__py3-none-any.whl

navcli/cli/commands/interaction.py

@@ -0,0 +1,129 @@
+"""Interaction commands: click, type, clear, upload."""
+
+import cmd2
+from navcli.cli.commands.base import BaseBrowserCommand
+
+
+# Parsers for aliased commands
+_click_parser = cmd2.Cmd2ArgumentParser()
+_click_parser.add_argument("selector", help="CSS selector")
+_click_parser.add_argument("--force", action="store_true", help="Force click without waiting")
+
+_type_parser = cmd2.Cmd2ArgumentParser()
+_type_parser.add_argument("selector", help="CSS selector")
+_type_parser.add_argument("text", help="Text to type")
+
+
+class InteractionCommands(BaseBrowserCommand):
+    """Interaction command set."""
+
+    def __init__(self, client):
+        super().__init__(client)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_click(self, args):
+        """Click an element.
+
+        Usage: click <selector> [--force]
+        Example: click #submit-button
+        Example: click .login-btn --force
+        """
+        import asyncio
+
+        async def _click():
+            return await self.client.click(args.selector, force=args.force)
+
+        result = asyncio.run(self.run_async_client(_click))
+        self.pretty_result(result)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_type(self, args):
+        """Type text into an input field.
+
+        Usage: type <selector> <text>
+        Example: type #search-input hello world
+        """
+        import asyncio
+
+        async def _type():
+            return await self.client.type(args.selector, args.text)
+
+        result = asyncio.run(self.run_async_client(_type))
+        self.pretty_result(result)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_dblclick(self, args):
+        """Double-click an element.
+
+        Usage: dblclick <selector>
+        Example: dblclick #submit-button
+        """
+        import asyncio
+
+        async def _dblclick():
+            return await self.client.dblclick(args.selector)
+
+        result = asyncio.run(self.run_async_client(_dblclick))
+        self.pretty_result(result)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_rightclick(self, args):
+        """Right-click an element.
+
+        Usage: rightclick <selector>
+        Example: rightclick .context-menu
+        """
+        import asyncio
+
+        async def _rightclick():
+            return await self.client.rightclick(args.selector)
+
+        result = asyncio.run(self.run_async_client(_rightclick))
+        self.pretty_result(result)
+
+    # Aliases
+    @cmd2.with_argparser(_click_parser)
+    def do_c(self, args):
+        """Click an element (shortcut).
+
+        Usage: c <selector> [--force]
+        """
+        return self.do_click(args)
+
+    @cmd2.with_argparser(_type_parser)
+    def do_t(self, args):
+        """Type text into an input (shortcut).
+
+        Usage: t <selector> <text>
+        """
+        return self.do_type(args)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_clear(self, args):
+        """Clear an input field.
+
+        Usage: clear <selector>
+        Example: clear #search-input
+        """
+        import asyncio
+
+        async def _clear():
+            return await self.client.clear(args.selector)
+
+        result = asyncio.run(self.run_async_client(_clear))
+        self.pretty_result(result)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_upload(self, args):
+        """Upload a file to an input.
+
+        Usage: upload <selector> <file_path>
+        Example: upload input[type=file] /path/to/file.txt
+        """
+        import asyncio
+
+        async def _upload():
+            return await self.client.upload(args.selector, args.file_path)
+
+        result = asyncio.run(self.run_async_client(_upload))
+        self.pretty_result(result)

navcli/cli/commands/navigation.py

@@ -0,0 +1,90 @@
+"""Navigation commands: goto, back, forward, reload."""
+
+import cmd2
+from navcli.cli.commands.base import BaseBrowserCommand
+
+
+# Alias parser for goto -> g
+_goto_parser = cmd2.Cmd2ArgumentParser()
+_goto_parser.add_argument("url", help="URL to navigate to")
+
+
+class NavigationCommands(BaseBrowserCommand):
+    """Navigation command set."""
+
+    def __init__(self, client):
+        super().__init__(client)
+
+    @cmd2.with_argparser(_goto_parser)
+    def do_goto(self, args):
+        """Navigate to a URL.
+
+        Usage: goto <url>
+        Example: goto https://example.com
+        """
+        import asyncio
+        url = args.url
+        if not url.startswith(("http://", "https://")):
+            url = "https://" + url
+
+        async def _goto():
+            return await self.client.goto(url)
+
+        result = asyncio.run(self.run_async_client(_goto))
+        self.pretty_result(result)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_back(self, _):
+        """Go back in history.
+
+        Usage: back
+        """
+        import asyncio
+
+        async def _back():
+            return await self.client.back()
+
+        result = asyncio.run(self.run_async_client(_back))
+        self.pretty_result(result)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_forward(self, _):
+        """Go forward in history.
+
+        Usage: forward
+        """
+        import asyncio
+
+        async def _forward():
+            return await self.client.forward()
+
+        result = asyncio.run(self.run_async_client(_forward))
+        self.pretty_result(result)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_reload(self, _):
+        """Reload the current page.
+
+        Usage: reload
+        """
+        import asyncio
+
+        async def _reload():
+            return await self.client.reload()
+
+        result = asyncio.run(self.run_async_client(_reload))
+        self.pretty_result(result)
+
+    # Aliases
+    do_b = do_back  # back -> b
+    do_f = do_forward  # forward -> f
+    do_r = do_reload  # reload -> r
+
+    # goto -> g (requires separate parser)
+    @cmd2.with_argparser(_goto_parser)
+    def do_g(self, args):
+        """Navigate to a URL (shortcut).
+
+        Usage: g <url>
+        """
+        return self.do_goto(args)

navcli/cli/commands/query.py

@@ -0,0 +1,171 @@
+"""Query commands: elements, text, html, screenshot, state, url, title."""
+
+import cmd2
+import base64
+from navcli.cli.commands.base import BaseBrowserCommand
+
+
+# Parser for evaluate command
+_evaluate_parser = cmd2.Cmd2ArgumentParser()
+_evaluate_parser.add_argument("expression", help="JavaScript expression")
+
+
+class QueryCommands(BaseBrowserCommand):
+    """Query command set."""
+
+    def __init__(self, client):
+        super().__init__(client)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_elements(self, _):
+        """Get interactive elements on the page.
+
+        Usage: elements
+        """
+        import asyncio
+
+        async def _elements():
+            return await self.client.get_elements()
+
+        result = asyncio.run(self.run_async_client(_elements))
+        self.pretty_result(result)
+        if result.get("success"):
+            state = result.get("state", {})
+            elements = state.get("dom", {}).get("elements", [])
+            for elem in elements[:20]:
+                self.poutput(f"  {elem.get('selector')} [{elem.get('tag')}] {elem.get('text', '')[:50]}")
+            if len(elements) > 20:
+                self.poutput(f"  ... and {len(elements) - 20} more")
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_text(self, _):
+        """Get page text content.
+
+        Usage: text
+        """
+        import asyncio
+
+        async def _text():
+            return await self.client.get_text()
+
+        result = asyncio.run(self.run_async_client(_text))
+        self.pretty_result(result)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_html(self, _):
+        """Get page HTML content.
+
+        Usage: html
+        """
+        import asyncio
+
+        async def _html():
+            return await self.client.get_html()
+
+        result = asyncio.run(self.run_async_client(_html))
+        self.pretty_result(result)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_screenshot(self, _):
+        """Take a screenshot of the page.
+
+        Usage: screenshot [output_file]
+        Example: screenshot
+        Example: screenshot page.png
+        """
+        import asyncio
+        import os
+
+        async def _screenshot():
+            return await self.client.get_screenshot()
+
+        result = asyncio.run(self.run_async_client(_screenshot))
+        self.pretty_result(result)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_state(self, _):
+        """Get full page state.
+
+        Usage: state
+        """
+        import asyncio
+
+        async def _state():
+            return await self.client.get_state()
+
+        result = asyncio.run(self.run_async_client(_state))
+        self.pretty_result(result)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_url(self, _):
+        """Get current URL.
+
+        Usage: url
+        """
+        import asyncio
+
+        async def _url():
+            return await self.client.get_url()
+
+        result = asyncio.run(self.run_async_client(_url))
+        self.pretty_result(result)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_title(self, _):
+        """Get page title.
+
+        Usage: title
+        """
+        import asyncio
+
+        async def _title():
+            return await self.client.get_title()
+
+        result = asyncio.run(self.run_async_client(_title))
+        self.pretty_result(result)
+
+    @cmd2.with_argparser(_evaluate_parser)
+    def do_evaluate(self, args):
+        """Evaluate JavaScript expression.
+
+        Usage: evaluate <js_expression>
+        Example: evaluate document.title
+        Example: evaluate window.innerHeight
+        """
+        import asyncio
+
+        async def _evaluate():
+            return await self.client.evaluate(args.expression)
+
+        result = asyncio.run(self.run_async_client(_evaluate))
+        self.pretty_result(result)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_links(self, _):
+        """Get all links on the page.
+
+        Usage: links
+        """
+        import asyncio
+
+        async def _links():
+            return await self.client.get_links()
+
+        result = asyncio.run(self.run_async_client(_links))
+        self.pretty_result(result)
+        if result.get("success"):
+            state = result.get("state", {})
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_forms(self, _):
+        """Get all forms on the page.
+
+        Usage: forms
+        """
+        import asyncio
+
+        async def _forms():
+            return await self.client.get_forms()
+
+        result = asyncio.run(self.run_async_client(_forms))
+        self.pretty_result(result)

navcli/core/models/__init__.py

@@ -0,0 +1,15 @@
+"""Core models for NavCLI."""
+
+from .element import Element
+from .dom import DOMTree, DOMChange
+from .state import StateSnapshot
+from .feedback import CommandResult, Feedback
+
+__all__ = [
+    'Element',
+    'DOMTree',
+    'DOMChange',
+    'StateSnapshot',
+    'CommandResult',
+    'Feedback',
+]

navcli/core/models/dom.py

@@ -0,0 +1,33 @@
+"""DOM Tree model for page DOM representation."""
+
+from typing import Optional
+from pydantic import BaseModel, Field
+
+from .element import Element
+
+
+class DOMChange(BaseModel):
+    """Represents a SPA DOM change."""
+
+    type: str              # 'added', 'removed', 'modified'
+    selector: str          # CSS selector of changed element
+    html: Optional[str] = None  # new HTML (for added/modified)
+    text: Optional[str] = None  # new text (for modified)
+
+
+class DOMTree(BaseModel):
+    """Represents the page DOM tree.
+
+    SPA Diff Strategy:
+    - First load returns full DOM
+    - Subsequent operations return incremental changes
+    - Fallback to full DOM if changes > 50%
+    """
+
+    version: int = 0              # incremental version number
+    full: bool = True              # is full DOM (vs incremental)
+    html: str = ""                 # full or incremental HTML
+    changes: list[DOMChange] = Field(default_factory=list)  # SPA changes
+    elements: list[Element] = Field(default_factory=list)  # interactive elements
+    async_loaded: bool = False     # contains async loaded content
+    loading: bool = False          # currently loading

navcli/core/models/element.py

@@ -0,0 +1,22 @@
+"""Element model for interactive elements."""
+
+from typing import Optional
+from pydantic import BaseModel
+
+
+class Element(BaseModel):
+    """Represents an interactive element on the page.
+
+    Only returns "actionable + meaningful" elements:
+    - button, a (with href), input, select, textarea
+    - h1-h3, img (with alt), nav, menu
+    """
+
+    selector: str          # CSS selector
+    tag: str               # tag name
+    text: str              # element text content
+    clickable: bool        # is clickable
+    input: bool            # is inputtable
+    type: Optional[str] = None  # input type (for input elements)
+    href: Optional[str] = None  # href (for anchor elements)
+    alt: Optional[str] = None   # alt text (for img elements)

navcli/core/models/feedback.py

@@ -0,0 +1,24 @@
+"""Feedback and CommandResult models."""
+
+from typing import Optional
+from pydantic import BaseModel, Field
+
+from .state import StateSnapshot
+
+
+class Feedback(BaseModel):
+    """Represents the result of a command execution."""
+
+    action: str = ""               # action performed
+    result: str = ""               # result description
+    changes: list = Field(default_factory=list)  # DOM changes
+
+
+class CommandResult(BaseModel):
+    """Standard result returned by all commands."""
+
+    success: bool = False
+    command: str = ""
+    state: StateSnapshot = Field(default_factory=StateSnapshot)
+    feedback: Feedback = Field(default_factory=Feedback)
+    error: Optional[str] = None

navcli/core/models/state.py

@@ -0,0 +1,19 @@
+"""StateSnapshot model for page state."""
+
+from typing import Optional
+from pydantic import BaseModel, Field
+
+from .dom import DOMTree
+
+
+class StateSnapshot(BaseModel):
+    """Represents the current page state."""
+
+    url: str = ""                  # current URL
+    title: str = ""                # page title
+    dom: DOMTree = Field(default_factory=DOMTree)  # DOM tree
+    variables: dict = Field(default_factory=dict)  # page variables
+    loading: bool = False          # is still loading
+    network_idle: bool = True      # network is idle
+    dom_stable: bool = True       # DOM is stable
+    pending_requests: int = 0     # pending request count

navcli/server/__init__.py

@@ -0,0 +1,86 @@
+"""NavCLI Browser Server."""
+
+import asyncio
+import signal
+import sys
+from typing import Optional
+
+import uvicorn
+from uvicorn.config import Config
+
+from navcli.server.app import create_app
+from navcli.server.browser import start_browser, close_browser
+
+__version__ = "0.1.0"
+
+# Server instance
+_server: Optional[uvicorn.Server] = None
+
+
+async def start_server(host: str = "127.0.0.1", port: int = 8765) -> uvicorn.Server:
+    """Start the browser server.
+
+    Args:
+        host: Host to bind
+        port: Port to listen
+
+    Returns:
+        Uvicorn server instance
+    """
+    global _server
+
+    # Start browser
+    await start_browser()
+
+    # Create app
+    app = create_app()
+
+    # Configure uvicorn
+    config = Config(app, host=host, port=port, log_level="info")
+    _server = uvicorn.Server(config)
+
+    # Register shutdown handler
+    def signal_handler():
+        asyncio.create_task(shutdown())
+
+    config.lifespan = "on"
+
+    # Start server
+    await _server.serve()
+
+    return _server
+
+
+async def shutdown():
+    """Shutdown the server."""
+    global _server
+
+    if _server:
+        _server.should_exit = True
+
+    # Close browser
+    await close_browser()
+
+
+def main():
+    """Main entry point for nav-server command."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="NavCLI Browser Server")
+    parser.add_argument("--host", default="127.0.0.1", help="Host to bind")
+    parser.add_argument("--port", type=int, default=8765, help="Port to listen")
+
+    args = parser.parse_args()
+
+    print(f"Starting NavCLI Browser Server on {args.host}:{args.port}...")
+
+    try:
+        asyncio.run(start_server(args.host, args.port))
+    except KeyboardInterrupt:
+        print("\nShutting down...")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()
+

navcli/server/app.py

@@ -0,0 +1,48 @@
+"""FastAPI application for NavCLI Browser Server."""
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from navcli.server.routes import navigation, interaction, query, explore, control, session
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    app = FastAPI(
+        title="NavCLI Browser Server",
+        description="HTTP API for controlling Playwright browser",
+        version="0.1.0",
+    )
+
+    # CORS
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Include routes
+    app.include_router(navigation.router, prefix="/cmd")
+    app.include_router(interaction.router, prefix="/cmd")
+    app.include_router(query.router)
+    app.include_router(explore.router)
+    app.include_router(control.router, prefix="/cmd")
+    app.include_router(session.router, prefix="/cmd")
+
+    @app.get("/")
+    async def root():
+        """Root endpoint."""
+        return {
+            "name": "NavCLI Browser Server",
+            "version": "0.1.0",
+            "status": "running",
+        }
+
+    @app.get("/health")
+    async def health():
+        """Health check endpoint."""
+        return {"status": "healthy"}
+
+    return app