clawrium 0.1.0__py3-none-any.whl

clawrium/__init__.py

@@ -0,0 +1,3 @@
+"""Clawrium - CLI tool for managing AI assistant fleets."""
+
+__version__ = "0.1.0"

clawrium/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI commands for Clawrium."""

clawrium/cli/host.py

@@ -0,0 +1,608 @@
+"""Host management commands for Clawrium."""
+
+import getpass
+import shlex
+from datetime import datetime, timezone
+from typing import Optional
+
+import paramiko
+import typer
+from rich.console import Console
+from rich.markup import escape as rich_escape
+from rich.table import Table
+
+from clawrium.core.hosts import (
+    add_host,
+    get_host,
+    get_host_by_key_id,
+    load_hosts,
+    remove_host,
+    update_host,
+    HostsFileCorruptedError,
+)
+from clawrium.core.keys import (
+    generate_host_keypair,
+    get_host_private_key,
+    read_public_key,
+    delete_host_keys,
+    InvalidKeyIdError,
+)
+from clawrium.core.ssh_connection import (
+    get_ssh_config,
+    test_ssh_connection,
+    accept_host_key,
+    HostKeyVerificationRequired,
+)
+from clawrium.core.hardware import gather_hardware
+
+__all__ = ["host_app"]
+
+console = Console()
+
+host_app = typer.Typer(
+    name="host",
+    help="Manage hosts in your fleet",
+    no_args_is_help=True,
+)
+
+
+@host_app.command()
+def init(
+    hostname: str = typer.Argument(..., help="Host IP or hostname to initialize"),
+    user: Optional[str] = typer.Option(
+        None,
+        "--user",
+        "-u",
+        help="SSH user for initial connection (default: current user)",
+    ),
+) -> None:
+    """Initialize a host for Clawrium management.
+
+    Generates a per-host SSH keypair and attempts to configure the xclm
+    management user on the remote host. If SSH access fails, displays
+    manual setup commands.
+    """
+    # Step 1: Generate keypair if not exists
+    private_key = get_host_private_key(hostname)
+    if private_key:
+        console.print(f"Using existing keypair for '{hostname}'")
+    else:
+        console.print(f"Generating SSH keypair for '{hostname}'...")
+        private_key_path, public_key_path = generate_host_keypair(hostname)
+        console.print(f"[green]Keypair created:[/green] {public_key_path}")
+        private_key = private_key_path
+
+    # Read the public key for display/setup
+    public_key_content = read_public_key(hostname)
+
+    # Step 2: Determine connection user
+    connection_user = user or getpass.getuser()
+
+    # Step 3: Try to connect to host
+    console.print(f"\nAttempting connection to {hostname} as {connection_user}...")
+
+    client = paramiko.SSHClient()
+    client.load_system_host_keys()
+    # Use RejectPolicy - we'll handle unknown hosts via HostKeyVerificationRequired
+    client.set_missing_host_key_policy(paramiko.RejectPolicy())
+
+    auto_setup_success = False
+    try:
+        # Try to connect with current user's default keys
+        client.connect(hostname=hostname, username=connection_user, timeout=10)
+
+        transport = client.get_transport()
+        if transport and transport.is_active():
+            console.print("[green]Connection successful![/green]")
+            console.print("Setting up xclm management user...")
+
+            # Execute setup commands (no shell injection - public key written via stdin)
+            setup_commands = [
+                ("sudo useradd -m -s /bin/bash xclm 2>/dev/null || true", None),
+                (
+                    'echo "xclm ALL=(ALL) NOPASSWD:ALL" | sudo tee /etc/sudoers.d/xclm',
+                    None,
+                ),
+                ("sudo chmod 440 /etc/sudoers.d/xclm", None),
+                ("sudo mkdir -p /home/xclm/.ssh", None),
+                ("sudo chmod 700 /home/xclm/.ssh", None),
+                (
+                    "sudo tee /home/xclm/.ssh/authorized_keys",
+                    public_key_content,
+                ),  # Write via stdin
+                ("sudo chmod 600 /home/xclm/.ssh/authorized_keys", None),
+                ("sudo chown -R xclm:xclm /home/xclm/.ssh", None),
+            ]
+
+            for cmd, stdin_data in setup_commands:
+                stdin, stdout, stderr = client.exec_command(cmd)
+                if stdin_data:
+                    stdin.write(stdin_data + "\n")
+                    stdin.channel.shutdown_write()
+                # Drain both stdout and stderr before checking exit status to prevent buffer hangs (W4 fix)
+                stdout.read()
+                stderr_output = stderr.read().decode().strip()
+                exit_status = stdout.channel.recv_exit_status()
+                if exit_status != 0 and "useradd" not in cmd:
+                    console.print(
+                        f"[yellow]Warning:[/yellow] Setup step failed (exit {exit_status})"
+                    )
+                    if stderr_output:
+                        # Escape stderr to prevent Rich markup injection (W2 fix)
+                        console.print(f"  {rich_escape(stderr_output)}")
+
+            # Verify xclm connection works
+            console.print("\nVerifying xclm access...")
+            success, message = test_ssh_connection(
+                hostname=hostname, port=22, user="xclm", key_filename=str(private_key)
+            )
+
+            if success:
+                console.print("[green]xclm user configured successfully![/green]")
+                console.print(f"\nNext step: [cyan]clm host add {hostname}[/cyan]")
+                auto_setup_success = True
+            else:
+                console.print(
+                    f"[yellow]Warning:[/yellow] xclm verification failed: {message}"
+                )
+                console.print("You may need to complete setup manually.")
+
+    except HostKeyVerificationRequired as e:
+        console.print(f"\n[yellow]Unknown host key for {e.hostname}[/yellow]")
+        console.print(f"  Key type: {e.key_type}")
+        console.print(f"  Fingerprint: {e.fingerprint}")
+        console.print(
+            "\n[yellow]Warning:[/yellow] Verify this fingerprint matches the host's actual key."
+        )
+
+        if typer.confirm("\nAccept this host key and retry?"):
+            accept_host_key(hostname, 22, expected_fingerprint=e.fingerprint)
+            console.print("Host key saved. Please run 'clm host init' again.")
+        else:
+            console.print("Connection cancelled.")
+        raise typer.Exit(code=1)
+    except paramiko.SSHException as e:
+        # Handle unknown host key from RejectPolicy
+        if "not found in known_hosts" in str(e) or "Server" in str(e):
+            console.print(f"\n[yellow]Unknown host key for {hostname}[/yellow]")
+            console.print(
+                "Run 'ssh-keyscan' or connect manually first to add the host key."
+            )
+        else:
+            console.print(f"[yellow]SSH error:[/yellow] {e}")
+    except paramiko.AuthenticationException as e:
+        console.print(f"[yellow]Authentication failed:[/yellow] {e}")
+    except Exception as e:
+        console.print(f"[yellow]Could not connect:[/yellow] {e}")
+    finally:
+        client.close()
+
+    # Step 4: If auto-setup failed, show manual commands
+    if not auto_setup_success:
+        console.print("\n[yellow]Manual setup required.[/yellow]")
+        console.print("\nRun these commands on the target host:\n")
+        console.print("[dim]# Create xclm user[/dim]")
+        console.print("sudo useradd -m -s /bin/bash xclm")
+        console.print("")
+        console.print("[dim]# Grant passwordless sudo[/dim]")
+        console.print(
+            'echo "xclm ALL=(ALL) NOPASSWD:ALL" | sudo tee /etc/sudoers.d/xclm'
+        )
+        console.print("sudo chmod 440 /etc/sudoers.d/xclm")
+        console.print("")
+        console.print("[dim]# Setup SSH access[/dim]")
+        console.print("sudo mkdir -p /home/xclm/.ssh")
+        console.print("sudo chmod 700 /home/xclm/.ssh")
+        # Shell-escape public key to prevent injection and escape Rich markup
+        # Use soft_wrap=False to keep command on one line for easy copy-paste
+        escaped_key = shlex.quote(public_key_content) if public_key_content else "''"
+        console.print(
+            f"echo {rich_escape(escaped_key)} | sudo tee /home/xclm/.ssh/authorized_keys",
+            soft_wrap=False,
+        )
+        console.print("sudo chmod 600 /home/xclm/.ssh/authorized_keys")
+        console.print("sudo chown -R xclm:xclm /home/xclm/.ssh")
+        console.print("")
+        console.print(f"Then run: [cyan]clm host add {hostname}[/cyan]")
+        # Exit non-zero so scripts can detect failure (B2 fix)
+        raise typer.Exit(code=1)
+
+
+@host_app.command()
+def add(
+    hostname: str = typer.Argument(..., help="Host IP address or hostname"),
+    port: Optional[int] = typer.Option(
+        None, "--port", "-p", help="SSH port (default: 22)"
+    ),
+    user: Optional[str] = typer.Option(
+        None, "--user", "-u", help="SSH user (default: xclm)"
+    ),
+    alias: Optional[str] = typer.Option(
+        None, "--alias", "-a", help="Friendly name for this host"
+    ),
+    tags: Optional[str] = typer.Option(
+        None, "--tags", "-t", help="Comma-separated tags"
+    ),
+) -> None:
+    """Add a new host to the fleet.
+
+    Requires keypair to exist (run 'clm host init' first).
+    Tests SSH connection before saving. Detects hardware capabilities
+    automatically after successful connection.
+    """
+    # Determine key_id: Try hostname first, fall back to alias
+    # This ensures `clm host init 192.168.1.10` + `clm host add 192.168.1.10 --alias mybox` works
+    from clawrium.core.keys import validate_key_id
+
+    # Try hostname first (most common case: init and add use same identifier)
+    host_key = get_host_private_key(hostname)
+    key_lookup_id = hostname
+
+    # Fall back to alias if hostname key doesn't exist and alias is provided
+    if not host_key and alias:
+        host_key = get_host_private_key(alias)
+        key_lookup_id = alias
+
+    # Validate the resolved key_id to prevent path traversal
+    try:
+        validate_key_id(key_lookup_id)
+    except InvalidKeyIdError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(code=1)
+
+    # Check for per-host keypair (enforces init-first workflow)
+    if not host_key:
+        console.print(f"[red]Error:[/red] No keypair found for '{hostname}'")
+        if alias:
+            console.print(f"  Also checked alias '{alias}'")
+        console.print(f"Run 'clm host init {hostname}' first to generate keys")
+        raise typer.Exit(code=1)
+
+    # Check for duplicate hostname, alias, or key_id
+    try:
+        existing = get_host(hostname)
+        if existing:
+            console.print(f"[red]Error:[/red] Host '{hostname}' already exists")
+            raise typer.Exit(code=1)
+
+        if alias:
+            existing_alias = get_host(alias)
+            if existing_alias:
+                console.print(f"[red]Error:[/red] Alias '{alias}' already in use")
+                raise typer.Exit(code=1)
+
+        # Check key_id uniqueness to prevent cross-host key collision
+        existing_key_id = get_host_by_key_id(key_lookup_id)
+        if existing_key_id:
+            console.print(
+                f"[red]Error:[/red] key_id '{key_lookup_id}' already in use by host '{existing_key_id.get('hostname')}'"
+            )
+            raise typer.Exit(code=1)
+    except HostsFileCorruptedError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(code=1)
+
+    # Load SSH config for hostname resolution
+    ssh_config = get_ssh_config(hostname)
+
+    # CLI flags override defaults
+    final_hostname = ssh_config.get(
+        "hostname", hostname
+    )  # Resolve HostName from SSH config
+    final_port = port if port is not None else int(ssh_config.get("port", 22))
+    final_user = user if user is not None else "xclm"  # Always default to xclm
+    final_key = str(host_key)  # Use per-host key
+
+    console.print(
+        f"Testing connection to {final_hostname}:{final_port} as {final_user}..."
+    )
+
+    # Test connection (per D-10)
+    try:
+        result = test_ssh_connection(
+            hostname=final_hostname,
+            port=final_port,
+            user=final_user,
+            key_filename=final_key,
+        )
+        success, message = result
+    except HostKeyVerificationRequired as e:
+        # TOFU: Show fingerprint and ask user to verify
+        console.print(f"\n[yellow]Unknown host key for {e.hostname}[/yellow]")
+        console.print(f"  Key type: {e.key_type}")
+        console.print(f"  Fingerprint: {e.fingerprint}")
+        console.print(
+            "\n[yellow]Warning:[/yellow] Verify this fingerprint matches the host's actual key."
+        )
+        console.print(
+            "If this is your first connection to this host, this is expected."
+        )
+
+        if not typer.confirm("\nAccept this host key and continue?"):
+            console.print("Connection cancelled.")
+            raise typer.Exit(code=1)
+
+        # Accept the host key with fingerprint verification
+        if not accept_host_key(
+            final_hostname, final_port, expected_fingerprint=e.fingerprint
+        ):
+            console.print(
+                "[red]Error:[/red] Failed to save host key (fingerprint may have changed)"
+            )
+            raise typer.Exit(code=1)
+
+        # Retry connection
+        result = test_ssh_connection(
+            hostname=final_hostname,
+            port=final_port,
+            user=final_user,
+            key_filename=final_key,
+        )
+        success, message = result
+
+    if not success:
+        console.print(f"[red]Connection failed:[/red] {message}")
+        raise typer.Exit(code=1)
+
+    console.print("[green]Connection successful![/green]")
+
+    # Detect hardware (per D-06)
+    console.print("Detecting hardware capabilities...")
+    try:
+        hardware = gather_hardware(
+            hostname=final_hostname, user=final_user, port=final_port, ssh_key=final_key
+        )
+        console.print(
+            f"[green]Hardware detected:[/green] {hardware['architecture']}, "
+            f"{hardware['processor_cores']} cores, "
+            f"{hardware['memtotal_mb']}MB RAM"
+        )
+    except Exception as e:
+        console.print(f"[yellow]Warning:[/yellow] Could not detect hardware: {e}")
+        hardware = {}
+
+    # Build host record (per D-04)
+    # Store resolved hostname for portability; keep original input as ssh_config_host
+    # for SSH config lookup. Do not store key_path for security - look up from SSH config.
+    now = datetime.now(timezone.utc).isoformat()
+
+    # Determine display alias
+    display_alias = alias or (hostname if hostname != final_hostname else None)
+
+    host = {
+        "hostname": final_hostname,  # Resolved hostname for direct connections
+        "key_id": key_lookup_id,  # Key storage identifier (alias, hostname, or generated name)
+        "port": final_port,
+        "user": final_user,
+        "auth_method": "key",
+        "hardware": hardware,
+        "metadata": {
+            "added_at": now,
+            "last_seen": now,
+            "tags": [t.strip() for t in tags.split(",")] if tags else [],
+        },
+    }
+    # Only add optional fields if they have values (avoid null pollution)
+    if hostname != final_hostname:
+        host["ssh_config_host"] = hostname
+    if display_alias:
+        host["alias"] = display_alias
+
+    add_host(host)
+    console.print(
+        f"[green]Host '{display_alias or hostname}' added successfully![/green]"
+    )
+
+
+@host_app.command(name="list")
+def list_hosts() -> None:
+    """List all registered hosts."""
+    try:
+        hosts = load_hosts()
+    except HostsFileCorruptedError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(code=1)
+
+    if not hosts:
+        console.print("No hosts registered. Use 'clm host add' to add a host.")
+        return
+
+    table = Table(title="Registered Hosts")
+
+    table.add_column("Alias", style="cyan")
+    table.add_column("Host", style="white")
+    table.add_column("Architecture", style="yellow")
+    table.add_column("Cores", justify="right")
+    table.add_column("Memory (GB)", justify="right")
+    table.add_column("Tags", style="dim")
+
+    for host in hosts:
+        hw = host.get("hardware", {})
+        meta = host.get("metadata", {})
+
+        # Format memory as GB with 1 decimal
+        mem_gb = (
+            round(hw.get("memtotal_mb", 0) / 1024, 1) if hw.get("memtotal_mb") else "-"
+        )
+
+        table.add_row(
+            host.get("alias") or "-",
+            host["hostname"],
+            hw.get("architecture", "?"),
+            str(hw.get("processor_cores", "?")),
+            str(mem_gb),
+            ", ".join(meta.get("tags", [])) or "-",
+        )
+
+    console.print(table)
+
+
+@host_app.command()
+def remove(
+    hostname: str = typer.Argument(..., help="Host hostname or alias to remove"),
+    force: bool = typer.Option(False, "--force", "-f", help="Skip confirmation prompt"),
+) -> None:
+    """Remove a host from the fleet.
+
+    Prompts for confirmation unless --force is specified.
+    """
+    # Find host by hostname or alias
+    try:
+        host = get_host(hostname)
+    except HostsFileCorruptedError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(code=1)
+
+    if not host:
+        console.print(f"[red]Error:[/red] Host '{hostname}' not found")
+        raise typer.Exit(code=1)
+
+    display_name = host.get("alias") or host["hostname"]
+
+    # Confirmation (per D-18)
+    if not force:
+        confirmed = typer.confirm(
+            f"Remove host '{display_name}'? This cannot be undone."
+        )
+        if not confirmed:
+            console.print("Cancelled.")
+            raise typer.Exit(code=0)  # Clean exit on user cancel, not error
+
+    # Remove by actual hostname
+    success = remove_host(host["hostname"])
+    if success:
+        # Also delete per-host keys using key_id
+        key_id = host.get("key_id") or host["hostname"]  # Fallback for old records
+        keys_deleted = delete_host_keys(key_id)
+        console.print(f"[green]Host '{display_name}' removed successfully.[/green]")
+        if keys_deleted:
+            console.print(f"[dim]Keypair for '{key_id}' deleted.[/dim]")
+    else:
+        console.print("[red]Error:[/red] Failed to remove host")
+        raise typer.Exit(code=1)
+
+
+@host_app.command()
+def status(
+    hostname: str = typer.Argument(..., help="Host hostname or alias to check"),
+    refresh: bool = typer.Option(
+        False, "--refresh", "-r", help="Re-detect hardware capabilities"
+    ),
+) -> None:
+    """Check status of a host.
+
+    Shows connection status, hostname verification, and last seen time.
+    Use --refresh to update hardware information.
+    """
+    # Find host
+    try:
+        host = get_host(hostname)
+    except HostsFileCorruptedError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(code=1)
+
+    if not host:
+        console.print(f"[red]Error:[/red] Host '{hostname}' not found")
+        raise typer.Exit(code=1)
+
+    display_name = host.get("alias") or host["hostname"]
+    console.print(f"Checking status of '{display_name}'...")
+
+    # Get per-host key using key_id
+    key_id = host.get("key_id") or host["hostname"]  # Fallback for old records
+    host_key = get_host_private_key(key_id)
+    if host_key is None:
+        console.print(f"[red]Error:[/red] No keypair found for '{key_id}'")
+        console.print(f"Run 'clm host init {key_id}' to regenerate keys")
+        raise typer.Exit(code=1)
+    ssh_key = str(host_key)
+
+    # Test connection
+    try:
+        result = test_ssh_connection(
+            hostname=host["hostname"],
+            port=host.get("port", 22),
+            user=host.get("user", "xclm"),
+            key_filename=ssh_key,
+        )
+        success, message = result
+    except HostKeyVerificationRequired:
+        success = False
+        message = "Host key verification required"
+        console.print(
+            f"[yellow]Note:[/yellow] Run 'clm host remove {hostname} && clm host add {host['hostname']}' to re-verify the host key."
+        )
+
+    # Refresh hardware BEFORE building table if requested (per D-06)
+    hw = host.get("hardware", {})
+    if refresh and success:
+        console.print("Refreshing hardware information...")
+        try:
+            hw = gather_hardware(
+                hostname=host["hostname"],
+                user=host.get("user", "xclm"),
+                port=host.get("port", 22),
+                ssh_key=ssh_key,
+            )
+
+            # Update host record atomically to prevent TOCTOU races (B3 fix)
+            def apply_hardware_update(h: dict) -> dict:
+                h["hardware"] = hw
+                h["metadata"]["last_seen"] = datetime.now(timezone.utc).isoformat()
+                return h
+
+            try:
+                if update_host(host["hostname"], apply_hardware_update):
+                    console.print("[green]Hardware information updated.[/green]\n")
+                else:
+                    console.print("[yellow]Warning:[/yellow] Host not found during update\n")
+            except Exception as e:
+                console.print(f"[red]Error saving host data:[/red] {e}")
+                raise typer.Exit(code=1)
+        except typer.Exit:
+            raise
+        except Exception as e:
+            console.print(
+                f"[yellow]Warning:[/yellow] Could not refresh hardware: {e}\n"
+            )
+    elif refresh and not success:
+        console.print(
+            "[yellow]Cannot refresh hardware: host is not connected[/yellow]\n"
+        )
+
+    # Display status table
+    table = Table(title=f"Host Status: {display_name}")
+    table.add_column("Property", style="cyan")
+    table.add_column("Value")
+
+    if success:
+        table.add_row("Connection", "[green]Connected[/green]")
+    else:
+        table.add_row("Connection", f"[red]Disconnected[/red] ({message})")
+
+    table.add_row("Hostname", host["hostname"])
+    if host.get("ssh_config_host"):
+        table.add_row("SSH Config", host["ssh_config_host"])
+    table.add_row("Port", str(host.get("port", 22)))
+    table.add_row("User", host.get("user", "xclm"))
+
+    meta = host.get("metadata", {})
+    table.add_row("Added", meta.get("added_at", "Unknown"))
+    table.add_row("Last Seen", meta.get("last_seen", "Unknown"))
+    table.add_row("Tags", ", ".join(meta.get("tags", [])) or "-")
+
+    if hw:
+        table.add_row("Architecture", hw.get("architecture", "?"))
+        table.add_row("CPU Cores", str(hw.get("processor_cores", "?")))
+        table.add_row("Memory", f"{round(hw.get('memtotal_mb', 0) / 1024, 1)} GB")
+        gpu = hw.get("gpu", {})
+        if gpu.get("present"):
+            table.add_row("GPU", gpu.get("vendor") or "Unknown")
+        else:
+            table.add_row("GPU", "None detected")
+
+    console.print(table)
+
+    # Exit 1 if host is disconnected (for scripting)
+    if not success:
+        raise typer.Exit(code=1)

clawrium/cli/init.py

@@ -0,0 +1,58 @@
+"""Init command for Clawrium."""
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from clawrium.core.config import init_config_dir
+from clawrium.core.deps import check_all_dependencies
+
+__all__ = ["init"]
+
+console = Console()
+
+
+def init() -> None:
+    """Initialize Clawrium configuration directory and check dependencies.
+
+    Creates the configuration directory at ~/.config/clawrium/
+    (or XDG_CONFIG_HOME/clawrium/ if set) and verifies that all
+    required dependencies are available.
+
+    Exits with code 1 if any dependency is missing.
+    """
+    # Create config directory
+    config_dir = init_config_dir()
+    console.print("[green]Clawrium initialized![/green]")
+    console.print(f"Config directory: {config_dir}")
+    console.print()
+
+    # Check dependencies
+    deps = check_all_dependencies()
+
+    table = Table(title="Dependency Status")
+    table.add_column("Dependency", style="cyan")
+    table.add_column("Status")
+    table.add_column("Version/Path")
+    table.add_column("Action Required")
+
+    all_found = True
+    for dep in deps:
+        if dep.found:
+            status = "[green]OK[/green]"
+        else:
+            status = "[red]MISSING[/red]"
+            all_found = False
+
+        version_or_path = dep.version or dep.path or "-"
+        action = dep.install_hint if not dep.found else "-"
+        table.add_row(dep.name, status, version_or_path, action)
+
+    console.print(table)
+
+    if not all_found:
+        console.print()
+        console.print(
+            "[yellow]Some dependencies are missing. Please install them before continuing.[/yellow]"
+        )
+        raise typer.Exit(code=1)