runongpu 0.1.0__py3-none-any.whl

runongpu/cli.py

@@ -0,0 +1,107 @@
+# Builds the command-line interface for RunOnGPU.
+import typer
+
+# Prints styled terminal output for a better CLI experience.
+from rich.console import Console
+
+# Project helpers for saving local config, creating runongpu.txt, and loading user settings.
+from runongpu.config import create_runongpu_template_file, get_folder_name_from_repo_url, save_notebook_url, save_repo_url, load_config
+from runongpu.colab import open_colab
+from runongpu.parser import parse_config
+
+
+app = typer.Typer()
+console = Console()
+
+
+@app.command()
+def doctor():
+    # Verifies that the user's local RunOnGPU setup has the required pieces installed.
+    console.print("[bold cyan]Checking RunOnGPU setup...[/bold cyan]")
+
+    console.print("[green]✓ CLI is running[/green]")
+    console.print("[green]✓ Typer is installed[/green]")
+    console.print("[green]✓ Rich is installed[/green]")
+
+    saved_config = load_config()
+
+    if saved_config is None:
+        console.print("[yellow]⚠ No repo URL saved yet[/yellow]")
+        console.print("[yellow]Run: runongpu init[/yellow]")
+    else:
+        console.print("[green]✓ Repo URL is saved[/green]")
+        console.print(f"[green] Repo URL: {saved_config["repo_url"]}")
+
+    try:
+        import playwright
+        console.print("[green]✓ Playwright is installed[/green]")
+    except ImportError:
+        console.print("[red]✗ Playwright is not installed[/red]")
+        console.print("[yellow]Run: pip install playwright[/yellow]")
+
+
+@app.command()
+def init():
+    # Store the GitHub repo that RunOnGPU should clone inside Colab.
+    repo_url = typer.prompt("Enter your Github repo URL")
+
+    console.print("[yellow]Deriving folder name[/yellow]")
+    folder_name = get_folder_name_from_repo_url(repo_url)
+    console.print("[green]Successfully derived folder name[/green]")
+
+    save_repo_url(repo_url, folder_name)
+
+    # Create a starter runongpu.txt so users know where to put setup/build/test/run commands.
+    create_runongpu_template_file()
+
+    console.print("[green]✓ Github repo URL saved. [/green]")
+
+
+@app.command()
+def config():
+    # Show the saved local settings without opening Colab.
+    saved_config = load_config()
+
+    if saved_config is None:
+        console.print("[yellow]No repo url found. Run `runongpu init` first.[/yellow]")
+        return
+
+    console.print("[bold cyan]Saved RunOnGPU config:[/bold cyan]")
+    console.print(f"GitHub repo URL: [green]{saved_config['repo_url']}[/green]")
+
+    notebook_url = saved_config.get("notebook_url", "")
+
+    if notebook_url:
+        console.print(f"Colab notebook URL: [green]{notebook_url}[/green]")
+    else:
+        console.print("Colab notebook URL: [yellow]Not saved yet[/yellow]")
+
+
+@app.command()
+def run():
+    # Main workflow: parse project commands, open Colab, write the notebook cell, and save the notebook URL.
+    saved_config = load_config()
+
+    if saved_config is None:
+        console.print("[red]No repo URL saved. Run `runongpu init` first.[/red]")
+        return
+
+    try:
+        console.print("[yellow]Parsing runongpu.txt. [/yellow]")
+        project_config = parse_config()
+        console.print("[green] Successfully parsed through runongpu.txt")
+    except ValueError as error:
+        console.print(f"[red] runongpu.txt error: [/red]\n {error}")
+        return
+
+    notebook_url = saved_config.get("notebook_url", "")
+
+    console.print("[bold cyan]Starting RunOnGPU...[/bold cyan]")
+    current_notebook_url = open_colab(notebook_url, project_config)
+
+    # Save the copied Colab notebook so future runs reuse it instead of creating another copy.
+    save_notebook_url(current_notebook_url)
+
+
+if __name__ == "__main__":
+    app()

runongpu/colab.py

@@ -0,0 +1,199 @@
+import os
+import subprocess
+import time
+from pathlib import Path
+from urllib.error import URLError
+from urllib.request import urlopen
+
+from playwright.sync_api import sync_playwright
+
+from runongpu.config import load_config
+
+from rich.console import Console
+
+console = Console()
+
+# Path to the real Chrome executable on Windows.
+# RunOnGPU uses real Chrome because Colab/Google login is more reliable there
+# than in Playwright's bundled browser.
+CHROME_EXE = (
+    Path(os.environ["PROGRAMFILES"])
+    / "Google"
+    / "Chrome"
+    / "Application"
+    / "chrome.exe"
+)
+
+# Dedicated Chrome profile for RunOnGPU.
+# This keeps Colab login/session data persistent without touching the user's
+# everyday Chrome profile.
+RUNONGPU_PROFILE_DIR = Path.home() / ".runongpu" / "chrome-profile"
+
+# Local Chrome DevTools Protocol port.
+# Playwright connects to this port to control the real Chrome window.
+DEBUG_PORT = 9222
+
+# Shared starter notebook used only when the user does not already have a saved
+# RunOnGPU notebook URL.
+TEMPLATE_URL = "https://colab.research.google.com/drive/1pB8iVjR4-tPVSEBFjY8ow6N_F34bcMwi?usp=sharing"
+
+
+def wait_for_debug_port(timeout_seconds: int = 15) -> None:
+    """Wait until Chrome is ready for Playwright to connect."""
+    start_time = time.time()
+
+    while time.time() - start_time < timeout_seconds:
+        try:
+            # Chrome exposes this local endpoint after remote debugging starts.
+            with urlopen(f"http://127.0.0.1:{DEBUG_PORT}/json/version", timeout=1):
+                return
+        except URLError:
+            # Chrome can take a moment to launch, so retry briefly instead of failing immediately.
+            time.sleep(0.5)
+
+    
+    raise RuntimeError(
+        f"Chrome did not open remote debugging port {DEBUG_PORT}. "
+        "Close Chrome and try again, or use a different debug port."
+    )
+
+
+def open_colab(notebook_url: str = "", project_config: dict | None = None) -> str:
+    """Open a saved Colab notebook, or copy the template notebook on first run."""
+
+    target_url = notebook_url or TEMPLATE_URL
+
+    # Launch real Chrome with remote debugging enabled so Playwright can attach.
+    # The custom profile lets users sign into Colab once and reuse that session.
+    subprocess.Popen([
+        str(CHROME_EXE),
+        f"--remote-debugging-port={DEBUG_PORT}",
+        f"--user-data-dir={RUNONGPU_PROFILE_DIR}",
+        "--no-first-run",
+        "--no-default-browser-check",
+        target_url,
+    ])
+
+    # Avoid connecting before Chrome has opened its debugging endpoint.
+    wait_for_debug_port()
+
+    with sync_playwright() as playwright:
+        # Attach to the already-open real Chrome window instead of launching a new browser.
+        browser = playwright.chromium.connect_over_cdp(
+            f"http://127.0.0.1:{DEBUG_PORT}"
+        )
+
+        # Use the active browser context and newest tab opened by RunOnGPU.
+        context = browser.contexts[0]
+        page = context.pages[-1]
+
+        if not notebook_url:
+            while True:
+                # Saving a copy usually opens a new Colab tab. expect_page captures
+                # that tab directly instead of guessing with context.pages[-1].
+                with context.expect_page() as new_page_info:
+                    page.get_by_role("button", name="File", exact=True).click()
+                    page.get_by_text("Save a copy in Drive").click()
+
+                # Switch automation to the copied notebook tab.
+                page = new_page_info.value
+                page.wait_for_load_state("domcontentloaded")
+
+                copied_successfully = (
+                    page.url != target_url
+                    and "accounts.google.com" not in page.url
+                )
+
+                if copied_successfully:
+                    break
+
+                input("Please sign into Colab, then press Enter to try again. If already signed in, press enter...")
+
+        current_url = page.url
+
+        if project_config is None:
+            raise RuntimeError("project_config was not passed into open_colab().")
+
+        # project_config contains the parsed setup/build/test/run commands from runongpu.txt.
+        console.print(f"[cyan]project_config:[/cyan] {project_config}")
+        console.print("[cyan]Writing RunOnGPU cell...[/cyan]")
+        write_runongpu_cell(page, project_config)
+
+        console.print("[green]✓ RunOnGPU cell written[/green]")
+        set_t4_gpu_and_run_all(page)
+
+        input("Colab is open. Press Enter when done...")
+
+        browser.close()
+
+        return current_url
+
+
+def write_runongpu_cell(page, project_config: dict):
+    saved_config = load_config()
+
+    # Close popups such as Gemini/Colab assistant before selecting the target cell.
+    page.keyboard.press("Escape")
+    page.wait_for_timeout(1000)
+
+    # Target a known marker in the template instead of relying on the first visible editor.
+    # This avoids accidentally pasting into Gemini or another popup editor.
+    target_cell = page.get_by_text("# Paste your code here:", exact=False).first
+    target_cell.click()
+
+    # Preserve the intended execution order from runongpu.txt:
+    # install dependencies, build the project, run tests, then run the program.
+    all_commands = (
+        project_config["setup"]
+        + project_config["build"]
+        + project_config["test"]
+        + project_config["run"]
+    )
+
+    # Colab shell commands use !, so each parsed command becomes a notebook shell line.
+    command_lines = "\n".join(f"!{command}" for command in all_commands)
+
+    page.keyboard.press("Control+A")
+
+    folder_name = saved_config["folder_name"]
+    repo_url = saved_config["repo_url"]
+
+    code =  f"""
+# Paste your code here:
+folder_name = "{folder_name}"
+github_repo_url = "{repo_url}"
+!rm -rf {folder_name}
+!git clone {{github_repo_url}}
+%cd {{folder_name}}
+{command_lines}
+"""
+
+    # Clipboard paste is faster and more reliable than typing long generated cells.
+    page.evaluate("text => navigator.clipboard.writeText(text)", code)
+    page.keyboard.press("Control+V")
+
+
+def set_t4_gpu_and_run_all(page) -> None:
+    # Open Colab runtime settings so the notebook uses a GPU runtime.
+    console.print("[cyan]Opening Runtime menu...[/cyan]")
+    page.get_by_role("button", name="Runtime", exact=True).click()
+
+    console.print("[cyan]Opening Change runtime type...[/cyan]")
+    page.get_by_role("menuitem", name="Change runtime type", exact=True).click()
+
+    # Select the free T4 GPU option available in Colab.
+    console.print("[cyan]Selecting T4 GPU...[/cyan]")
+    page.get_by_role("radio", name="T4 GPU").click()
+
+    console.print("[cyan]Saving runtime settings...[/cyan]")
+    page.get_by_role("button", name="Save").click()
+
+    # Give Colab time to close the runtime dialog before sending keyboard shortcuts.
+    console.print("[cyan]Waiting for runtime dialog to close...[/cyan]")
+    page.wait_for_timeout(3000)
+    page.keyboard.press("Escape")
+
+    # Start the notebook after the runtime is configured.
+    console.print("[cyan]Running all cells...[/cyan]")
+    page.keyboard.press("Control+F9")
+    console.print("[green]✓ Runtime set and cells started[/green]")

runongpu/config.py

@@ -0,0 +1,111 @@
+# Configuration helpers for RunOnGPU.
+# This file manages small local settings that should persist between CLI runs,
+# such as the GitHub repository URL and the copied Colab notebook URL.
+
+import json
+from pathlib import Path
+from rich.console import Console
+
+console = Console()
+
+# Store RunOnGPU settings in the user's home directory instead of the project repo.
+# This keeps personal/local state out of Git.
+CONFIG_DIR = Path.home() / ".runongpu"
+
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+
+def save_repo_url(repo_url: str, folder_name: str) -> None:
+    CONFIG_DIR.mkdir(exist_ok=True)
+    config = {
+        "repo_url": repo_url,
+        "notebook_url": "",
+        "folder_name": folder_name
+    }
+
+    # Persist the selected project so future `runongpu run` calls know what to clone.
+    with open(CONFIG_FILE, "w", encoding="utf-8") as file:
+        json.dump(config, file, indent=4)
+
+
+def load_config() -> dict | None:
+    # Return None when the user has not run `runongpu init` yet.
+    if not CONFIG_FILE.exists():
+        return None
+
+    # Convert the saved JSON config back into a Python dictionary.
+    with open(CONFIG_FILE, "r", encoding="utf-8") as file:
+        return json.load(file)
+
+
+def save_notebook_url(notebook_url: str) -> None:
+    # Keep the copied Colab notebook URL so RunOnGPU reuses it instead of
+    # creating a new notebook copy every time.
+    config = load_config()
+
+    if config is None:
+        config = {}
+
+    config["notebook_url"] = notebook_url
+
+    with open(CONFIG_FILE, "w", encoding="utf-8") as file:
+        json.dump(config, file, indent=4)
+
+
+def create_runongpu_template_file() -> None:
+    # Create a starter runongpu.txt in the current project folder.
+    # The file documents the command sections that RunOnGPU later parses.
+    txt_path = Path("runongpu.txt")
+
+    if not txt_path.exists():
+
+        txt_path.write_text(
+            """# RunOnGPU Configuration
+#
+# Add one command per line under each section.
+# Empty sections are allowed.
+#
+# Example Python project:
+#
+# [setup]
+# pip install -r requirements.txt
+#
+# [run]
+# python main.py
+#
+# Example CUDA project:
+#
+# [build]
+# nvcc main.cu -o main
+#
+# [run]
+# ./main
+#
+# Example CMake project:
+#
+# [build]
+# cmake -S . -B build
+# cmake --build build
+#
+# [run]
+# ./build/my_program
+
+[setup]
+
+[build]
+
+[test]
+
+[run]
+""",
+            encoding="utf-8",
+        )
+        console.print("[green]✓ Added runongpu.txt to the repo. [/green]")
+    else:
+        console.print("[yellow]runongpu.txt already exists. Good job! Proud of you! [/yellow]")
+
+
+def get_folder_name_from_repo_url(repo_url: str) -> str:
+    # Git clones repositories into a folder named after the repo, so derive that
+    # folder name from the URL instead of asking the user to type it manually.
+    return repo_url.rstrip("/").split("/")[-1].replace(".git", "")

runongpu/parser.py

@@ -0,0 +1,46 @@
+from pathlib import Path
+
+
+def parse_config() -> dict:
+    # Each section maps to the list of commands RunOnGPU should run in Colab.
+    config = {
+        "setup": [],
+        "build": [],
+        "test": [],
+        "run": [],
+    }
+
+    current_section = None
+
+    # Path("runongpu.txt") looks for the file in the current terminal directory.
+    # Users should run RunOnGPU from the project folder that contains runongpu.txt.
+    txt_path = Path("runongpu.txt")
+
+    for line in txt_path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+
+        # Ignore spacing and documentation inside runongpu.txt.
+        if not line:
+            continue
+
+        if line.startswith("#"):
+            continue
+
+        # Section headers decide where the following commands should be stored.
+        # Example: [build] makes current_section equal to "build".
+        if line.startswith("[") and line.endswith("]"):
+            section = line[1:-1].lower()
+
+            if section not in config:
+                raise ValueError(f"Unknown section: {section}")
+
+            current_section = section
+            continue
+
+        # Commands must appear under a valid section so RunOnGPU knows when to run them.
+        if current_section is None:
+            raise ValueError("Command found before any section header.")
+
+        config[current_section].append(line)
+
+    return config

runongpu-0.1.0.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: runongpu
+Version: 0.1.0
+Summary: A CLI tool that runs GitHub projects on free cloud GPUs
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer
+Requires-Dist: rich
+Requires-Dist: playwright
+Dynamic: license-file
+
+# RunOnGPU
+
+RunOnGPU is a CLI tool that helps you run GitHub projects on a GPU with minimal setup.
+
+It is useful if you want to test CUDA, PyTorch, or other GPU code but do not have a local NVIDIA GPU.
+
+## Requirements
+
+* Windows
+* Python 3.10+
+* Git
+* Google Chrome
+* Google account for Colab
+
+## Install
+
+```bash
+pip install runongpu
+python -m playwright install
+
+Check setup:
+
+```bash
+runongpu doctor
+```
+
+## Quick Start
+
+Go to the project you want to run and initialize RunOnGPU:
+
+```bash
+runongpu init
+```
+
+Enter your GitHub repo URL when asked.
+
+This creates a `runongpu.txt` file. Edit this file to tell RunOnGPU how to set up, build, test, and run your project.
+
+Then run:
+
+```bash
+runongpu run
+```
+
+RunOnGPU will open Colab, copy the starter notebook, clone your repo, set the runtime to a T4 GPU, and run your commands.
+
+## runongpu.txt
+
+`runongpu.txt` controls what happens inside Colab.
+
+It has four sections:
+
+```text
+[setup]
+# install dependencies here
+
+[build]
+# compile or build the project here
+
+[test]
+# run tests here
+
+[run]
+# run the final program here
+```
+
+Add one command per line.
+
+## Example: CUDA
+
+If your repo has this structure:
+
+```text
+my-cuda-project/
+├── main.cu
+└── runongpu.txt
+```
+
+Use:
+
+```text
+[setup]
+
+[build]
+nvcc main.cu -o vector_add
+
+[test]
+
+[run]
+./vector_add
+```
+
+## Example: CUDA in a Subfolder
+
+If your repo has this structure:
+
+```text
+runongpu-examples/
+├── cuda/
+│   └── vector-add/
+│       └── main.cu
+└── runongpu.txt
+```
+
+Use:
+
+```text
+[setup]
+
+[build]
+cd cuda/vector-add && nvcc main.cu -o vector_add
+
+[test]
+
+[run]
+cd cuda/vector-add && ./vector_add
+```
+
+## Example: Python
+
+```text
+[setup]
+pip install -r requirements.txt
+
+[build]
+
+[test]
+pytest
+
+[run]
+python main.py
+```
+
+## Example: CMake
+
+```text
+[setup]
+
+[build]
+cmake -S . -B build
+cmake --build build
+
+[test]
+ctest --test-dir build --output-on-failure
+
+[run]
+./build/my_program
+```
+
+## Notes
+
+On the first run, you may need to sign into Google Colab. RunOnGPU saves the copied notebook URL and reuses it on future runs.
+
+Do not interact with the Colab window while RunOnGPU is setting it up.
+
+## Run Tests
+
+```bash
+python -m pytest
+```

runongpu-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+runongpu/cli.py,sha256=1qZ4YtnMsqhyUxaet21fbrOyr0l0XyOoKRrG2Azw6Uo,3777
+runongpu/colab.py,sha256=xnEuOi5cTflpTrDIn07Z1cwrD_A90u0_2hX6hYwjM3s,7357
+runongpu/config.py,sha256=GJMbfKEeJy4bYk7yXCH5nkcoCCiXTJ6E1LWahxb9lpc,2948
+runongpu/parser.py,sha256=8lRiWjAdhxF881SSiZ7XoKDgH236GkinPV0WTbcvNLg,1439
+runongpu-0.1.0.dist-info/licenses/LICENSE,sha256=NhuhsC4al9nqfixPdNMzo1fQYISuisuuOq_3p4844jA,1092
+runongpu-0.1.0.dist-info/METADATA,sha256=9HdF8HLnnpRZvVOzP-bB-VucA1BxYM05RgqkgtCtK_0,2651
+runongpu-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+runongpu-0.1.0.dist-info/entry_points.txt,sha256=MJdJNsR_cdsJlQPGnsTZXMgioq7WI4p1bpenVPANqEA,46
+runongpu-0.1.0.dist-info/top_level.txt,sha256=733xt9x99LcPvPkvO6oHmaCaUbsJRbu09_1qKIk_gdk,9
+runongpu-0.1.0.dist-info/RECORD,,

runongpu-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

runongpu-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+runongpu = runongpu.cli:app

runongpu-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MashrafeeAryan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

runongpu-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+runongpu