portacode 1.4.11.dev5__tar.gz → 1.4.11.dev6__tar.gz

{portacode-1.4.11.dev5 → portacode-1.4.11.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: portacode
-Version: 1.4.11.dev5
+Version: 1.4.11.dev6
 Summary: Portacode CLI client and SDK
 Home-page: https://github.com/portacode/portacode
 Author: Meena Erian

{portacode-1.4.11.dev5 → portacode-1.4.11.dev6}/portacode/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '1.4.11.dev5'
-__version_tuple__ = version_tuple = (1, 4, 11, 'dev5')
+__version__ = version = '1.4.11.dev6'
+__version_tuple__ = version_tuple = (1, 4, 11, 'dev6')
 
 __commit_id__ = commit_id = None

{portacode-1.4.11.dev5 → portacode-1.4.11.dev6}/portacode/connection/handlers/WEBSOCKET_PROTOCOL.md

@@ -380,6 +380,22 @@ Emitted after a successful `create_proxmox_container` action. Contains the new c
 *   `container` (object): Metadata such as `vmid`, `hostname`, `template`, `storage`, `disk_gib`, `ram_mib`, and `cpus`.
 *   `setup_steps` (array[object]): Detailed bootstrap step results (name, stdout/stderr, elapsed time, and status).
 
+### `proxmox_container_progress`
+
+Sent intermittently while `create_proxmox_container` is executing so callers can display a progress indicator. Each notification describes the currently running step (validation, provisioning, or each bootstrap command) and whether it succeeded or failed.
+
+**Event Fields:**
+
+*   `step_index` (integer): 1-based index of the current step inside the entire provisioning sequence.
+*   `total_steps` (integer): Total number of steps that must run before provisioning completes.
+*   `step_name` (string): Internal step identifier (e.g., `create_container`, `apt_update`, `portacode_connect`).
+*   `step_label` (string): Human-friendly label suitable for UI (e.g., `Create container`, `Apt update`).
+*   `status` (string): One of `in_progress`, `completed`, or `failed`.
+*   `phase` (string): Either `lifecycle` (environment/container lifecycle) or `bootstrap` (per-command bootstrap work).
+*   `message` (string): Short description of what is happening or why a failure occurred.
+*   `details` (object, optional): Contains `attempt` (if retries were needed) and `error_summary` when a step fails.
+*   `request_id` (string, optional): Mirrors the request ID from the incoming `create_proxmox_container` payload when available.
+
 ### `clock_sync_request`
 
 Internal event that devices send to the gateway to request the authoritative server timestamp (used for adjusting `portacode.utils.ntp_clock`). The gateway responds immediately with [`clock_sync_response`](#clock_sync_response).
@@ -1075,6 +1091,22 @@ Emitted after a successful `create_proxmox_container` action to report the newly
 *   `container` (object): Metadata such as `vmid`, `hostname`, `template`, `storage`, `disk_gib`, `ram_mib`, and `cpus`.
 *   `setup_steps` (array[object]): Detailed bootstrap step reports including stdout/stderr, elapsed time, and pass/fail status.
 
+### `proxmox_container_progress`
+
+Sent continuously while `create_proxmox_container` runs so dashboards can show a progress bar tied to each lifecycle and bootstrap step.
+
+**Event Fields:**
+
+*   `step_index` (integer): 1-based position of the step inside the entire provisioning workflow.
+*   `total_steps` (integer): Total number of lifecycle and bootstrap steps for the current operation.
+*   `step_name` (string): Internal identifier (e.g., `validate_environment`, `install_deps`, `portacode_connect`).
+*   `step_label` (string): Friendly label suitable for the UI.
+*   `status` (string): One of `in_progress`, `completed`, or `failed`.
+*   `phase` (string): Either `lifecycle` (node validation/container lifecycle) or `bootstrap` (commands run inside the CT).
+*   `message` (string): Short human-readable description of the action or failure.
+*   `details` (object, optional): Contains `attempt` (when retries are used) and `error_summary` on failure.
+*   `request_id` (string, optional): Mirrors the `create_proxmox_container` request when provided.
+
 ### <a name="clock_sync_response"></a>`clock_sync_response`
 
 Reply sent by the gateway immediately after receiving a `clock_sync_request`. Devices use this event plus the measured round-trip time to keep their local `ntp_clock` offset accurate.

{portacode-1.4.11.dev5 → portacode-1.4.11.dev6}/portacode/connection/handlers/proxmox_infra.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
 import logging
 import os
@@ -12,7 +13,7 @@ import sys
 import time
 from datetime import datetime
 from pathlib import Path
-from typing import Any, Dict, Iterable, List, Optional, Tuple
+from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple
 
 import platformdirs
 
@@ -39,6 +40,8 @@ IFACES_PATH = Path("/etc/network/interfaces")
 SYSCTL_PATH = Path("/etc/sysctl.d/99-portacode-forward.conf")
 UNIT_DIR = Path("/etc/systemd/system")
 
+ProgressCallback = Callable[[int, int, Dict[str, Any], str, Optional[Dict[str, Any]]], None]
+
 
 def _call_subprocess(cmd: List[str], **kwargs: Any) -> subprocess.CompletedProcess[str]:
     env = os.environ.copy()
@@ -245,6 +248,66 @@ def _format_rootfs(storage: str, disk_gib: int, storage_type: str) -> str:
     return f"{storage}:{disk_gib}G"
 
 
+def _get_provisioning_user_info(message: Dict[str, Any]) -> Tuple[str, str, str]:
+    user = (message.get("username") or "svcuser").strip() if message else "svcuser"
+    user = user or "svcuser"
+    password = message.get("password") or "" if message else ""
+    ssh_key = (message.get("ssh_key") or "").strip() if message else ""
+    return user, password, ssh_key
+
+
+def _friendly_step_label(step_name: str) -> str:
+    if not step_name:
+        return "Step"
+    normalized = step_name.replace("_", " ").strip()
+    return normalized.capitalize()
+
+
+def _build_bootstrap_steps(user: str, password: str, ssh_key: str) -> List[Dict[str, Any]]:
+    steps = [
+        {
+            "name": "apt_update",
+            "cmd": "apt-get update -y",
+            "retries": 4,
+            "retry_delay_s": 5,
+            "retry_on": [
+                "Temporary failure resolving",
+                "Could not resolve",
+                "Failed to fetch",
+            ],
+        },
+        {
+            "name": "install_deps",
+            "cmd": "apt-get install -y python3 python3-pip sudo --fix-missing",
+            "retries": 5,
+            "retry_delay_s": 5,
+            "retry_on": [
+                "lock-frontend",
+                "Unable to acquire the dpkg frontend lock",
+                "Temporary failure resolving",
+                "Could not resolve",
+                "Failed to fetch",
+            ],
+        },
+        {"name": "user_exists", "cmd": f"id -u {user} >/dev/null 2>&1 || adduser --disabled-password --gecos '' {user}", "retries": 0},
+        {"name": "add_sudo", "cmd": f"usermod -aG sudo {user}", "retries": 0},
+    ]
+    if password:
+        steps.append({"name": "set_password", "cmd": f"echo '{user}:{password}' | chpasswd", "retries": 0})
+    if ssh_key:
+        steps.append({
+            "name": "add_ssh_key",
+            "cmd": f"install -d -m 700 /home/{user}/.ssh && echo '{ssh_key}' >> /home/{user}/.ssh/authorized_keys && chown -R {user}:{user} /home/{user}/.ssh",
+            "retries": 0,
+        })
+    steps.extend([
+        {"name": "pip_upgrade", "cmd": "python3 -m pip install --upgrade pip", "retries": 0},
+        {"name": "install_portacode", "cmd": "python3 -m pip install --upgrade portacode", "retries": 0},
+        {"name": "portacode_connect", "type": "portacode_connect", "timeout_s": 30},
+    ])
+    return steps
+
+
 def _get_storage_type(storages: Iterable[Dict[str, Any]], storage_name: str) -> str:
     for entry in storages:
         if entry.get("storage") == storage_name:
@@ -333,9 +396,7 @@ def _build_container_payload(message: Dict[str, Any], config: Dict[str, Any]) ->
     if not storage:
         raise ValueError("Storage pool could not be determined.")
 
-    user = (message.get("username") or "svcuser").strip() or "svcuser"
-    password = message.get("password") or ""
-    ssh_key = (message.get("ssh_key") or "").strip()
+    user, password, ssh_key = _get_provisioning_user_info(message)
 
     payload = {
         "template": template,
@@ -471,15 +532,31 @@ def _summarize_error(res: Dict[str, Any]) -> str:
     return "Command failed; see stdout/stderr for details."
 
 
-def _run_setup_steps(vmid: int, steps: List[Dict[str, Any]], user: str) -> Tuple[List[Dict[str, Any]], bool]:
+def _run_setup_steps(
+    vmid: int,
+    steps: List[Dict[str, Any]],
+    user: str,
+    progress_callback: Optional[ProgressCallback] = None,
+    start_index: int = 1,
+    total_steps: Optional[int] = None,
+) -> Tuple[List[Dict[str, Any]], bool]:
     results: List[Dict[str, Any]] = []
-    for step in steps:
+    computed_total = total_steps if total_steps is not None else start_index + len(steps) - 1
+    for offset, step in enumerate(steps):
+        step_index = start_index + offset
+        if progress_callback:
+            progress_callback(step_index, computed_total, step, "in_progress", None)
+
         if step.get("type") == "portacode_connect":
             res = _portacode_connect_and_read_key(vmid, user, timeout_s=step.get("timeout_s", 10))
             res["name"] = step["name"]
             results.append(res)
             if not res.get("ok"):
+                if progress_callback:
+                    progress_callback(step_index, computed_total, step, "failed", res)
                 return results, False
+            if progress_callback:
+                progress_callback(step_index, computed_total, step, "completed", res)
             continue
 
         attempts = 0
@@ -492,7 +569,11 @@ def _run_setup_steps(vmid: int, steps: List[Dict[str, Any]], user: str) -> Tuple
                 res["error_summary"] = _summarize_error(res)
             results.append(res)
             if res["returncode"] == 0:
+                if progress_callback:
+                    progress_callback(step_index, computed_total, step, "completed", res)
                 break
+            if progress_callback:
+                progress_callback(step_index, computed_total, step, "failed", res)
             retry_on = step.get("retry_on", [])
             if attempts >= step.get("retries", 0) + 1:
                 return results, False
@@ -503,50 +584,25 @@ def _run_setup_steps(vmid: int, steps: List[Dict[str, Any]], user: str) -> Tuple
     return results, True
 
 
-def _bootstrap_portacode(vmid: int, user: str, password: str, ssh_key: str) -> Tuple[str, List[Dict[str, Any]]]:
-    steps = [
-        {
-            "name": "apt_update",
-            "cmd": "apt-get update -y",
-            "retries": 4,
-            "retry_delay_s": 5,
-            "retry_on": [
-                "Temporary failure resolving",
-                "Could not resolve",
-                "Failed to fetch",
-            ],
-        },
-        {
-            "name": "install_deps",
-            "cmd": "apt-get install -y python3 python3-pip sudo --fix-missing",
-            "retries": 5,
-            "retry_delay_s": 5,
-            "retry_on": [
-                "lock-frontend",
-                "Unable to acquire the dpkg frontend lock",
-                "Temporary failure resolving",
-                "Could not resolve",
-                "Failed to fetch",
-            ],
-        },
-        {"name": "user_exists", "cmd": f"id -u {user} >/dev/null 2>&1 || adduser --disabled-password --gecos '' {user}", "retries": 0},
-        {"name": "add_sudo", "cmd": f"usermod -aG sudo {user}", "retries": 0},
-    ]
-    if password:
-        steps.append({"name": "set_password", "cmd": f"echo '{user}:{password}' | chpasswd", "retries": 0})
-    if ssh_key:
-        steps.append({
-            "name": "add_ssh_key",
-            "cmd": f"install -d -m 700 /home/{user}/.ssh && echo '{ssh_key}' >> /home/{user}/.ssh/authorized_keys && chown -R {user}:{user} /home/{user}/.ssh",
-            "retries": 0,
-        })
-    steps.extend([
-        {"name": "pip_upgrade", "cmd": "python3 -m pip install --upgrade pip", "retries": 0},
-        {"name": "install_portacode", "cmd": "python3 -m pip install --upgrade portacode", "retries": 0},
-        {"name": "portacode_connect", "type": "portacode_connect", "timeout_s": 30},
-    ])
-
-    results, ok = _run_setup_steps(vmid, steps, user)
+def _bootstrap_portacode(
+    vmid: int,
+    user: str,
+    password: str,
+    ssh_key: str,
+    steps: Optional[List[Dict[str, Any]]] = None,
+    progress_callback: Optional[ProgressCallback] = None,
+    start_index: int = 1,
+    total_steps: Optional[int] = None,
+) -> Tuple[str, List[Dict[str, Any]]]:
+    actual_steps = steps if steps is not None else _build_bootstrap_steps(user, password, ssh_key)
+    results, ok = _run_setup_steps(
+        vmid,
+        actual_steps,
+        user,
+        progress_callback=progress_callback,
+        start_index=start_index,
+        total_steps=total_steps,
+    )
     if not ok:
         raise RuntimeError("Portacode bootstrap steps failed.")
     key_step = next((entry for entry in results if entry.get("name") == "portacode_connect"), None)
@@ -690,51 +746,205 @@ class CreateProxmoxContainerHandler(SyncHandler):
     def command_name(self) -> str:
         return "create_proxmox_container"
 
+    def _emit_progress_event(
+        self,
+        *,
+        step_index: int,
+        total_steps: int,
+        step_name: str,
+        step_label: str,
+        status: str,
+        message: str,
+        phase: str,
+        request_id: Optional[str],
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        loop = self.context.get("event_loop")
+        if not loop or loop.is_closed():
+            logger.debug(
+                "progress event skipped (no event loop) step=%s status=%s",
+                step_name,
+                status,
+            )
+            return
+
+        payload: Dict[str, Any] = {
+            "event": "proxmox_container_progress",
+            "step_name": step_name,
+            "step_label": step_label,
+            "status": status,
+            "phase": phase,
+            "step_index": step_index,
+            "total_steps": total_steps,
+            "message": message,
+        }
+        if request_id:
+            payload["request_id"] = request_id
+        if details:
+            payload["details"] = details
+
+        future = asyncio.run_coroutine_threadsafe(self.send_response(payload), loop)
+        future.add_done_callback(
+            lambda fut: logger.warning(
+                "Failed to emit progress event for %s: %s", step_name, fut.exception()
+            )
+            if fut.exception()
+            else None
+        )
+
     def execute(self, message: Dict[str, Any]) -> Dict[str, Any]:
         logger.info("create_proxmox_container command received")
-        if os.geteuid() != 0:
-            logger.error("container creation rejected: not running as root")
-            raise PermissionError("Container creation requires root privileges.")
-
-        config = _load_config()
-        if not config or not config.get("token_value"):
-            logger.error("container creation rejected: infra not configured")
-            raise ValueError("Proxmox infrastructure is not configured.")
-        if not config.get("network", {}).get("applied"):
-            logger.error("container creation rejected: network bridge not applied")
-            raise RuntimeError("Proxmox bridge setup must be applied before creating containers.")
-
-        proxmox = _connect_proxmox(config)
-        node = config.get("node") or DEFAULT_NODE_NAME
-        payload = _build_container_payload(message, config)
-        payload["cpuunits"] = max(int(payload["cpus"] * 1024), 10)
-        payload["memory"] = int(payload["ram_mib"])
-        payload["node"] = node
-        logger.debug(
-            "Provisioning container node=%s template=%s ram=%s cpu=%s storage=%s",
-            node,
-            payload["template"],
-            payload["ram_mib"],
-            payload["cpus"],
-            payload["storage"],
+        request_id = message.get("request_id")
+        bootstrap_user, bootstrap_password, bootstrap_ssh_key = _get_provisioning_user_info(message)
+        bootstrap_steps = _build_bootstrap_steps(bootstrap_user, bootstrap_password, bootstrap_ssh_key)
+        total_steps = 3 + len(bootstrap_steps)
+        current_step_index = 1
+
+        def _run_lifecycle_step(
+            step_name: str,
+            step_label: str,
+            start_message: str,
+            success_message: str,
+            action,
+        ):
+            nonlocal current_step_index
+            step_index = current_step_index
+            self._emit_progress_event(
+                step_index=step_index,
+                total_steps=total_steps,
+                step_name=step_name,
+                step_label=step_label,
+                status="in_progress",
+                message=start_message,
+                phase="lifecycle",
+                request_id=request_id,
+            )
+            try:
+                result = action()
+            except Exception as exc:
+                self._emit_progress_event(
+                    step_index=step_index,
+                    total_steps=total_steps,
+                    step_name=step_name,
+                    step_label=step_label,
+                    status="failed",
+                    message=f"{step_label} failed: {exc}",
+                    phase="lifecycle",
+                    request_id=request_id,
+                    details={"error": str(exc)},
+                )
+                raise
+            self._emit_progress_event(
+                step_index=step_index,
+                total_steps=total_steps,
+                step_name=step_name,
+                step_label=step_label,
+                status="completed",
+                message=success_message,
+                phase="lifecycle",
+                request_id=request_id,
+            )
+            current_step_index += 1
+            return result
+
+        def _validate_environment():
+            if os.geteuid() != 0:
+                raise PermissionError("Container creation requires root privileges.")
+            config = _load_config()
+            if not config or not config.get("token_value"):
+                raise ValueError("Proxmox infrastructure is not configured.")
+            if not config.get("network", {}).get("applied"):
+                raise RuntimeError("Proxmox bridge setup must be applied before creating containers.")
+            return config
+
+        config = _run_lifecycle_step(
+            "validate_environment",
+            "Validating infrastructure",
+            "Checking token, permissions, and bridge setup…",
+            "Infrastructure validated.",
+            _validate_environment,
         )
 
-        try:
+        def _create_container():
+            proxmox = _connect_proxmox(config)
+            node = config.get("node") or DEFAULT_NODE_NAME
+            payload = _build_container_payload(message, config)
+            payload["cpuunits"] = max(int(payload["cpus"] * 1024), 10)
+            payload["memory"] = int(payload["ram_mib"])
+            payload["node"] = node
+            logger.debug(
+                "Provisioning container node=%s template=%s ram=%s cpu=%s storage=%s",
+                node,
+                payload["template"],
+                payload["ram_mib"],
+                payload["cpus"],
+                payload["storage"],
+            )
             vmid, _ = _instantiate_container(proxmox, node, payload)
-        except Exception as exc:
-            logger.exception("container instantiation failed")
-            raise
-
-        payload["vmid"] = vmid
-        payload["created_at"] = datetime.utcnow().isoformat() + "Z"
-        _write_container_record(vmid, payload)
+            payload["vmid"] = vmid
+            payload["created_at"] = datetime.utcnow().isoformat() + "Z"
+            _write_container_record(vmid, payload)
+            return proxmox, node, vmid, payload
+
+        proxmox, node, vmid, payload = _run_lifecycle_step(
+            "create_container",
+            "Creating container",
+            "Provisioning the LXC container…",
+            "Container created.",
+            _create_container,
+        )
 
-        try:
+        def _start_container_step():
             _start_container(proxmox, node, vmid)
-            public_key, steps = _bootstrap_portacode(vmid, payload["username"], payload["password"], payload["ssh_public_key"])
-        except Exception:
-            logger.exception("failed to start/setup container %s", vmid)
-            raise
+
+        _run_lifecycle_step(
+            "start_container",
+            "Starting container",
+            "Booting the container…",
+            "Container startup completed.",
+            _start_container_step,
+        )
+
+        def _bootstrap_progress_callback(step_index: int, total: int, step: Dict[str, Any], status: str, result: Optional[Dict[str, Any]]):
+            label = step.get("display_name") or _friendly_step_label(step.get("name", "bootstrap"))
+            if status == "in_progress":
+                message_text = f"{label} is running…"
+            elif status == "completed":
+                message_text = f"{label} completed."
+            else:
+                summary = (result or {}).get("error_summary") or (result or {}).get("error")
+                message_text = f"{label} failed"
+                if summary:
+                    message_text += f": {summary}"
+            details: Dict[str, Any] = {}
+            if status == "failed" and result:
+                if result.get("attempt"):
+                    details["attempt"] = result["attempt"]
+                summary_detail = result.get("error_summary") or result.get("error")
+                if summary_detail:
+                    details["error_summary"] = summary_detail
+            self._emit_progress_event(
+                step_index=step_index,
+                total_steps=total,
+                step_name=step.get("name", "bootstrap"),
+                step_label=label,
+                status=status,
+                message=message_text,
+                phase="bootstrap",
+                request_id=request_id,
+                details=details or None,
+            )
+
+        public_key, steps = _bootstrap_portacode(
+            vmid,
+            payload["username"],
+            payload["password"],
+            payload["ssh_public_key"],
+            steps=bootstrap_steps,
+            progress_callback=_bootstrap_progress_callback,
+            start_index=current_step_index,
+            total_steps=total_steps,
+        )
 
         return {
             "event": "proxmox_container_created",

{portacode-1.4.11.dev5 → portacode-1.4.11.dev6}/portacode/connection/terminal.py

@@ -414,6 +414,7 @@ class TerminalManager:
             "mux": mux,
             "use_content_caching": True,  # Enable content caching optimization
             "debug": self.debug,
+            "event_loop": asyncio.get_running_loop(),
         }
         
         # Initialize command registry

{portacode-1.4.11.dev5 → portacode-1.4.11.dev6}/portacode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: portacode
-Version: 1.4.11.dev5
+Version: 1.4.11.dev6
 Summary: Portacode CLI client and SDK
 Home-page: https://github.com/portacode/portacode
 Author: Meena Erian