relationalai 1.0.0a3__py3-none-any.whl → 1.0.0a5__py3-none-any.whl

relationalai/tools/cli/cli.py

@@ -5,16 +5,37 @@ For more documentation on these commands, visit: https://docs.relationalai.com
 
 from __future__ import annotations
 
+import sys
 from pathlib import Path
 
 import click
 
 from rich.console import Console
+from rich.table import Table
 
 from .config_template import CONFIG_TEMPLATE
 
 console = Console()
 
+def _load_config():
+    """Load config using the unified Config() factory (rai yaml → snowflake toml → dbt profiles)."""
+    from relationalai.config import Config
+
+    try:
+        return Config()
+    except Exception as e:
+        raise click.ClickException(f"Failed to load config: {e}") from e
+
+
+def _validate_session(session) -> None:  # noqa: ANN001
+    """Best-effort validation across session types."""
+    if hasattr(session, "sql"):
+        session.sql("select 1").collect()
+        return
+    if hasattr(session, "execute"):
+        session.execute("select 1").fetchall()
+        return
+
 
 @click.group(invoke_without_command=True)
 @click.version_option()
@@ -26,37 +47,61 @@ def cli(ctx: click.Context):
         click.echo(ctx.get_help())
 
 
-@cli.command()
+@cli.command()  # type: ignore[attr-defined]
 def analyze():
     """Check for errors, warnings, and performance issues in the models."""
     console.print("analyze")
 
 
-@cli.command()
+@cli.command()  # type: ignore[attr-defined]
 def build():
     """Create artifacts, show compilation errors, and produce SQL for the models."""
     console.print("build")
 
 
-@cli.command()
+@cli.command()  # type: ignore[attr-defined]
 def connect():
     """Validate config and database connection."""
-    console.print("connect")
+    config = _load_config()
+    try:
+        connection = config.get_default_connection()
+    except Exception as e:
+        raise click.ClickException(f"Failed to resolve default connection: {e}") from e
+
+    session = None
+    err: Exception | None = None
+    try:
+        session = connection.get_session()
+        _validate_session(session)
+        status = "[green]OK[/green]"
+    except Exception as e:
+        session = None
+        err = e
+        status = "[red]FAIL[/red]"
+
+    table = Table(show_header=False)
+    table.add_row("Connection Status", status)
+    console.print(table)
+
+    if err is not None:
+        raise click.ClickException(f"Connection failed: {err}") from err
+
+    return session
 
 
-@cli.command()
+@cli.command()  # type: ignore[attr-defined]
 def deploy():
     """Deploy models/views to the database and produce SQL for execution."""
     console.print("deploy")
 
 
-@cli.command()
+@cli.command()  # type: ignore[attr-defined]
 def explore():
     """Model explorer for visualization of data."""
     console.print("explore")
 
 
-@cli.command()
+@cli.command()  # type: ignore[attr-defined]
 def init():
     """Create a template for the YAML config file."""
     config_file = Path("raiconfig.yml")
@@ -73,18 +118,155 @@ def init():
         raise click.ClickException(f"Failed to create config file: {e}")
 
 
-@cli.command()
+@cli.command()  # type: ignore[attr-defined]
 @click.option("--uninstall", is_flag=True, help="Nukes the database")
 def clean(uninstall: bool):
     """Clean up build folder and remove artifacts."""
     console.print("clean")
 
 
-@cli.command()
+@cli.command()  # type: ignore[attr-defined]
 def test():
     """Run constraints and tests."""
     console.print("test")
 
 
+@cli.group()  # type: ignore[attr-defined]
+def docs():
+    """Generate and serve documentation site."""
+    pass
+
+
+@docs.command()
+@click.option(
+    "--output",
+    "-o",
+    default=None,
+    help="Output directory for generated documentation (defaults to docs/dist)",
+)
+def generate(output: str | None):
+    """Generate static documentation site from models."""
+    from .docs import generate_docs
+
+    try:
+        generate_docs(output_dir=output)
+    except click.ClickException as e:
+        # Print formatted error message and exit
+        console.print(f"[red]✗ Failed to generate documentation: {e.message}[/red]")
+        sys.exit(1)
+    except Exception as e:
+        console.print(f"[red]✗ Failed to generate documentation: {e}[/red]")
+        sys.exit(1)
+
+
+@docs.command()
+@click.option(
+    "--port",
+    "-p",
+    default=8000,
+    type=int,
+    help="Port to serve documentation on (default: 8000)",
+)
+@click.option(
+    "--host",
+    default="127.0.0.1",
+    help="Host to bind to (default: 127.0.0.1)",
+)
+@click.option(
+    "--build-dir",
+    default=None,
+    help="Directory containing built documentation (defaults to docs/dist)",
+)
+@click.option(
+    "--no-open",
+    is_flag=True,
+    help="Don't open browser automatically",
+)
+def serve(port: int, host: str, build_dir: str | None, no_open: bool):
+    """Serve generated documentation site."""
+    from .docs import find_docs_dir, serve_docs
+
+    # Determine build directory
+    if build_dir is None:
+        docs_dir = find_docs_dir()
+        build_dir = str(docs_dir / "dist")
+
+    try:
+        serve_docs(
+            build_dir=build_dir,
+            host=host,
+            port=port,
+            open_browser=not no_open,
+        )
+    except click.ClickException as e:
+        # Print formatted error message and exit
+        console.print(f"[red]✗ Failed to start server: {e.message}[/red]")
+        sys.exit(1)
+    except Exception as e:
+        console.print(f"[red]✗ Failed to start server: {e}[/red]")
+        sys.exit(1)
+
+
+@docs.command()
+@click.option(
+    "--port",
+    "-p",
+    default=5173,
+    type=int,
+    help="Port to serve development server on (default: 5173)",
+)
+@click.option(
+    "--host",
+    default="127.0.0.1",
+    help="Host to bind to (default: 127.0.0.1)",
+)
+@click.option(
+    "--no-open",
+    is_flag=True,
+    help="Don't open browser automatically",
+)
+def dev(port: int, host: str, no_open: bool):
+    """Start development server with hot module replacement (HMR).
+
+    This command runs Vite's dev server which provides:
+    - Hot module replacement - changes reflect instantly
+    - Fast refresh - no need to rebuild on every change
+    - Source maps for debugging
+
+    Use this for development instead of 'rai docs generate' + 'rai docs serve'.
+    """
+    from .docs import dev_docs
+
+    try:
+        dev_docs(
+            host=host,
+            port=port,
+            open_browser=not no_open,
+        )
+    except click.ClickException as e:
+        # Print formatted error message and exit
+        console.print(f"[red]✗ Failed to start dev server: {e.message}[/red]")
+        sys.exit(1)
+    except Exception as e:
+        console.print(f"[red]✗ Failed to start dev server: {e}[/red]")
+        sys.exit(1)
+
+
+@docs.command(name="clean")
+def clean_docs():
+    """Remove auto generated files and directories."""
+    from .docs import cleanup_docs
+
+    try:
+        cleanup_docs()
+    except click.ClickException as e:
+        # Print formatted error message and exit
+        console.print(f"[red]✗ Failed to cleanup: {e.message}[/red]")
+        sys.exit(1)
+    except Exception as e:
+        console.print(f"[red]✗ Failed to cleanup: {e}[/red]")
+        sys.exit(1)
+
+
 if __name__ == "__main__":
-    cli()
+    cli()  # type: ignore[call-arg]

relationalai/tools/cli/components/progress_reader.py

@@ -96,7 +96,7 @@ class _RenderableWrapper:
         """Rich protocol - yield the result of calling the callable."""
         result = self._callable()
         # Result should always be a Group, which implements __rich_console__
-        yield from result.__rich_console__(console, options)
+        yield from result.__rich_console__(console, options)  # type: ignore[return-value, attr-defined]
 
 @dataclass(frozen=False)
 class Task:

relationalai/tools/cli/docs.py

@@ -0,0 +1,394 @@
+"""
+Documentation generation and serving utilities.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import webbrowser
+from pathlib import Path
+from typing import Optional
+
+import click
+from rich.console import Console
+
+console = Console()
+
+
+def find_docs_dir() -> Path:
+    """Find the documentation source directory."""
+    # Try multiple possible locations
+    possible_paths = [
+        Path("docs"),  # Root level
+        Path(__file__).parent.parent.parent.parent / "docs",  # From this file
+        Path.cwd() / "docs",  # Current working directory
+    ]
+
+    for path in possible_paths:
+        if path.exists() and (path / "package.json").exists():
+            return path.resolve()
+
+    raise click.ClickException(
+        "Documentation source directory not found. "
+        "Expected 'docs/' directory with package.json"
+    )
+
+
+def has_nodejs() -> bool:
+    """Check if Node.js is installed."""
+    try:
+        subprocess.run(
+            ["node", "--version"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return False
+
+
+def has_npm() -> bool:
+    """Check if npm is installed."""
+    try:
+        subprocess.run(
+            ["npm", "--version"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return False
+
+
+def print_generation_success(output_path: Path) -> None:
+    """
+    Print success message after documentation generation.
+
+    Args:
+        output_path: Path to the generated documentation output directory
+    """
+    console.print("[green]✓ Documentation generated")
+    console.print()
+    console.print("[cyan]The documentation site is ready to host![/cyan]")
+    console.print(f"[dim]Output location: {output_path}[/dim]")
+    console.print()
+    console.print("[yellow]You can serve it locally with:[/yellow]")
+    console.print("  [bold]rai docs serve[/bold]")
+    console.print()
+    console.print("[yellow]Or host the dist folder directly:[/yellow]")
+    console.print(
+        "[dim]The dist folder contains a complete static website. You can copy it to any "
+        "web server (Nginx, Apache, Flask, etc.), upload it to a CDN, or deploy it to "
+        "static hosting services like GitHub Pages, Netlify, or Vercel. All files use "
+        "relative paths, so it works regardless of where it's hosted.[/dim]"
+    )
+
+
+def generate_docs(
+    output_dir: Optional[str] = None,
+    docs_dir: Optional[Path] = None,
+) -> Path:
+    """
+    Generate static documentation site.
+
+    Args:
+        output_dir: Optional output directory (defaults to docs/dist)
+        docs_dir: Optional path to docs directory
+
+    Returns:
+        Path to the generated output directory
+    """
+    if docs_dir is None:
+        docs_dir = find_docs_dir()
+
+    # Check prerequisites
+    if not has_nodejs():
+        raise click.ClickException(
+            "Node.js is not installed. "
+            "Please install Node.js from https://nodejs.org/"
+        )
+
+    if not has_npm():
+        raise click.ClickException(
+            "npm is not installed. "
+            "npm should come with Node.js installation."
+        )
+
+    # Check if package.json exists
+    package_json = docs_dir / "package.json"
+    if not package_json.exists():
+        raise click.ClickException(
+            f"package.json not found in {docs_dir}. "
+            "This doesn't appear to be a valid SolidJS project."
+        )
+
+    # Install dependencies if node_modules doesn't exist
+    node_modules = docs_dir / "node_modules"
+    if not node_modules.exists():
+        console.print("[blue]Installing dependencies...[/blue]")
+        try:
+            subprocess.run(
+                ["npm", "install"],
+                cwd=docs_dir,
+                check=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+            )
+            console.print("[green]✓ Dependencies installed[/green]")
+        except subprocess.CalledProcessError as e:
+            error_msg = e.stderr.decode() if e.stderr else "Unknown error"
+            raise click.ClickException(
+                f"Failed to install dependencies: {error_msg}"
+            )
+
+    # Build the documentation
+    console.print("[blue]Building documentation site...[/blue]")
+    try:
+        subprocess.run(
+            ["npm", "run", "build"],
+            cwd=docs_dir,
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        console.print("[green]✓ Build completed successfully[/green]")
+    except subprocess.CalledProcessError as e:
+        error_msg = e.stderr if e.stderr else e.stdout if e.stdout else "Unknown error"
+        console.print(f"[red]Build error output:[/red]\n{error_msg}")
+        raise click.ClickException(f"Build failed: {error_msg}")
+
+    # Determine output directory
+    build_output = docs_dir / "dist"
+    if not build_output.exists():
+        raise click.ClickException(
+            "Build output directory not found. "
+            "Build may have failed."
+        )
+
+    # Copy to custom output directory if specified
+    if output_dir:
+        output_path = Path(output_dir).resolve()
+        if output_path.exists():
+            console.print(f"[yellow]Output directory '{output_path}' exists. Cleaning...[/yellow]")
+            shutil.rmtree(output_path)
+        shutil.copytree(build_output, output_path)
+        print_generation_success(output_path)
+        return output_path
+
+    print_generation_success(build_output)
+    return build_output
+
+
+def serve_docs(
+    build_dir: str,
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    open_browser: bool = True,
+) -> None:
+    """
+    Serve generated documentation site.
+
+    Args:
+        build_dir: Directory containing built documentation
+        host: Host to bind to
+        port: Port to serve on
+        open_browser: Whether to open browser automatically
+    """
+    build_path = Path(build_dir).resolve()
+
+    if not build_path.exists():
+        raise click.ClickException(
+            "Build directory does not exist. "
+            "Run 'rai docs generate' first."
+        )
+
+    index_html = build_path / "index.html"
+    if not index_html.exists():
+        raise click.ClickException(
+            "index.html not found. "
+            "This doesn't appear to be a valid build directory. "
+            "Run 'rai docs generate' first."
+        )
+
+    # Import FastAPI here to avoid requiring it if not using server
+    try:
+        from fastapi import FastAPI
+        from fastapi.staticfiles import StaticFiles
+        import uvicorn
+    except ImportError:
+        raise click.ClickException(
+            "FastAPI and uvicorn are required for serving documentation. "
+            "Install with: pip install fastapi uvicorn"
+        )
+
+    app = FastAPI(title="RAI Documentation")
+    app.mount("/", StaticFiles(directory=str(build_path), html=True), name="static")
+
+    url = f"http://{host}:{port}"
+    console.print(f"[green]✓ Documentation server running at {url}[/green]")
+    console.print("[yellow]Press Ctrl+C to stop the server[/yellow]")
+
+    if open_browser:
+        try:
+            webbrowser.open(url)
+        except Exception:
+            console.print(f"[yellow]Could not open browser automatically. Visit {url}[/yellow]")
+
+    try:
+        uvicorn.run(app, host=host, port=port, log_level="warning")
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Server stopped[/yellow]")
+    except OSError as e:
+        if "Address already in use" in str(e):
+            raise click.ClickException(
+                f"Port {port} is already in use. "
+                "Try a different port with --port option."
+            )
+        raise
+
+
+def dev_docs(
+    docs_dir: Optional[Path] = None,
+    host: str = "127.0.0.1",
+    port: int = 5173,
+    open_browser: bool = True,
+) -> None:
+    """
+    Start development server with hot module replacement.
+
+    This runs Vite's dev server, which provides:
+    - Hot module replacement (HMR) - changes reflect instantly
+    - Fast refresh - no need to rebuild on every change
+    - Source maps for debugging
+
+    Args:
+        docs_dir: Optional path to docs directory
+        host: Host to bind to
+        port: Port to serve on (default: 5173, Vite's default)
+        open_browser: Whether to open browser automatically
+    """
+    if docs_dir is None:
+        docs_dir = find_docs_dir()
+
+    # Check prerequisites
+    if not has_nodejs():
+        raise click.ClickException(
+            "Node.js is not installed. "
+            "Please install Node.js from https://nodejs.org/"
+        )
+
+    if not has_npm():
+        raise click.ClickException(
+            "npm is not installed. "
+            "npm should come with Node.js installation."
+        )
+
+    # Check if package.json exists
+    package_json = docs_dir / "package.json"
+    if not package_json.exists():
+        raise click.ClickException(
+            f"package.json not found in {docs_dir}. "
+            "This doesn't appear to be a valid SolidJS project."
+        )
+
+    # Install dependencies if node_modules doesn't exist
+    node_modules = docs_dir / "node_modules"
+    if not node_modules.exists():
+        console.print("[blue]Installing dependencies...[/blue]")
+        try:
+            subprocess.run(
+                ["npm", "install"],
+                cwd=docs_dir,
+                check=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+            )
+            console.print("[green]✓ Dependencies installed[/green]")
+        except subprocess.CalledProcessError as e:
+            error_msg = e.stderr.decode() if e.stderr else "Unknown error"
+            raise click.ClickException(
+                f"Failed to install dependencies: {error_msg}"
+            )
+
+    # Start dev server
+    url = f"http://{host}:{port}"
+    console.print("[green]✓ Starting development server...[/green]")
+    console.print(f"[blue]Server will be available at {url}[/blue]")
+    console.print("[yellow]Press Ctrl+C to stop the server[/yellow]")
+    console.print(
+        "[dim]Note: Changes to files will automatically reload in the browser[/dim]"
+    )
+
+    if open_browser:
+        # Open browser after a short delay to let server start
+        import threading
+        import time
+
+        def open_browser_delayed():
+            time.sleep(1.5)  # Give server time to start
+            try:
+                webbrowser.open(url)
+            except Exception:
+                console.print(f"[yellow]Could not open browser automatically. Visit {url}[/yellow]")
+
+        threading.Thread(target=open_browser_delayed, daemon=True).start()
+
+    try:
+        # Run npm run dev with custom host/port
+        # Vite accepts --host and --port flags directly
+        subprocess.run(
+            ["npm", "run", "dev", "--", "--host", host, "--port", str(port)],
+            cwd=docs_dir,
+            check=True,
+        )
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Development server stopped[/yellow]")
+    except subprocess.CalledProcessError as e:
+        error_msg = e.stderr.decode() if e.stderr else e.stdout.decode() if e.stdout else "Unknown error"
+        raise click.ClickException(f"Dev server failed: {error_msg}")
+    except OSError as e:
+        if "Address already in use" in str(e):
+            raise click.ClickException(
+                f"Port {port} is already in use. "
+                "Try a different port with --port option."
+            )
+        raise
+
+
+def cleanup_docs(docs_dir: Optional[Path] = None) -> None:
+    """
+    Clean up generated files and dependencies.
+
+    Silently removes:
+    - node_modules/ directory
+    - dist/ directory (build output)
+
+    Args:
+        docs_dir: Optional path to docs directory
+    """
+    if docs_dir is None:
+        docs_dir = find_docs_dir()
+
+    removed_items = []
+
+    # Remove node_modules
+    node_modules = docs_dir / "node_modules"
+    if node_modules.exists() and node_modules.is_dir():
+        try:
+            shutil.rmtree(node_modules)
+            removed_items.append("node_modules")
+        except Exception as e:
+            raise click.ClickException(f"Failed to remove node_modules: {e}")
+
+    # Remove dist
+    dist = docs_dir / "dist"
+    if dist.exists() and dist.is_dir():
+        try:
+            shutil.rmtree(dist)
+            removed_items.append("dist")
+        except Exception as e:
+            raise click.ClickException(f"Failed to remove dist: {e}")
+

relationalai/tools/debugger.py

@@ -1,11 +1,15 @@
 # debug_snapshot.py
 from __future__ import annotations
-import os, json, time, tempfile
+import os
+import json
+import time
+import tempfile
 from typing import List
 
 def _tail_lines(path: str, max_lines: int) -> List[str]:
     """Tail last N lines efficiently; fine for small/medium files."""
-    if not os.path.exists(path): return []
+    if not os.path.exists(path):
+        return []
     # simple approach: read and slice; optimize later if needed
     with open(path, "r", encoding="utf-8", errors="ignore") as f:
         return f.readlines()[-max_lines:]
@@ -17,11 +21,14 @@ def write_snapshot(spans_jsonl: str, out_html: str, last: int = 5000):
     os.makedirs(os.path.dirname(out_html) or ".", exist_ok=True)
     fd, tmp = tempfile.mkstemp(dir=os.path.dirname(out_html) or ".", prefix=".part-", suffix=".html")
     with os.fdopen(fd, "w", encoding="utf-8") as f:
-        f.write(html); f.flush(); os.fsync(f.fileno())
+        f.write(html)
+        f.flush()
+        os.fsync(f.fileno())
     os.replace(tmp, out_html)
 
 def start_background_snapshots(spans_jsonl: str, out_html: str, interval_ms: int = 1000, last: int = 5000):
-    import threading, atexit
+    import threading
+    import atexit
     stop = threading.Event()
 
     def loop():