portacode 0.3.11.dev4__tar.gz → 0.3.12.dev0__tar.gz

portacode-0.3.12.dev0/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:stackoverflow.com)"
+    ],
+    "deny": []
+  }
+}

{portacode-0.3.11.dev4 → portacode-0.3.12.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: portacode
-Version: 0.3.11.dev4
+Version: 0.3.12.dev0
 Summary: Portacode CLI client and SDK
 Home-page: https://github.com/portacode/portacode
 Author: Meena Erian

portacode-0.3.12.dev0/backup.sh

@@ -0,0 +1,42 @@
+# backup.sh
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ensure we’re in project root
+cd "$(dirname "$0")"
+
+# config
+BACKUP_DIR="${1:-$PWD/../backups}"
+VOLUME_NAME="portacode_pgdata"
+SERVICE_NAME="db"
+
+mkdir -p "$BACKUP_DIR"
+
+# check & stop DB for a consistent dump
+if [ "$(docker inspect -f '{{.State.Running}}' portacode-db 2>/dev/null || echo false)" = "true" ]; then
+  echo "🛑 Stopping $SERVICE_NAME..."
+  docker-compose stop "$SERVICE_NAME"
+  RESTART_DB=true
+else
+  RESTART_DB=false
+fi
+
+# create backup
+TS=$(date +%F_%H-%M-%S)
+FILE="pgdata-$TS.tar.gz"
+echo "📦 Backing up volume to $BACKUP_DIR/$FILE..."
+docker run --rm \
+  -v "${VOLUME_NAME}":/data:ro \
+  -v "${BACKUP_DIR}":/backup \
+  alpine \
+  sh -c "cd /data && tar czf /backup/${FILE} ."
+
+echo "✅ Backup complete."
+
+# restart DB if we stopped it
+if [ "$RESTART_DB" = true ]; then
+  echo "🔄 Starting $SERVICE_NAME..."
+  docker-compose start "$SERVICE_NAME"
+fi
+
+echo "🎉 Done."

{portacode-0.3.11.dev4 → portacode-0.3.12.dev0}/docker-compose.yaml

@@ -1,4 +1,3 @@
-version: "3.9"
 services:
   db:
     image: postgres:15
@@ -10,6 +9,11 @@ services:
       - pgdata:/var/lib/postgresql/data
     ports:
       - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U portacode -d portacode"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
 
   django:
     build:
@@ -17,11 +21,12 @@ services:
       dockerfile: Dockerfile
     container_name: portacode-django
     restart: unless-stopped
-    command: ["bash", "-c", "python manage.py collectstatic --noinput && daphne portacode_django.asgi:application -b 0.0.0.0 -p 8001"]
+    command: ["bash", "-c", "python manage.py migrate && python manage.py collectstatic --noinput && daphne portacode_django.asgi:application -b 0.0.0.0 -p 8001"]
     env_file:
       - main.env
     depends_on:
-      - db
+      db:
+        condition: service_healthy
     ports:
       - "8001:8001"
     volumes:
@@ -36,7 +41,10 @@ services:
     env_file:
       - main.env
     depends_on:
-      - db
+      db:
+        condition: service_healthy
+      redis:
+        condition: service_started
     ports:
       - "8000:8000"
     volumes:

{portacode-0.3.11.dev4 → portacode-0.3.12.dev0}/portacode/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.3.11.dev4'
-__version_tuple__ = version_tuple = (0, 3, 11, 'dev4')
+__version__ = version = '0.3.12.dev'
+__version_tuple__ = version_tuple = (0, 3, 12, 'dev0')

{portacode-0.3.11.dev4 → portacode-0.3.12.dev0}/portacode/connection/handlers/WEBSOCKET_PROTOCOL.md

@@ -2,26 +2,22 @@
 
 This document outlines the WebSocket communication protocol between the Portacode server and the connected client devices.
 
-## Protocol Architecture
-
-This protocol uses a **unified message structure** throughout the entire system. No message transformations occur between layers, ensuring consistency and eliminating complexity.
-
 ## Raw Message Format
 
-All communication over the WebSocket is managed by a [multiplexer](./multiplex.py) that wraps every message in a JSON object with a `device_channel` and a `payload`. This allows for multiple virtual communication channels over a single connection.
+All communication over the WebSocket is managed by a [multiplexer](./multiplex.py) that wraps every message in a JSON object with a `channel` and a `payload`. This allows for multiple virtual communication channels over a single connection.
 
 **Raw Message Structure:**
 
 ```json
 {
-  "device_channel": "<channel_id>",
+  "channel": "<channel_id>",
   "payload": {
     // This is where the Action or Event object goes
   }
 }
 ```
 
-*   `device_channel` (string|integer, mandatory): Identifies the virtual channel on the device side. When sending control commands to the device, they should be sent to channel 0. When the device responds to such control commands or sends system events, they will also be sent on channel 0. When a terminal session is created in the device, it is assigned a UUID, and that UUID becomes the device_channel for communicating to that specific terminal.
+*   `channel` (string|integer, mandatory): Identifies the virtual channel the message is for. When sending control commands to the device, they should be sent to channel 0 and when the device responsed to such control commands or sends system events, they will also be send on the zero channel. When a terminal session is created in the device, it is assigned a uuid, the uuid becomes the channel for communicating to that specific terminal.
 *   `payload` (object, mandatory): The content of the message, which will be either an [Action](#actions) or an [Event](#events) object.
 
 ---
@@ -39,23 +35,13 @@ Actions are messages sent from the server to the device, placed within the `payl
     "arg1": "value1",
     "...": "..."
   },
-  "client_channel": "<session_id>"
+  "reply_channel": "<channel_name>"
 }
 ```
 
 *   `command` (string, mandatory): The name of the action to be executed (e.g., `terminal_start`).
 *   `payload` (object, mandatory): An object containing the specific arguments for the action.
-*   `client_channel` (string, mandatory): A session identifier that the device will echo back in its response. This identifies which client session on the server side is communicating with the device. The device uses this to track active client sessions and ensure messages are only sent to connected clients. This works like a return address - the device_channel specifies which application on the device handles the message, while the client_channel specifies which client session should receive the response.
-
-### Session Management and Event Subscriptions
-
-**Client Session Tracking**: Devices maintain awareness of active client sessions through explicit session management commands. The server notifies devices when client sessions connect, disconnect, or change their event subscriptions.
-
-**Mandatory Client Channel**: All commands sent to devices MUST include a `client_channel` to enable proper session tracking and response routing.
-
-**Event Subscription System**: Client sessions can specify which events they want to receive through subscription management. This allows devices to filter events and reduce bandwidth usage by only sending relevant updates to interested clients.
-
----
+*   `reply_channel` (string, optional): A channel name that the device will echo back in its response. The difference between this field and the `channel` field handled in the device connection [multiplexer](./multiplex.py), is simply that `channel` defines which application in the device is handeling this communication, while `reply_channel` defines which client session on the server side is communicating with the device. That's why the [multiplexer](./multiplex.py) for `channel` is here, while the multiplexer for the `reply_channel` is on the other side of the conversation. A lot like the source port number and destination port number in TCP/IP.
 
 ### `terminal_start`
 
@@ -191,41 +177,6 @@ Deletes a file or directory. Handled by [`file_delete`](./file_handlers.py).
 *   On success, the device will respond with a [`file_delete_response`](#file_delete_response) event.
 *   On error, a generic [`error`](#error) event is sent.
 
-### `session_subscribe`
-
-Manages client session subscriptions and notifies the device about active sessions and their event interests. The device stores subscription filters for each active session and uses them to determine which sessions should receive each event.
-
-**Payload Fields:**
-
-*   `client_channel` (string, mandatory): The session identifier being managed.
-*   `action` (string, mandatory): The subscription action - "connect", "disconnect", or "update".
-*   `filters` (array, optional): Array of filter objects the client is interested in. Required for "connect" and "update" actions.
-
-**Filter Object Format:**
-Each filter is a flexible object that can match against any field in event payloads:
-*   **Field Matching**: Any field name with string value or "*" for wildcard
-*   **Pattern Matching**: String values support wildcards (e.g., "terminal_*")
-*   **Multiple Conditions**: All specified fields must match for filter to match
-
-**Example Filter Objects:**
-```json
-[
-  {"event": "terminal_data", "terminal_id": "uuid-123"},
-  {"event": "terminal_*", "project_id": "project-456"}, 
-  {"event": "system_info"},
-  {"event": "*", "project_id": "project-789"},
-  {"event": "file_*", "path": "/home/user/*"}
-]
-```
-
-**Processing Architecture:**
-The device maintains a subscription registry mapping each `client_channel` to its filter objects. When broadcasting events, the device evaluates each active session's filters against the event payload to determine which sessions should receive the event.
-
-**Responses:**
-
-*   On success, the device will respond with a [`session_subscribe_ack`](#session_subscribe_ack) event.
-*   On error, a generic [`error`](#error) event is sent.
-
 ---
 
 ## Events
@@ -238,35 +189,12 @@ Events are messages sent from the device to the server, placed within the `paylo
 {
   "event": "<event_name>",
   // Event-specific fields...
-  "client_channels": ["<session_id1>", "<session_id2>"]
+  "reply_channel": "<channel_name>"
 }
 ```
 
 *   `event` (string, mandatory): The name of the event being sent (e.g., `terminal_started`).
-*   <a name="client_channels"></a>`client_channels` (array, optional): List of client session identifiers that should receive this event. For direct responses to commands, this contains the single `client_channel` from the original request. For broadcast events, this contains all client sessions whose subscription filters matched the event. The server uses this to route the event to the correct client sessions.
-
-### Event Broadcasting and Session Awareness
-
-**Targeted Events**: Events that are direct responses to commands include the original `client_channel` in the `client_channels` array, ensuring they are routed only to the requesting session.
-
-**Broadcast Events**: Events that are not direct responses (such as spontaneous terminal exits or system notifications) are processed through subscription filtering. The device evaluates the event payload against each active session's filter objects to determine which sessions should receive the event.
-
-**Subscription Filtering Process**:
-1. Device generates an event with its payload fields
-2. For each active client session, device evaluates session's filter objects against event payload
-3. If any filter matches, the session's `client_channel` is added to the `client_channels` array
-4. Event is sent once with all matching `client_channels`, minimizing network traffic
-5. Server routes the single event to all specified client sessions
-
-**Filter Matching**: A filter matches an event if all specified fields in the filter have corresponding fields in the event payload with matching values (supporting wildcards like `terminal_*` or `*`).
-
-**Efficiency Benefits**:
-- **Single Event Transmission**: Each event is sent once from device to server, regardless of how many client sessions need it
-- **Flexible Filtering**: Clients can filter on any event field without protocol changes
-- **Minimal Bandwidth**: Only events with at least one interested client session are transmitted
-- **Simple Routing**: Server receives pre-filtered events with target client sessions already identified
-
----
+*   <a name="reply_channel"></a>`reply_channel` (string, optional): If the event is a direct response to an action that included a `reply_channel`, this field will contain the same value. This allows the server to correlate responses with their original requests.
 
 ### <a name="error"></a>`error`
 
@@ -276,16 +204,6 @@ A generic event sent when an error occurs during the execution of an action.
 
 *   `message` (string, mandatory): A description of the error that occurred.
 
-### <a name="session_subscribe_ack"></a>`session_subscribe_ack`
-
-Acknowledges the receipt and processing of a `session_subscribe` action. This confirms that the device has updated its session registry and subscription filters.
-
-**Event Fields:**
-
-*   `action` (string, mandatory): The subscription action that was processed ("connect", "disconnect", or "update").
-*   `active_sessions` (integer, mandatory): The total number of currently active client sessions.
-*   `filter_count` (integer, mandatory): The number of filter objects registered for the managed session (0 for disconnect action).
-
 ### <a name="terminal_started"></a>`terminal_started`
 
 Confirms that a new terminal session has been successfully started. Triggered by a `terminal_start` action. Handled by [`terminal_start`](./terminal_handlers.py).
@@ -293,7 +211,7 @@ Confirms that a new terminal session has been successfully started. Triggered by
 **Event Fields:**
 
 *   `terminal_id` (string, mandatory): The unique ID of the newly created terminal session.
-*   `device_channel` (string, mandatory): The device channel name for terminal I/O (same as terminal_id).
+*   `channel` (string, mandatory): The channel name for terminal I/O.
 *   `project_id` (string, optional): The project ID associated with the terminal.
 
 ### <a name="terminal_exit"></a>`terminal_exit`
@@ -410,14 +328,4 @@ Confirms that a file or directory has been deleted in response to a `file_delete
 
 *   `path` (string, mandatory): The path of the deleted file or directory.
 *   `deleted_type` (string, mandatory): The type of the deleted item ("file" or "directory").
-*   `success` (boolean, mandatory): Indicates whether the deletion was successful.
-
----
-
-## Future Enhancements
-
-### Bandwidth Management
-The protocol will support configurable rate limiting and bandwidth monitoring to prevent resource exhaustion and ensure fair usage across multiple client sessions. This will include per-session bandwidth quotas, throttling mechanisms, and automatic rate limiting enforcement.
-
-### Channel Traffic Isolation
-Different device channels (control, terminal sessions, file operations) will have separate traffic shaping to ensure high-priority control commands are not delayed by high-volume terminal output. This includes priority queuing and per-channel bandwidth allocation.
+*   `success` (boolean, mandatory): Indicates whether the deletion was successful.

{portacode-0.3.11.dev4 → portacode-0.3.12.dev0}/portacode/connection/handlers/base.py

@@ -40,58 +40,15 @@ class BaseHandler(ABC):
         """
         pass
     
-    def _normalize_field_names(self, message: Dict[str, Any]) -> Dict[str, Any]:
-        """Normalize field names for backward compatibility.
-        
-        Supports both old and new field names:
-        - 'cmd' -> 'command' 
-        - 'reply_channel' -> 'client_channel'
-        
-        Args:
-            message: Original message dict
-            
-        Returns:
-            Message dict with normalized field names
-        """
-        normalized = message.copy()
-        
-        # Support both 'cmd' and 'command' fields
-        if 'cmd' in normalized and 'command' not in normalized:
-            normalized['command'] = normalized['cmd']
-            logger.debug("Converted 'cmd' to 'command' for backward compatibility")
-        
-        # Support both 'reply_channel' and 'client_channel' fields  
-        if 'reply_channel' in normalized and 'client_channel' not in normalized:
-            normalized['client_channel'] = normalized['reply_channel']
-            logger.debug("Converted 'reply_channel' to 'client_channel' for backward compatibility")
-            
-        return normalized
-    
-    def _get_client_channels(self, client_channel: Optional[str] = None) -> Optional[list]:
-        """Convert single client_channel to client_channels array for responses.
-        
-        Args:
-            client_channel: Single client channel identifier
-            
-        Returns:
-            List with single client channel, or None if no channel provided
-        """
-        if client_channel:
-            return [client_channel]
-        return None
-
     async def send_response(self, payload: Dict[str, Any], reply_channel: Optional[str] = None) -> None:
         """Send a response back to the gateway.
         
         Args:
             payload: Response payload
-            reply_channel: Optional reply channel (supports both old and new names)
+            reply_channel: Optional reply channel
         """
-        # Support both reply_channel (old) and client_channel (new) parameter names
         if reply_channel:
-            # Add both formats for backward compatibility during transition
-            payload["reply_channel"] = reply_channel  # Old format
-            payload["client_channels"] = [reply_channel]  # New format
+            payload["reply_channel"] = reply_channel
         await self.control_channel.send(payload)
     
     async def send_error(self, message: str, reply_channel: Optional[str] = None) -> None:
@@ -99,13 +56,11 @@ class BaseHandler(ABC):
         
         Args:
             message: Error message
-            reply_channel: Optional reply channel (supports both old and new names)
+            reply_channel: Optional reply channel
         """
         payload = {"event": "error", "message": message}
         if reply_channel:
-            # Add both formats for backward compatibility during transition
-            payload["reply_channel"] = reply_channel  # Old format
-            payload["client_channels"] = [reply_channel]  # New format
+            payload["reply_channel"] = reply_channel
         await self.control_channel.send(payload)
 
 
@@ -126,14 +81,11 @@ class AsyncHandler(BaseHandler):
     
     async def handle(self, message: Dict[str, Any], reply_channel: Optional[str] = None) -> None:
         """Handle the command by executing it and sending the response."""
-        # Normalize field names for backward compatibility
-        normalized_message = self._normalize_field_names(message)
-        
         logger.info("handler: Processing command %s with reply_channel=%s", 
                    self.command_name, reply_channel)
         
         try:
-            response = await self.execute(normalized_message)
+            response = await self.execute(message)
             logger.info("handler: Command %s executed successfully", self.command_name)
             await self.send_response(response, reply_channel)
         except Exception as exc:
@@ -158,12 +110,9 @@ class SyncHandler(BaseHandler):
     
     async def handle(self, message: Dict[str, Any], reply_channel: Optional[str] = None) -> None:
         """Handle the command by executing it in an executor and sending the response."""
-        # Normalize field names for backward compatibility
-        normalized_message = self._normalize_field_names(message)
-        
         try:
             loop = asyncio.get_running_loop()
-            response = await loop.run_in_executor(None, self.execute, normalized_message)
+            response = await loop.run_in_executor(None, self.execute, message)
             await self.send_response(response, reply_channel)
         except Exception as exc:
             logger.exception("Error in sync handler %s: %s", self.command_name, exc)

{portacode-0.3.11.dev4 → portacode-0.3.12.dev0}/portacode/connection/terminal.py

@@ -16,6 +16,7 @@ in the handlers directory.
 import asyncio
 import json
 import logging
+import os
 from typing import Any, Dict, Optional, List
 
 from .multiplex import Multiplexer, Channel
@@ -32,8 +33,63 @@ from .handlers.session import SessionManager
 
 logger = logging.getLogger(__name__)
 
+class ClientSessionManager:
+    """Manages connected client sessions for the device."""
+    
+    def __init__(self):
+        self._client_sessions = {}
+        self._debug_file_path = os.path.join(os.getcwd(), "client_sessions.json")
+        logger.info("ClientSessionManager initialized")
+    
+    def update_sessions(self, sessions: List[Dict]) -> None:
+        """Update the client sessions with new data from server."""
+        self._client_sessions = {}
+        for session in sessions:
+            channel_name = session.get("channel_name")
+            if channel_name:
+                self._client_sessions[channel_name] = session
+        
+        logger.info(f"Updated client sessions: {len(self._client_sessions)} sessions")
+        self._write_debug_file()
+    
+    def get_sessions(self) -> Dict[str, Dict]:
+        """Get all current client sessions."""
+        return self._client_sessions.copy()
+    
+    def get_session_by_channel(self, channel_name: str) -> Optional[Dict]:
+        """Get a specific client session by channel name."""
+        return self._client_sessions.get(channel_name)
+    
+    def get_sessions_for_project(self, project_id: str) -> List[Dict]:
+        """Get all client sessions for a specific project."""
+        return [
+            session for session in self._client_sessions.values()
+            if session.get("project_id") == project_id
+        ]
+    
+    def get_sessions_for_user(self, user_id: int) -> List[Dict]:
+        """Get all client sessions for a specific user."""
+        return [
+            session for session in self._client_sessions.values()
+            if session.get("user_id") == user_id
+        ]
+    
+    def has_interested_clients(self) -> bool:
+        """Check if there are any connected clients interested in this device."""
+        return len(self._client_sessions) > 0
+    
+    def _write_debug_file(self) -> None:
+        """Write current client sessions to debug JSON file."""
+        try:
+            with open(self._debug_file_path, 'w') as f:
+                json.dump(list(self._client_sessions.values()), f, indent=2, default=str)
+            logger.debug(f"Updated client sessions debug file: {self._debug_file_path}")
+        except Exception as e:
+            logger.error(f"Failed to write client sessions debug file: {e}")
+
 __all__ = [
     "TerminalManager",
+    "ClientSessionManager",
 ]
 
 class TerminalManager:
@@ -44,6 +100,7 @@ class TerminalManager:
     def __init__(self, mux: Multiplexer):
         self.mux = mux
         self._session_manager = None  # Initialize as None first
+        self._client_session_manager = ClientSessionManager()  # Initialize client session manager
         self._set_mux(mux, is_initial=True)
 
     # ------------------------------------------------------------------
@@ -65,8 +122,8 @@ class TerminalManager:
             # Start async reattachment and reconciliation
             asyncio.create_task(self._handle_reconnection())
         else:
-            # No existing sessions, just send empty terminal list
-            asyncio.create_task(self._send_terminal_list())
+            # No existing sessions, send empty terminal list and request client sessions
+            asyncio.create_task(self._initial_connection_setup())
 
     def _set_mux(self, mux: Multiplexer, is_initial: bool = False) -> None:
         self.mux = mux
@@ -84,6 +141,7 @@ class TerminalManager:
         # Create context for handlers
         self._context = {
             "session_manager": self._session_manager,
+            "client_session_manager": self._client_session_manager,
             "mux": mux,
         }
         
@@ -144,6 +202,13 @@ class TerminalManager:
                 
                 logger.info("terminal_manager: Processing command '%s' with reply_channel=%s", cmd, reply_chan)
                 
+                # Handle client sessions update directly (special case)
+                if cmd == "client_sessions_update":
+                    sessions = message.get("sessions", [])
+                    self._client_session_manager.update_sessions(sessions)
+                    logger.info("terminal_manager: Updated client sessions (%d sessions)", len(sessions))
+                    continue
+                
                 # Dispatch command through registry
                 handled = await self._command_registry.dispatch(cmd, message, reply_chan)
                 if not handled:
@@ -206,6 +271,30 @@ class TerminalManager:
             await self._control_channel.send(payload)
         except Exception as exc:
             logger.warning("Failed to send terminal list: %s", exc)
+    
+    async def _request_client_sessions(self) -> None:
+        """Request current client sessions from server."""
+        try:
+            payload = {
+                "event": "request_client_sessions"
+            }
+            await self._control_channel.send(payload)
+            logger.info("Requested client sessions from server")
+        except Exception as exc:
+            logger.warning("Failed to request client sessions: %s", exc)
+
+    async def _initial_connection_setup(self) -> None:
+        """Handle initial connection setup sequence."""
+        try:
+            # Send empty terminal list
+            await self._send_terminal_list()
+            logger.info("Initial terminal list sent to server")
+            
+            # Request current client sessions
+            await self._request_client_sessions()
+            logger.info("Initial client session request sent")
+        except Exception as exc:
+            logger.error("Failed to handle initial connection setup: %s", exc)
 
     async def _handle_reconnection(self) -> None:
         """Handle the async reconnection sequence."""
@@ -217,5 +306,9 @@ class TerminalManager:
             # Then send updated terminal list to server
             await self._send_terminal_list()
             logger.info("Terminal list sent to server after reconnection")
+            
+            # Request current client sessions
+            await self._request_client_sessions()
+            logger.info("Client session request sent after reconnection")
         except Exception as exc:
             logger.error("Failed to handle reconnection: %s", exc) 

{portacode-0.3.11.dev4 → portacode-0.3.12.dev0}/portacode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: portacode
-Version: 0.3.11.dev4
+Version: 0.3.12.dev0
 Summary: Portacode CLI client and SDK
 Home-page: https://github.com/portacode/portacode
 Author: Meena Erian

{portacode-0.3.11.dev4 → portacode-0.3.12.dev0}/portacode.egg-info/SOURCES.txt

@@ -4,9 +4,12 @@ LICENSE
 MANIFEST.in
 Makefile
 README.md
+backup.sh
 docker-compose.yaml
 pyproject.toml
+restore.sh
 setup.py
+.claude/settings.local.json
 portacode/README.md
 portacode/__init__.py
 portacode/__main__.py

portacode-0.3.12.dev0/restore.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+# ─── CONFIG ────────────────────────────────────────────────────────────────
+BACKUP_DIR="${1:-$PWD/../backups}"
+VOLUME_NAME="portacode_pgdata"
+SERVICE="db"
+
+# ─── PICK A BACKUP ────────────────────────────────────────────────────────
+mapfile -t BACKUPS < <(
+  find "$BACKUP_DIR" -maxdepth 1 -type f -name "pgdata-*.tar.gz" \
+    -printf "%f\n" | sort -r
+)
+[ ${#BACKUPS[@]} -gt 0 ] || { echo "❌ No backups in $BACKUP_DIR"; exit 1; }
+
+echo "Available backups:"
+for i in "${!BACKUPS[@]}"; do
+  printf "  %2d) %s\n" $((i+1)) "${BACKUPS[i]}"
+done
+read -rp "Select backup [1-${#BACKUPS[@]}]: " SEL
+(( SEL>=1 && SEL<=${#BACKUPS[@]} )) || { echo "❌ Invalid choice."; exit 1; }
+FILE="${BACKUPS[$((SEL-1))]}"
+
+# ─── STOP & REMOVE OLD DB ─────────────────────────────────────────────────
+if docker-compose ps --status=running | grep -q "$SERVICE"; then
+  echo "🛑 Stopping & removing existing '$SERVICE' container..."
+  docker-compose stop "$SERVICE"
+  docker-compose rm -f "$SERVICE"
+fi
+
+# ─── DROP THE OLD VOLUME ───────────────────────────────────────────────────
+if docker volume inspect "$VOLUME_NAME" &>/dev/null; then
+  echo "🗑️  Removing old volume $VOLUME_NAME..."
+  docker volume rm "$VOLUME_NAME"
+fi
+
+# ─── HAVE COMPOSE CREATE THE BLANK VOLUME ─────────────────────────────────
+echo "➕ Letting Docker Compose create a fresh volume for '$SERVICE'..."
+# 'create' makes the container (and volume) without starting it
+docker-compose create "$SERVICE"
+
+# ─── RESTORE INTO THAT VOLUME ─────────────────────────────────────────────
+echo "📥 Restoring '$FILE' into volume '$VOLUME_NAME'..."
+docker run --rm \
+  -v "${VOLUME_NAME}":/data \
+  -v "$BACKUP_DIR":/backup \
+  alpine \
+  sh -c "cd /data && tar xzf /backup/${FILE}"
+
+# ─── START THE DB AGAIN ────────────────────────────────────────────────────
+echo "🚀 Starting '$SERVICE'..."
+docker-compose up -d "$SERVICE"
+
+echo "✅ Restore complete."