portacode 1.4.11.dev0__py3-none-any.whl → 1.4.12.dev1__py3-none-any.whl

portacode/_version.py

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

portacode/cli.py

@@ -405,6 +405,45 @@ def send_control(message: str, gateway: str | None) -> None:  # noqa: D401 – C
         finally:
             await mgr.stop()
 
+        asyncio.run(_run())
+
+
+@cli.command("revert_proxmox_infra")
+@click.option("--gateway", "gateway", "-g", help="Gateway websocket URL (overrides env/ default)")
+def revert_proxmox_infra(gateway: str | None) -> None:  # noqa: D401 – Click callback
+    """Revert the Proxmox infrastructure configuration stored on this device."""
+
+    target_gateway = gateway or os.getenv(GATEWAY_ENV) or GATEWAY_URL
+
+    async def _run() -> None:
+        keypair = get_or_create_keypair()
+        mgr = ConnectionManager(target_gateway, keypair, debug=False)
+        await mgr.start()
+
+        for _ in range(20):
+            if mgr.mux is not None:
+                break
+            await asyncio.sleep(0.1)
+        if mgr.mux is None:
+            click.echo("Failed to initialise connection – aborting.")
+            await mgr.stop()
+            return
+
+        ctl = mgr.mux.get_channel(0)
+        await ctl.send({"cmd": "revert_proxmox_infra"})
+
+        try:
+            with click.progressbar(length=30, label="Waiting for revert response") as bar:
+                for _ in range(30):
+                    try:
+                        reply = await asyncio.wait_for(ctl.recv(), timeout=0.1)
+                        click.echo(click.style("< " + json.dumps(reply, indent=2), fg="cyan"))
+                    except asyncio.TimeoutError:
+                        pass
+                    bar.update(1)
+        finally:
+            await mgr.stop()
+
     asyncio.run(_run())
 
 

portacode/connection/handlers/WEBSOCKET_PROTOCOL.md

@@ -322,7 +322,7 @@ This action does not require any payload fields.
 
 ### `setup_proxmox_infra`
 
-Configures a Proxmox node for Portacode infrastructure usage (API token storage, default storage selection, and bridge setup). Handled by [`ConfigureProxmoxInfraHandler`](./proxmox_infra.py).
+Configures a Proxmox node for Portacode infrastructure usage (API token validation, automatic storage/template detection, bridge/NAT setup, and connectivity verification). Handled by [`ConfigureProxmoxInfraHandler`](./proxmox_infra.py).
 
 **Payload Fields:**
 
@@ -333,7 +333,133 @@ Configures a Proxmox node for Portacode infrastructure usage (API token storage,
 **Responses:**
 
 *   On success, the device will emit a [`proxmox_infra_configured`](#proxmox_infra_configured-event) event with the persisted infra snapshot.
-*   On failure, the device will emit an [`error`](#error) event with details (e.g., permission issues, missing proxmoxer/dnsmasq, or missing root privileges).
+*   On failure, the device will emit an [`error`](#error) event with details (e.g., permission issues, missing proxmoxer/dnsmasq, missing root privileges, or failed network verification).
+
+### `revert_proxmox_infra`
+
+Reverts the Proxmox infrastructure network changes and clears the stored API token. Handled by [`RevertProxmoxInfraHandler`](./proxmox_infra.py).
+
+**Payload Fields:**
+
+This action does not require any payload fields.
+
+**Responses:**
+
+*   On success, the device will emit a [`proxmox_infra_reverted`](#proxmox_infra_reverted-event) event containing the cleared snapshot.
+
+### `create_proxmox_container`
+
+Creates a Portacode-managed LXC container, starts it, and bootstraps the Portacode service by running the commands from [`proxmox_management/setup_portacode.py`](../../proxmox_management/setup_portacode.py). Handled by [`CreateProxmoxContainerHandler`](./proxmox_infra.py).
+
+**Payload Fields:**
+
+*   `template` (string, required): Template identifier to use for the CT (e.g., `local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst`).
+*   `disk_gib` (integer, optional): Rootfs size in GiB (defaults to 32).
+*   `ram_mib` (integer, optional): Memory size in MiB (defaults to 2048).
+*   `cpus` (integer, optional): Number of CPU cores (defaults to 1).
+*   `hostname` (string, optional): Desired hostname inside the container; defaults to `ct<vmid>`.
+*   `username` (string, optional): OS user to provision (defaults to `svcuser`).
+*   `password` (string, optional): Password for the user (used only during provisioning).
+*   `ssh_key` (string, optional): SSH public key to add to the user.
+
+**Responses:**
+
+*   On success, the device will emit a [`proxmox_container_created`](#proxmox_container_created-event) event that includes the Portacode auth key produced inside the container.
+*   On failure, the device will emit an [`error`](#error) event.
+
+### `start_proxmox_container`
+
+Starts a previously provisioned, Portacode-managed LXC container. Handled by [`StartProxmoxContainerHandler`](./proxmox_infra.py).
+
+**Payload Fields:**
+
+*   `ctid` (string, required): Identifier of the container to start.
+
+**Responses:**
+
+*   Emits a [`proxmox_container_action`](#proxmox_container_action-event) event with `action="start"` and the refreshed infra snapshot.
+*   Emits an [`error`](#error) event when the request cannot be fulfilled (e.g., missing infra config, CT not tagged as managed, or API failure).
+
+### `stop_proxmox_container`
+
+Stops a running Portacode-managed container. Handled by [`StopProxmoxContainerHandler`](./proxmox_infra.py).
+
+**Payload Fields:**
+
+*   `ctid` (string, required): Identifier of the container to stop.
+
+**Responses:**
+
+*   Emits a [`proxmox_container_action`](#proxmox_container_action-event) event with `action="stop"` and the refreshed infra snapshot.
+*   Emits an [`error`](#error) event on failure.
+
+### `remove_proxmox_container`
+
+Deletes a managed container from Proxmox (stopping it first if necessary) and removes the stored metadata file. Handled by [`RemoveProxmoxContainerHandler`](./proxmox_infra.py).
+
+**Payload Fields:**
+
+*   `ctid` (string, required): Identifier of the container to delete.
+
+**Responses:**
+
+*   Emits a [`proxmox_container_action`](#proxmox_container_action-event) event with `action="remove"` and the refreshed infra snapshot after deletion.
+*   Emits an [`error`](#error) event on failure.
+
+### `proxmox_container_created`
+
+Emitted after a successful `create_proxmox_container` action. Contains the new container ID, the Portacode public key produced inside the container, and the bootstrap logs.
+
+**Event Fields:**
+
+*   `success` (boolean): True when the CT and Portacode bootstrap succeed.
+*   `message` (string): Human-readable summary (e.g., `Container 103 is ready`).
+*   `ctid` (string): The numeric CT ID.
+*   `public_key` (string): Portacode public auth key created inside the new container.
+*   `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.
+
+### `start_portacode_service`
+
+Runs `sudo portacode service install` inside the container after the dashboard has created the corresponding Device record with the supplied public key.
+
+**Payload Fields:**
+
+*   `ctid` (string, required): Container ID target.
+*   `step_index` (integer, required): Next step index to render inside `proxmox_container_progress`.
+*   `total_steps` (integer, required): The overall total number of steps (including lifecycle, bootstrap, and service installation).
+
+**Responses:**
+
+*   Emits additional [`proxmox_container_progress`](#proxmox_container_progress-event) events to report the authentication and service-install steps.
+*   On success, emits a [`proxmox_service_started`](#proxmox_service_started-event).
+*   On failure, emits a generic [`error`](#error) event.
+
+### `proxmox_service_started`
+
+Indicates that `portacode service install` finished successfully inside a managed container.
+
+**Event Fields:**
+
+*   `success` (boolean): True when the install succeeded.
+*   `message` (string): Success summary (e.g., `Portacode service install completed`).
+*   `ctid` (string): Container ID.
 
 ### `clock_sync_request`
 
@@ -980,20 +1106,37 @@ Provides system information in response to a `system_info` action. Handled by [`
     *   `proxmox` (object): Detection hints for Proxmox VE nodes:
         *   `is_proxmox_node` (boolean): True when Proxmox artifacts (e.g., `/etc/proxmox-release`) exist.
         *   `version` (string|null): Raw contents of `/etc/proxmox-release` when readable.
-        *   `infra` (object): Portacode infrastructure configuration snapshot:
-            *   `configured` (boolean): True when `setup_proxmox_infra` stored an API token.
-            *   `host` (string|null): Hostname used for the API client (usually `localhost`).
-            *   `node` (string|null): Proxmox node name that was targeted.
-            *   `user` (string|null): API token owner (e.g., `root@pam`).
-            *   `token_name` (string|null): API token identifier.
-            *   `default_storage` (string|null): Storage pool chosen for future containers.
-            *   `templates` (array[string]): Cached list of available LXC templates.
-            *   `last_verified` (string|null): ISO timestamp when the token was last validated.
-            *   `network` (object):
-                *   `applied` (boolean): True when the bridge/NAT services were successfully configured.
-                *   `message` (string|null): Informational text about the network setup attempt.
-                *   `bridge` (string): The bridge interface configured (typically `vmbr1`).
-            *   `node_status` (object|null): Status response returned by the Proxmox API when validating the token.
+            *   `infra` (object): Portacode infrastructure configuration snapshot:
+                *   `configured` (boolean): True when `setup_proxmox_infra` stored an API token.
+                *   `host` (string|null): Hostname used for the API client (usually `localhost`).
+                *   `node` (string|null): Proxmox node name that was targeted.
+                *   `user` (string|null): API token owner (e.g., `root@pam`).
+                *   `token_name` (string|null): API token identifier.
+                *   `default_storage` (string|null): Storage pool chosen for future containers.
+                *   `templates` (array[string]): Cached list of available LXC templates.
+                *   `last_verified` (string|null): ISO timestamp when the token was last validated.
+                *   `network` (object):
+                    *   `applied` (boolean): True when the bridge/NAT services were successfully configured.
+                    *   `message` (string|null): Informational text about the network setup attempt.
+                    *   `bridge` (string): The bridge interface configured (typically `vmbr1`).
+                    *   `health` (string|null): `"healthy"` when the connectivity verification succeeded.
+                *   `node_status` (object|null): Status response returned by the Proxmox API when validating the token.
+                *   `managed_containers` (object): Cached summary of the Portacode-managed containers:
+                    *   `updated_at` (string): ISO timestamp when this snapshot was last refreshed.
+                    *   `count` (integer): Number of managed containers.
+                    *   `total_ram_mib` (integer): RAM footprint summed across all containers.
+                    *   `total_disk_gib` (integer): Disk footprint summed across all containers.
+                    *   `total_cpu_share` (number): CPU shares requested across all containers.
+                    *   `containers` (array[object]): Container summaries with the following fields:
+                        *   `vmid` (string|null): Numeric CT ID.
+                        *   `hostname` (string|null): Hostname configured in the CT.
+                        *   `template` (string|null): Template identifier used.
+                        *   `storage` (string|null): Storage pool backing the rootfs.
+                        *   `disk_gib` (integer): Rootfs size in GiB.
+                        *   `ram_mib` (integer): Memory size in MiB.
+                        *   `cpu_share` (number): vCPU-equivalent share requested at creation.
+                        *   `status` (string): Lowercase lifecycle status (e.g., `running`, `stopped`, `deleted`).
+                        *   `created_at` (string|null): ISO timestamp recorded when the CT was provisioned.
     *   `portacode_version` (string): Installed CLI version returned by `portacode.__version__`.
 
 ### `proxmox_infra_configured`
@@ -1006,6 +1149,59 @@ Emitted after a successful `setup_proxmox_infra` action. The event reports the s
 *   `message` (string): User-facing summary (e.g., "Proxmox infrastructure configured").
 *   `infra` (object): Same snapshot described under [`system_info`](#system_info-event) `proxmox.infra`.
 
+### `proxmox_infra_reverted`
+
+Emitted after a successful `revert_proxmox_infra` action. Indicates the infra config is no longer present and the network was restored.
+
+**Event Fields:**
+
+*   `success` (boolean): True when the revert completed.
+*   `message` (string): Summary (e.g., "Proxmox infrastructure configuration reverted").
+*   `infra` (object): Snapshot with `configured=false` (matching [`system_info`](#system_info-event) `proxmox.infra`).
+
+### `proxmox_container_created`
+
+Emitted after a successful `create_proxmox_container` action to report the newly created CT, its Portacode public key, and the bootstrap logs.
+
+**Event Fields:**
+
+*   `success` (boolean): True when the CT provisioning and `portacode connect` steps complete.
+*   `message` (string): Human-readable summary (e.g., `Container 102 is ready`).
+*   `ctid` (string): The container ID that was created.
+*   `public_key` (string): Portacode public auth key discovered inside the container.
+*   `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.
+
+### `proxmox_container_action`
+
+Emitted after `start_proxmox_container`, `stop_proxmox_container`, or `remove_proxmox_container` commands complete. Each event includes the refreshed infra snapshot so dashboards can immediately display the latest managed container totals even though the `proxmox.infra.managed_containers` cache updates only every ~30 seconds.
+
+**Event Fields:**
+
+*   `action` (string): The action that ran (`start`, `stop`, or `remove`).
+*   `success` (boolean): True when the requested action succeeded.
+*   `ctid` (string): Target CT ID.
+*   `message` (string): Human-friendly summary (e.g., `Stopped container 103`).
+*   `status` (string): The container’s new status (e.g., `running`, `stopped`, `deleted`).
+*   `details` (object, optional): Exit status information (e.g., `exitstatus`, `stop_exitstatus`, `delete_exitstatus`).
+*   `infra` (object): Same snapshot described under [`system_info`](#system_info-event) `proxmox.infra`, including the updated `managed_containers` summary.
+
 ### <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/connection/handlers/__init__.py

@@ -14,6 +14,7 @@ from .terminal_handlers import (
     TerminalListHandler,
 )
 from .system_handlers import SystemInfoHandler
+from .update_handler import UpdatePortacodeHandler
 from .file_handlers import (
     FileReadHandler,
     FileWriteHandler,
@@ -40,8 +41,15 @@ from .project_state_handlers import (
     ProjectStateGitRevertHandler,
     ProjectStateGitCommitHandler,
 )
-from .update_handler import UpdatePortacodeHandler
-from .proxmox_infra import ConfigureProxmoxInfraHandler
+from .proxmox_infra import (
+    ConfigureProxmoxInfraHandler,
+    CreateProxmoxContainerHandler,
+    RevertProxmoxInfraHandler,
+    StartPortacodeServiceHandler,
+    StartProxmoxContainerHandler,
+    StopProxmoxContainerHandler,
+    RemoveProxmoxContainerHandler,
+)
 
 __all__ = [
     "BaseHandler",
@@ -54,6 +62,7 @@ __all__ = [
     "TerminalListHandler",
     "SystemInfoHandler",
     "ConfigureProxmoxInfraHandler",
+    "CreateProxmoxContainerHandler",
     # File operation handlers (optional - register as needed)
     "FileReadHandler",
     "FileWriteHandler", 
@@ -79,5 +88,10 @@ __all__ = [
     "ProjectStateGitUnstageHandler",
     "ProjectStateGitRevertHandler",
     "ProjectStateGitCommitHandler",
+    "StartPortacodeServiceHandler",
+    "StartProxmoxContainerHandler",
+    "StopProxmoxContainerHandler",
+    "RemoveProxmoxContainerHandler",
     "UpdatePortacodeHandler",
+    "RevertProxmoxInfraHandler",
 ]