hivepods-cli 0.1.0__tar.gz

hivepods_cli-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: hivepods-cli
+Version: 0.1.0
+Summary: Command line interface for DockHive / HivePods
+Author: DockHive
+License: MIT
+Project-URL: Homepage, https://github.com/DockHive/hive-cli
+Project-URL: Issues, https://github.com/DockHive/hive-cli/issues
+Keywords: dockhive,hivepods,cli,pods,environments,cloud
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+Requires-Dist: websockets>=12.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: rich>=13.0
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+
+# HivePods
+
+Your own cloud dev environment, ready in seconds. Pick an operating system,
+choose how much power you need, and you're in — right from your terminal.
+
+```bash
+hivepod create web1     # a quick wizard: name it, pick an OS + size
+hivepod connect web1    # you're in a shell
+```
+
+## Install
+
+```bash
+pipx install hivepods-cli      # recommended — keeps hivepod on its own
+# or
+pip install hivepods-cli
+```
+
+## Get started
+
+```bash
+hivepod login           # opens your browser to sign in
+hivepod create          # short wizard: name, OS, size
+hivepod connect myenv   # open a shell in your environment
+hivepod list            # see everything you're running
+```
+
+`hivepod login` signs you in through the browser. On a machine with no browser,
+use `hivepod login --no-browser` for email and password instead.
+
+No servers to manage, no setup. Each environment gets its own address
+(`myenv.dockhive.sh`), so whatever you run inside is reachable.
+
+## Everyday commands
+
+```bash
+hivepod create                       # interactive: OS, size (or custom CPU/RAM/disk), region
+hivepod create api --os ubuntu-24.04 --size small    # or one-liner
+
+hivepod connect api                  # interactive shell
+hivepod exec api "npm test"          # run a single command
+hivepod logs api -f                  # follow live logs
+
+hivepod stop api                     # pause (your data stays)
+hivepod start api                    # resume
+hivepod restart api
+hivepod rm api                       # delete
+
+hivepod list                         # what you have
+hivepod status api                   # details + live CPU/RAM
+
+hivepod env api PORT=3000 --unset DEBUG   # change environment variables
+hivepod apply api                    # use them (recreates the environment; data/ and projects/ are kept)
+
+hivepod backup create api            # back up the data/ and projects/ folders
+hivepod backup list
+hivepod backup restore <backup-id> api-copy   # a NEW environment from a backup
+```
+
+Anywhere a command takes a name, you can pass the environment's id instead.
+`start`, `stop`, `restart`, `suspend`, `resume`, `apply`, `rm`, `backup create`
+and `backup restore` wait until the work is done; add `--no-wait` to return
+straight away.
+
+`hivepod connect` works on macOS, Linux and Windows (Windows Terminal or the
+Windows 10+ console).
+
+## Operating systems
+
+Ubuntu, Debian, Fedora, Alpine, Arch, Rocky and more run as fast, lightweight
+environments. **Windows** and **FreeBSD** run as full machines — reach those
+through the built-in web console (or RDP for Windows) instead of a shell.
+
+```bash
+hivepod os              # everything you can launch
+```
+
+## Sizes
+
+Pick a preset, or set your own:
+
+| Size | vCPU | RAM | Disk |
+|------|------|-----|------|
+| nano | 0.5 | 512 MB | 5 GB |
+| micro | 1 | 1 GB | 10 GB |
+| small | 2 | 2 GB | 25 GB |
+| medium | 4 | 4 GB | 50 GB |
+| custom | your call | your call | your call |
+
+## Settings
+
+```bash
+hivepod config set default_size small   # your default when you don't pick one
+hivepod config list
+```
+
+## Help
+
+```bash
+hivepod --help
+hivepod <command> --help
+```

hivepods_cli-0.1.0/README.md

@@ -0,0 +1,102 @@
+# HivePods
+
+Your own cloud dev environment, ready in seconds. Pick an operating system,
+choose how much power you need, and you're in — right from your terminal.
+
+```bash
+hivepod create web1     # a quick wizard: name it, pick an OS + size
+hivepod connect web1    # you're in a shell
+```
+
+## Install
+
+```bash
+pipx install hivepods-cli      # recommended — keeps hivepod on its own
+# or
+pip install hivepods-cli
+```
+
+## Get started
+
+```bash
+hivepod login           # opens your browser to sign in
+hivepod create          # short wizard: name, OS, size
+hivepod connect myenv   # open a shell in your environment
+hivepod list            # see everything you're running
+```
+
+`hivepod login` signs you in through the browser. On a machine with no browser,
+use `hivepod login --no-browser` for email and password instead.
+
+No servers to manage, no setup. Each environment gets its own address
+(`myenv.dockhive.sh`), so whatever you run inside is reachable.
+
+## Everyday commands
+
+```bash
+hivepod create                       # interactive: OS, size (or custom CPU/RAM/disk), region
+hivepod create api --os ubuntu-24.04 --size small    # or one-liner
+
+hivepod connect api                  # interactive shell
+hivepod exec api "npm test"          # run a single command
+hivepod logs api -f                  # follow live logs
+
+hivepod stop api                     # pause (your data stays)
+hivepod start api                    # resume
+hivepod restart api
+hivepod rm api                       # delete
+
+hivepod list                         # what you have
+hivepod status api                   # details + live CPU/RAM
+
+hivepod env api PORT=3000 --unset DEBUG   # change environment variables
+hivepod apply api                    # use them (recreates the environment; data/ and projects/ are kept)
+
+hivepod backup create api            # back up the data/ and projects/ folders
+hivepod backup list
+hivepod backup restore <backup-id> api-copy   # a NEW environment from a backup
+```
+
+Anywhere a command takes a name, you can pass the environment's id instead.
+`start`, `stop`, `restart`, `suspend`, `resume`, `apply`, `rm`, `backup create`
+and `backup restore` wait until the work is done; add `--no-wait` to return
+straight away.
+
+`hivepod connect` works on macOS, Linux and Windows (Windows Terminal or the
+Windows 10+ console).
+
+## Operating systems
+
+Ubuntu, Debian, Fedora, Alpine, Arch, Rocky and more run as fast, lightweight
+environments. **Windows** and **FreeBSD** run as full machines — reach those
+through the built-in web console (or RDP for Windows) instead of a shell.
+
+```bash
+hivepod os              # everything you can launch
+```
+
+## Sizes
+
+Pick a preset, or set your own:
+
+| Size | vCPU | RAM | Disk |
+|------|------|-----|------|
+| nano | 0.5 | 512 MB | 5 GB |
+| micro | 1 | 1 GB | 10 GB |
+| small | 2 | 2 GB | 25 GB |
+| medium | 4 | 4 GB | 50 GB |
+| custom | your call | your call | your call |
+
+## Settings
+
+```bash
+hivepod config set default_size small   # your default when you don't pick one
+hivepod config list
+```
+
+## Help
+
+```bash
+hivepod --help
+hivepod <command> --help
+```

hivepods_cli-0.1.0/hivepods_cli/__init__.py

@@ -0,0 +1,3 @@
+"""HivePods CLI — manage DockHive pods from your terminal."""
+
+__version__ = "0.1.0"

hivepods_cli-0.1.0/hivepods_cli/browser_login.py

@@ -0,0 +1,193 @@
+"""Browser sign-in for the CLI.
+
+Starts a throwaway web server on 127.0.0.1, opens the DockHive sign-in page in
+the browser, and waits for the page to hand the session back to that local
+address once the user has approved. Falls back cleanly if no browser is around.
+
+The page can hand the session back two ways:
+  * POST /callback (form or JSON body with state/token/refresh) — preferred, the
+    token never appears in a URL or the browser history;
+  * GET /callback?state=…&token=…  — still accepted; the reply immediately
+    replaces the history entry so the token doesn't linger there.
+
+Anything else (wrong path, wrong state, wrong Host, stray requests from other
+pages) gets a 4xx and is ignored: we keep waiting for the genuine callback until
+the timeout.
+"""
+from __future__ import annotations
+
+import json
+import secrets
+import threading
+import time
+import urllib.parse
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Optional
+
+# How long we'll sit waiting for the browser round-trip before giving up.
+TIMEOUT_SECONDS = 300
+MAX_BODY = 64 * 1024
+
+_DONE_PAGE = b"""<!doctype html><meta charset="utf-8">
+<meta name="referrer" content="no-referrer">
+<title>DockHive CLI</title>
+<script>try{history.replaceState(null,'','/done')}catch(e){}</script>
+<style>body{font:16px -apple-system,Segoe UI,sans-serif;background:#0b0c0f;color:#e8e8e8;
+display:flex;min-height:100vh;align-items:center;justify-content:center;margin:0}
+div{text-align:center;max-width:22rem;padding:2rem}</style>
+<div><h2>%s</h2><p>%s</p></div>
+"""
+
+
+class _Result:
+    token: Optional[str] = None
+    refresh: Optional[str] = None
+    error: Optional[str] = None
+
+
+class _Handler(BaseHTTPRequestHandler):
+    # bound by start_login() before the server spins up
+    expected_state = ""
+    expected_port = 0
+    result = _Result()
+    done = None  # threading.Event set once a genuine callback was handled
+
+    def log_message(self, *_args):  # silence the default stderr logging
+        pass
+
+    def _reply(self, heading: str, detail: str, code: int = 200):
+        body = _DONE_PAGE % (heading.encode(), detail.encode())
+        self.send_response(code)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("Referrer-Policy", "no-referrer")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _host_ok(self) -> bool:
+        # Blocks DNS-rebinding pages from talking to the loopback server.
+        host = (self.headers.get("Host") or "").lower()
+        return host in (f"127.0.0.1:{self.expected_port}", f"localhost:{self.expected_port}")
+
+    def _handle(self, params: dict):
+        if not self._host_ok():
+            self._reply("Not allowed", "You can close this window.", code=421)
+            return
+        state = params.get("state") or ""
+        if not isinstance(state, str) or not secrets.compare_digest(
+                state.encode(), type(self).expected_state.encode()):
+            # Not our callback (stale tab, another page probing): ignore it.
+            self._reply("Something went wrong", "This sign-in link is not valid. Close this and retry.",
+                        code=400)
+            return
+
+        result = type(self).result
+        if params.get("error"):
+            result.error = "sign-in was cancelled"
+            self._reply("Sign-in cancelled", "You can close this window.")
+            type(self).done.set()
+            return
+
+        token = params.get("token") or ""
+        if not isinstance(token, str) or not token:
+            self._reply("Something went wrong", "No session was returned. Close this and retry.", code=400)
+            return
+
+        result.token = token
+        refresh = params.get("refresh")
+        result.refresh = refresh if isinstance(refresh, str) and refresh else None
+        self._reply("You're signed in", "Head back to your terminal — you can close this window.")
+        type(self).done.set()
+
+    def do_GET(self):
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path != "/callback":
+            self._reply("Not found", "You can close this window.", code=404)
+            return
+        params = {k: v[0] for k, v in urllib.parse.parse_qs(parsed.query).items()}
+        self._handle(params)
+
+    def do_POST(self):
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path != "/callback":
+            self._reply("Not found", "You can close this window.", code=404)
+            return
+        try:
+            length = int(self.headers.get("Content-Length") or 0)
+        except ValueError:
+            length = 0
+        if length <= 0 or length > MAX_BODY:
+            self._reply("Something went wrong", "Invalid request.", code=400)
+            return
+        raw = self.rfile.read(length).decode("utf-8", "replace")
+        ctype = (self.headers.get("Content-Type") or "").split(";")[0].strip().lower()
+        if ctype == "application/json":
+            try:
+                params = json.loads(raw)
+            except ValueError:
+                params = None
+            if not isinstance(params, dict):
+                self._reply("Something went wrong", "Invalid request.", code=400)
+                return
+        else:
+            params = {k: v[0] for k, v in urllib.parse.parse_qs(raw).items()}
+        self._handle(params)
+
+
+def start_login(web_url: str, open_browser: bool = True,
+                timeout: float = TIMEOUT_SECONDS) -> _Result:
+    """Run the loopback sign-in dance and return the captured session.
+
+    Raises RuntimeError on timeout or if the browser reports an error.
+    """
+    state = secrets.token_urlsafe(24)
+
+    server = HTTPServer(("127.0.0.1", 0), _Handler)
+    port = server.server_address[1]
+    done = threading.Event()
+    _Handler.expected_state = state
+    _Handler.expected_port = port
+    _Handler.result = _Result()
+    _Handler.done = done
+
+    auth_url = (
+        web_url.rstrip("/")
+        + "/cli-auth?"
+        + urllib.parse.urlencode({"port": port, "state": state})
+    )
+
+    deadline = time.monotonic() + timeout
+
+    def _serve():
+        # Keep answering until the genuine callback arrives or time runs out;
+        # wrong-state / stray requests don't end the wait.
+        while not done.is_set():
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            server.timeout = min(remaining, 1.0)
+            server.handle_request()
+
+    worker = threading.Thread(target=_serve, daemon=True)
+    worker.start()
+
+    opened = webbrowser.open(auth_url) if open_browser else False
+    if not opened:
+        print("Open this URL in your browser to sign in:\n  " + auth_url)
+
+    worker.join(timeout + 5)
+    try:
+        server.server_close()
+    except OSError:
+        pass
+
+    result = _Handler.result
+    if not done.is_set():
+        raise RuntimeError("timed out waiting for the browser sign-in")
+    if result.error:
+        raise RuntimeError(result.error)
+    if not result.token:
+        raise RuntimeError("no session was returned")
+    return result