safaai 0.1.0__py3-none-any.whl

safaai/__init__.py

@@ -0,0 +1,3 @@
+"""safaai — TUI-first developer workstation optimizer."""
+
+__version__ = "0.1.0"

safaai/__main__.py

@@ -0,0 +1,22 @@
+import sys
+from safaai.app import SafaaiApp
+from safaai.screens.splash_asciimatics import run_splash_screen
+from safaai.screens.splash import SplashScreen
+
+
+def main():
+    try:
+        run_splash_screen()
+        SplashScreen.skip_delay = True
+    except KeyboardInterrupt:
+        sys.exit(0)
+    except Exception:
+        pass
+
+    app = SafaaiApp()
+    app.run()
+
+
+if __name__ == "__main__":
+    main()
+

safaai/actions/__init__.py

@@ -0,0 +1 @@
+"""Action executors — safe, previewable, trash-aware operations."""

safaai/actions/executor.py

@@ -0,0 +1,201 @@
+"""Execute cleanup commands safely with timeout and reporting."""
+from __future__ import annotations
+
+import asyncio
+import shlex
+
+from safaai.core.debug_log import get_logger
+
+_admin_session_active: bool = False
+_session_sudo_password: str | None = None
+
+
+def set_session_sudo_password(pwd: str | None) -> None:
+    """Set in-memory session sudo password (never stored on disk)."""
+    global _session_sudo_password, _admin_session_active
+    _session_sudo_password = pwd
+    if pwd is not None:
+        _admin_session_active = True
+
+
+def get_session_sudo_password() -> str | None:
+    """Get in-memory session sudo password."""
+    return _session_sudo_password
+
+
+async def verify_sudo_password(pwd: str) -> bool:
+    """Verify sudo password via sudo -S -v."""
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            "sudo", "-S", "-v",
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        await proc.communicate(input=f"{pwd}\n".encode())
+        return proc.returncode == 0
+    except (OSError, asyncio.CancelledError):
+        return False
+
+
+async def request_admin_privileges() -> bool:
+    """Request admin privileges via macOS native dialog.
+
+    Calls ``sudo -v`` through ``osascript`` so the user gets the standard
+    macOS password dialog instead of a hidden terminal prompt. Once
+    authenticated the credential stays cached for the default sudo timeout
+    (usually 5 minutes).
+
+    Returns True if the user authenticated, False if they cancelled.
+    """
+    global _admin_session_active
+    if _session_sudo_password is not None:
+        return True
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            "osascript", "-e",
+            'do shell script "sudo -v" with administrator privileges',
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        await proc.communicate()
+        _admin_session_active = proc.returncode == 0
+    except (OSError, asyncio.CancelledError):
+        _admin_session_active = False
+    return _admin_session_active
+
+
+def admin_session_active() -> bool:
+    """Whether an admin credential is cached for the current session."""
+    return bool(_session_sudo_password) or _admin_session_active
+
+
+async def run_command(cmd: str, timeout: int = 30, sudo_pwd: str | None = None) -> dict:
+    """Run a single shell command with timeout.
+
+    If sudo_pwd is provided (or session password is set), runs with elevated
+    sudo privileges via sudo -S.
+    Returns {"command": str, "exit_code": int, "stdout": str, "stderr": str}.
+    """
+    logr = get_logger()
+    pwd = sudo_pwd or _session_sudo_password
+    logr.debug("  run_command: %s  (timeout=%ds, elevated=%s)", cmd, timeout, bool(pwd),
+               extra={"command": cmd, "timeout": timeout})
+
+    if pwd and (cmd.startswith("sudo ") or "sudo " in cmd):
+        # Convert 'sudo ...' to 'sudo -S ...' for stdin password feeding
+        if cmd.startswith("sudo ") and not cmd.startswith("sudo -S "):
+            cmd = "sudo -S " + cmd[5:]
+        try:
+            proc = await asyncio.create_subprocess_shell(
+                cmd,
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await asyncio.wait_for(
+                proc.communicate(input=f"{pwd}\n".encode()), timeout=timeout
+            )
+            return {
+                "command": cmd,
+                "exit_code": proc.returncode or 0,
+                "stdout": stdout.decode().strip(),
+                "stderr": stderr.decode().strip(),
+            }
+        except asyncio.TimeoutError:
+            return {
+                "command": cmd,
+                "exit_code": -1,
+                "stdout": "",
+                "stderr": f"Timed out after {timeout}s",
+            }
+        except OSError as e:
+            return {"command": cmd, "exit_code": -1, "stdout": "", "stderr": str(e)}
+
+    # When no password is supplied, always use non-interactive 'sudo -n'
+    # so sudo never touches /dev/tty or corrupts terminal line settings.
+    if not pwd and cmd.startswith("sudo ") and not cmd.startswith("sudo -n "):
+        cmd = "sudo -n " + cmd[5:]
+
+    try:
+        proc = await asyncio.create_subprocess_shell(
+            cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+        return {
+            "command": cmd,
+            "exit_code": proc.returncode or 0,
+            "stdout": stdout.decode().strip(),
+            "stderr": stderr.decode().strip(),
+        }
+    except asyncio.TimeoutError:
+        return {
+            "command": cmd,
+            "exit_code": -1,
+            "stdout": "",
+            "stderr": f"Timed out after {timeout}s",
+        }
+    except OSError as e:
+        return {"command": cmd, "exit_code": -1, "stdout": "", "stderr": str(e)}
+
+
+async def run_commands(commands: list[str], timeout: int = 30, sudo_pwd: str | None = None) -> list[dict]:
+    """Run multiple commands sequentially and return results.
+
+    Commands are run one at a time (not parallel) so output stays ordered.
+    """
+    results: list[dict] = []
+    for cmd in commands:
+        result = await run_command(cmd, timeout=timeout, sudo_pwd=sudo_pwd)
+        results.append(result)
+    return results
+
+
+async def force_remove_path(path: str, timeout: int = 30, sudo_pwd: str | None = None) -> dict:
+    """Robust force deletion of files/directories.
+
+    1. Unlocks flags (chflags -R nouchg).
+    2. Grants write permissions (chmod -R u+rwX).
+    3. Runs rm -rf.
+    4. Evaluates if elevated privileges or quarantine fallback are needed.
+    """
+    from pathlib import Path
+
+    pwd = sudo_pwd or _session_sudo_password
+    if "*" in path:
+        shlex_target = path
+    else:
+        target = Path(path)
+        if not target.exists():
+            return {"command": f"rm -rf {path}", "exit_code": 0, "stdout": "", "stderr": "Already deleted"}
+        shlex_target = shlex.quote(str(target))
+
+    await run_command(f"chflags -R nouchg {shlex_target} 2>/dev/null", timeout=10)
+    await run_command(f"chmod -R u+rwX {shlex_target} 2>/dev/null", timeout=10)
+
+    if pwd:
+        await run_command(f"sudo -S chflags -R nouchg {shlex_target} 2>/dev/null", timeout=10, sudo_pwd=pwd)
+        await run_command(f"sudo -S chmod -R u+rwX {shlex_target} 2>/dev/null", timeout=10, sudo_pwd=pwd)
+        res = await run_command(f"sudo -S rm -rf {shlex_target}", timeout=timeout, sudo_pwd=pwd)
+    else:
+        res = await run_command(f"rm -rf {shlex_target}", timeout=timeout)
+
+    if "*" not in path and not Path(path).exists():
+        return res
+
+    if res.get("exit_code", 0) == 0:
+        return res
+
+    if "*" not in path and Path(path).exists():
+        from safaai.actions.trash import move_to_trash
+        status = await move_to_trash(Path(path))
+        return {
+            "command": f"quarantine {path}",
+            "exit_code": 0 if not Path(path).exists() else 1,
+            "stdout": status,
+            "stderr": "" if not Path(path).exists() else "Quarantine fallback completed",
+        }
+
+    return res

safaai/actions/kill.py

@@ -0,0 +1,33 @@
+"""Kill user-owned processes safely."""
+from __future__ import annotations
+
+import os
+import signal
+
+import psutil
+
+
+async def kill_process(pid: int, force: bool = False) -> str:
+    """Send SIGTERM to a process. Returns status message.
+
+    When *force* is True, falls back to SIGKILL after 3s timeout.
+    """
+    try:
+        proc = psutil.Process(pid)
+        name = proc.name() or str(pid)
+    except psutil.NoSuchProcess:
+        return f"Process {pid} already gone."
+
+    try:
+        if force:
+            proc.kill()
+            return f"Killed {name} (PID {pid})."
+        proc.terminate()
+        try:
+            proc.wait(timeout=3)
+            return f"Terminated {name} (PID {pid})."
+        except psutil.TimeoutExpired:
+            proc.kill()
+            return f"Terminated {name} (PID {pid}) — force killed after timeout."
+    except psutil.AccessDenied:
+        return f"Access denied — cannot kill PID {pid} ({name})."

safaai/actions/optimize.py

@@ -0,0 +1,85 @@
+"""macOS optimization actions — kill user apps + purge RAM."""
+from __future__ import annotations
+
+import os
+import signal
+
+import psutil
+
+from safaai.actions.executor import (
+    admin_session_active,
+    get_session_sudo_password,
+    request_admin_privileges,
+    run_command,
+)
+
+
+def _parent_chain(pid: int) -> set[int]:
+    """Return set of PIDs from *pid* up to launchd (PID 1)."""
+    pids = {pid, 1}
+    try:
+        proc = psutil.Process(pid)
+        while True:
+            ppid = proc.ppid()
+            if ppid <= 1:
+                break
+            pids.add(ppid)
+            proc = psutil.Process(ppid)
+    except (psutil.NoSuchProcess, psutil.AccessDenied):
+        pass
+    return pids
+
+
+async def kill_user_apps() -> dict:
+    """Kill all third-party user processes, keeping only system + safaai.
+
+    System = root-owned + /System/ binaries + launchd.
+    Safaai's own PID and its terminal/SSH parent chain are also protected.
+    """
+    my_pid = os.getpid()
+    protected_pids = _parent_chain(my_pid)
+    protected_pids.add(my_pid)
+
+    targets: list[psutil.Process] = []
+
+    for proc in psutil.process_iter(["pid", "name", "username", "exe"]):
+        try:
+            pid = proc.info["pid"]
+            if pid in protected_pids:
+                continue
+            if proc.info.get("username") == "root":
+                continue
+            exe = (proc.info.get("exe") or "")
+            if exe.startswith("/System/") or exe.startswith("/usr/libexec/"):
+                continue
+            targets.append(proc)
+        except (psutil.NoSuchProcess, psutil.AccessDenied):
+            continue
+
+    killed_names: list[str] = []
+    for p in targets:
+        try:
+            p.terminate()
+            killed_names.append(p.name() or str(p.pid))
+        except (psutil.NoSuchProcess, psutil.AccessDenied):
+            pass
+
+    # Grace period then force-kill survivors
+    gone, alive = psutil.wait_procs(targets, timeout=3)
+    for p in alive:
+        try:
+            p.kill()
+        except (psutil.NoSuchProcess, psutil.AccessDenied):
+            pass
+
+    return {"exit_code": 0, "killed": len(killed_names), "stdout": f"Killed {len(killed_names)} apps"}
+
+
+async def purge_memory() -> dict:
+    """Run macOS ``purge`` to release inactive memory pages (needs admin)."""
+    if not admin_session_active():
+        ok = await request_admin_privileges()
+        if not ok:
+            return {"command": "purge", "exit_code": -1, "stdout": "", "stderr": "Admin access denied"}
+    sudo_pwd = get_session_sudo_password()
+    return await run_command("sudo purge", sudo_pwd=sudo_pwd)

safaai/actions/trash.py

@@ -0,0 +1,53 @@
+"""Move paths to system Trash or Quarantine instead of risky delete."""
+from __future__ import annotations
+
+import asyncio
+import shlex
+import shutil
+import time
+from pathlib import Path
+
+
+async def move_to_trash(path: str | Path) -> str:
+    """Move a file or directory to macOS Trash via osascript.
+
+    Falls back to ~/.Trash and then ~/.local/share/safaai/quarantine/
+    Returns a status message.
+    """
+    path = Path(path)
+    if not path.exists():
+        return f"Path does not exist: {path}"
+
+    try:
+        escaped = shlex.quote(str(path.resolve()))
+        script = f'tell app "Finder" to delete POSIX file {escaped}'
+        proc = await asyncio.create_subprocess_exec(
+            "osascript", "-e", script,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        _, stderr = await asyncio.wait_for(proc.communicate(), timeout=10)
+        if proc.returncode == 0:
+            return f"Moved to Trash: {path}"
+    except (OSError, asyncio.TimeoutError):
+        pass
+
+    # Fallback 1: move to ~/.Trash/
+    trash_dir = Path.home() / ".Trash"
+    if trash_dir.exists():
+        trash_target = trash_dir / f"{path.name}_{int(time.time())}"
+        try:
+            await asyncio.to_thread(shutil.move, str(path), str(trash_target))
+            return f"Moved to Trash (fallback): {path}"
+        except OSError:
+            pass
+
+    # Fallback 2: Safe Quarantine directory
+    quarantine_dir = Path.home() / ".local" / "share" / "safaai" / "quarantine"
+    quarantine_dir.mkdir(parents=True, exist_ok=True)
+    quarantine_target = quarantine_dir / f"{int(time.time())}_{path.name}"
+    try:
+        await asyncio.to_thread(shutil.move, str(path), str(quarantine_target))
+        return f"Quarantined safely: {path} → {quarantine_target}"
+    except OSError as e:
+        return f"Failed to trash or quarantine {path}: {e}"

safaai/app.py

@@ -0,0 +1,59 @@
+"""SafaaiApp — root application."""
+from __future__ import annotations
+
+import asyncio
+
+from textual.app import App
+from textual.binding import Binding
+
+from safaai.commands.palette import SafaaiCommandProvider
+from safaai.css import APP_CSS
+from safaai.scanners.brew import BrewScanner
+from safaai.scanners.disk import DiskScanner
+from safaai.scanners.docker import DockerScanner
+from safaai.scanners.graph import GraphScanner
+from safaai.scanners.memory import MemoryScanner
+from safaai.scanners.node import NodeScanner
+from safaai.scanners.project_purge import ProjectPurgeScanner
+from safaai.scanners.registry import get_registry
+from safaai.scanners.startup import StartupScanner
+from safaai.scanners.xcode import XcodeScanner
+from safaai.screens.dashboard import DashboardScreen
+from safaai.screens.splash import SplashScreen
+
+
+class SafaaiApp(App):
+    """Safaai TUI application."""
+
+    TITLE = "safaai"
+    CSS = APP_CSS
+    SCREENS = {
+        "dashboard": DashboardScreen,
+        "splash": SplashScreen,
+    }
+    COMMANDS = {SafaaiCommandProvider}
+
+    BINDINGS = [
+        Binding("q", "quit", "Quit", priority=True),
+    ]
+
+    def on_mount(self) -> None:
+        # Register built-in scanners
+        get_registry().register(DiskScanner())
+        get_registry().register(DockerScanner())
+        get_registry().register(NodeScanner())
+        get_registry().register(BrewScanner())
+        get_registry().register(XcodeScanner())
+        get_registry().register(StartupScanner())
+        get_registry().register(MemoryScanner())
+        get_registry().register(GraphScanner())
+        get_registry().register(ProjectPurgeScanner())
+        # Start on splash
+        self.push_screen("splash")
+
+    def on_exit(self) -> None:
+        """Cancel any still-running background tasks on quit so subprocesses
+        are not orphaned."""
+        for task in asyncio.all_tasks():
+            if task is not asyncio.current_task():
+                task.cancel()

safaai/commands/__init__.py

@@ -0,0 +1 @@
+"""Slash command providers for Textual command palette."""