docker-stack 2.1.2__tar.gz → 2.2.0__tar.gz

{docker_stack-2.1.2 → docker_stack-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docker-stack
-Version: 2.1.2
+Version: 2.2.0
 Summary: CLI for deploying and managing Docker stacks.
 Home-page: https://github.com/mesudip/docker-stack
 Author: Sudip Bhattarai
@@ -84,7 +84,10 @@ Use this option when CI can connect directly to the target Docker daemon.
 
 #### 2. Docker-Manager
 
-Use the bundled action when deploying through Docker-Manager:
+Use the bundled action when deploying through
+[Docker-Manager](https://github.com/mesudip/docker-enterprise). The manager
+repository contains the server source, installation instructions, and deployment
+documentation.
 
 For a full compose deployment directly from CI, use the action to configure
 Docker-Manager authentication and then run the normal `docker-stack deploy`
@@ -162,11 +165,40 @@ Stack commands use the `default` namespace unless `-n/--namespace` is supplied.
 Listings print the selected namespace; `docker-stack ls -A` (or
 `--all-namespaces`) lists every visible namespace.
 
-The prompt displays `(docker:office)`, keeps the selected manager context active,
+The prompt displays `(docker:office@cluster)`, keeps the selected manager context active,
 and refreshes authentication when needed. The session supports `docker` and
 `docker compose`; legacy `docker-compose` is not supported. If authentication
 expires, run `docker-stack login` again.
 
+Container listing is cluster-aware and includes the owning Swarm node. Select a
+node when working with daemon-local resources such as volumes and images:
+
+```bash
+docker ps
+docker-stack node current
+docker-stack node use worker-02
+docker volume ls
+docker image ls
+docker-stack node use cluster
+```
+
+Node selection is stored only in the managed shell's isolated Docker
+configuration and appears in the prompt as `(docker:office@worker-02)`.
+Selected-node requests remain subject to the manager's Docker permissions;
+image management is root-only because the manager does not define delegated
+image permissions.
+
+Cluster-aware output is enabled after the manager has observed compatible
+agents on every discovered node. The manager remembers that capability until it
+restarts, so a temporary agent outage does not make the CLI revert to a legacy
+feature decision. A partial cluster listing prints the available containers,
+reports each failed node on stderr with its incident id, and exits non-zero.
+
+`docker ps --quiet` and `docker ps --format ...` use Docker's native formatter
+and therefore do not add the `NODE` column. Explicit Docker overrides such as
+`--context`, `--host`/`-H`, and `--config` bypass managed cluster formatting and
+are sent unchanged to the Docker CLI.
+
 ## Core Capabilities
 
 -   **Advanced Deployments on Plain Docker Daemons:**

{docker_stack-2.1.2 → docker_stack-2.2.0}/README.md

@@ -58,7 +58,10 @@ Use this option when CI can connect directly to the target Docker daemon.
 
 #### 2. Docker-Manager
 
-Use the bundled action when deploying through Docker-Manager:
+Use the bundled action when deploying through
+[Docker-Manager](https://github.com/mesudip/docker-enterprise). The manager
+repository contains the server source, installation instructions, and deployment
+documentation.
 
 For a full compose deployment directly from CI, use the action to configure
 Docker-Manager authentication and then run the normal `docker-stack deploy`
@@ -136,11 +139,40 @@ Stack commands use the `default` namespace unless `-n/--namespace` is supplied.
 Listings print the selected namespace; `docker-stack ls -A` (or
 `--all-namespaces`) lists every visible namespace.
 
-The prompt displays `(docker:office)`, keeps the selected manager context active,
+The prompt displays `(docker:office@cluster)`, keeps the selected manager context active,
 and refreshes authentication when needed. The session supports `docker` and
 `docker compose`; legacy `docker-compose` is not supported. If authentication
 expires, run `docker-stack login` again.
 
+Container listing is cluster-aware and includes the owning Swarm node. Select a
+node when working with daemon-local resources such as volumes and images:
+
+```bash
+docker ps
+docker-stack node current
+docker-stack node use worker-02
+docker volume ls
+docker image ls
+docker-stack node use cluster
+```
+
+Node selection is stored only in the managed shell's isolated Docker
+configuration and appears in the prompt as `(docker:office@worker-02)`.
+Selected-node requests remain subject to the manager's Docker permissions;
+image management is root-only because the manager does not define delegated
+image permissions.
+
+Cluster-aware output is enabled after the manager has observed compatible
+agents on every discovered node. The manager remembers that capability until it
+restarts, so a temporary agent outage does not make the CLI revert to a legacy
+feature decision. A partial cluster listing prints the available containers,
+reports each failed node on stderr with its incident id, and exits non-zero.
+
+`docker ps --quiet` and `docker ps --format ...` use Docker's native formatter
+and therefore do not add the `NODE` column. Explicit Docker overrides such as
+`--context`, `--host`/`-H`, and `--config` bypass managed cluster formatting and
+are sent unchanged to the Docker CLI.
+
 ## Core Capabilities
 
 -   **Advanced Deployments on Plain Docker Daemons:**

{docker_stack-2.1.2 → docker_stack-2.2.0}/docker_stack/cli.py

@@ -12,6 +12,7 @@ from typing import Dict, List, Optional, Tuple
 import os
 import yaml
 import json
+import time
 from docker_stack.docker_objects import DockerConfig, DockerObjectManager, DockerSecret
 from docker_stack.helpers import CallbackCommand, Command, generate_secret, run_cli_command
 from docker_stack.login import (
@@ -28,6 +29,7 @@ from docker_stack.login import (
 )
 from docker_stack.shell_auth import (
     SHELL_CONTEXT_ENV,
+    SHELL_NODE_STATE_ENV,
     ShellAuthError,
     ensure_shell_access,
     login_for_active_shell,
@@ -35,6 +37,7 @@ from docker_stack.shell_auth import (
     shell_session_active,
 )
 from docker_stack.manager_api import (
+    FEATURE_CLUSTER_CONTAINER_CLI,
     FEATURE_STACK_DEPLOY,
     FEATURE_STACK_QUERY,
     ManagerApiClient,
@@ -51,6 +54,232 @@ DOCKER_SHELL_ENDPOINT_ENV_VARS = (
     "DOCKER_MACHINE_NAME",
 )
 DEFAULT_NAMESPACE = "default"
+NODE_HEADER = "X-Docker-Manager-Node"
+
+
+def _active_docker_config_path() -> Path:
+    if not shell_session_active():
+        raise RuntimeError("node selection is available only inside docker-stack shell")
+    config_root = os.getenv("DOCKER_CONFIG", "").strip()
+    if not config_root:
+        raise RuntimeError("managed shell Docker configuration is unavailable")
+    return Path(config_root) / "config.json"
+
+
+def _read_selected_node() -> str:
+    config_path = _active_docker_config_path()
+    try:
+        payload = json.loads(config_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise RuntimeError(f"failed reading managed Docker configuration: {exc}") from exc
+    headers = payload.get("HttpHeaders")
+    value = headers.get(NODE_HEADER) if isinstance(headers, dict) else None
+    return str(value).strip() if value else "cluster"
+
+
+def _write_selected_node(value: Optional[str], display_name: str) -> None:
+    config_path = _active_docker_config_path()
+    try:
+        payload = json.loads(config_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise RuntimeError(f"failed reading managed Docker configuration: {exc}") from exc
+    headers = payload.get("HttpHeaders")
+    headers = dict(headers) if isinstance(headers, dict) else {}
+    if value:
+        headers[NODE_HEADER] = value
+    else:
+        headers.pop(NODE_HEADER, None)
+    if headers:
+        payload["HttpHeaders"] = headers
+    else:
+        payload.pop("HttpHeaders", None)
+    temporary = config_path.with_suffix(".tmp")
+    temporary.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    os.chmod(temporary, 0o600)
+    os.replace(temporary, config_path)
+    node_state = os.getenv(SHELL_NODE_STATE_ENV, "").strip()
+    if node_state:
+        Path(node_state).write_text(f"{display_name}\n", encoding="utf-8")
+
+
+def _manager_with_cluster_cli() -> ManagerApiClient:
+    client = discover_manager_client()
+    if client is None or not client.supports(FEATURE_CLUSTER_CONTAINER_CLI):
+        raise RuntimeError("Docker-Manager does not support cluster container CLI; upgrade the manager and all node agents")
+    return client
+
+
+def _select_node(value: str) -> str:
+    client = _manager_with_cluster_cli()
+    requested = value.strip()
+    if requested.lower() == "cluster":
+        _write_selected_node(None, "cluster")
+        return "cluster"
+    nodes = client.list_nodes().get("nodes", [])
+    exact = [node for node in nodes if str(node.get("id") or "") == requested]
+    candidates = exact or [
+        node
+        for node in nodes
+        if str(node.get("id") or "").startswith(requested)
+        or str(node.get("hostname") or "") == requested
+    ]
+    if not candidates:
+        raise RuntimeError(f"node '{requested}' is not visible or does not exist")
+    if len(candidates) != 1:
+        names = ", ".join(str(node.get("hostname") or node.get("id")) for node in candidates)
+        raise RuntimeError(f"node '{requested}' is ambiguous: {names}")
+    node = candidates[0]
+    if str(node.get("state") or "").lower() != "ready":
+        raise RuntimeError(f"node '{requested}' is not ready")
+    node_id = str(node.get("id") or "").strip()
+    hostname = str(node.get("hostname") or node_id).strip()
+    _write_selected_node(node_id, hostname)
+    return hostname
+
+
+def _human_age(timestamp: object) -> str:
+    try:
+        seconds = max(0, int(time.time()) - int(timestamp))
+    except (TypeError, ValueError):
+        return "-"
+    if seconds < 60:
+        return f"{seconds} seconds ago"
+    if seconds < 3600:
+        return f"{seconds // 60} minutes ago"
+    if seconds < 86400:
+        return f"{seconds // 3600} hours ago"
+    return f"{seconds // 86400} days ago"
+
+
+def _format_ports(ports: object) -> str:
+    if not isinstance(ports, list):
+        return ""
+    values = []
+    for port in ports:
+        if not isinstance(port, dict):
+            continue
+        private = port.get("PrivatePort")
+        protocol = port.get("Type") or "tcp"
+        public = port.get("PublicPort")
+        address = port.get("IP") or "0.0.0.0"
+        values.append(f"{address}:{public}->{private}/{protocol}" if public is not None else f"{private}/{protocol}")
+    return ", ".join(values)
+
+
+def _print_cluster_containers(payload: Dict[str, object], *, no_trunc: bool = False, show_size: bool = False) -> int:
+    rows = []
+    for entry in payload.get("containers", []):
+        if not isinstance(entry, dict) or not isinstance(entry.get("docker"), dict):
+            continue
+        item = entry["docker"]
+        container_id = str(item.get("Id") or "-")
+        names = item.get("Names") if isinstance(item.get("Names"), list) else []
+        row = {
+            "CONTAINER ID": container_id if no_trunc else container_id[:12],
+            "IMAGE": str(item.get("Image") or "-"),
+            "COMMAND": str(item.get("Command") or "-"),
+            "CREATED": _human_age(item.get("Created")),
+            "STATUS": str(item.get("Status") or item.get("State") or "-"),
+            "PORTS": _format_ports(item.get("Ports")),
+            "NAMES": ",".join(str(name).lstrip("/") for name in names) or "-",
+            "NODE": str(entry.get("node_name") or entry.get("node_id") or "-"),
+        }
+        if show_size:
+            row["SIZE"] = str(item.get("SizeRw") if item.get("SizeRw") is not None else "-")
+        rows.append(row)
+    columns = ["CONTAINER ID", "IMAGE", "COMMAND", "CREATED", "STATUS", "PORTS", "NAMES"]
+    if show_size:
+        columns.append("SIZE")
+    columns.append("NODE")
+    widths = {column: max(len(column), max((len(row[column]) for row in rows), default=0)) for column in columns}
+    print("   ".join(column.ljust(widths[column]) for column in columns))
+    for row in rows:
+        print("   ".join(row[column].ljust(widths[column]) for column in columns))
+    errors = payload.get("node_errors") if isinstance(payload.get("node_errors"), list) else []
+    for error in errors:
+        if isinstance(error, dict):
+            print(
+                f"docker ps: node {error.get('node_name') or error.get('node_id')}: {error.get('message')} "
+                f"(incident: {error.get('incident_id')})",
+                file=sys.stderr,
+            )
+    return 1 if errors else 0
+
+
+def _managed_docker(arguments: List[str]) -> int:
+    values = list(arguments)
+    if values and values[0] == "--":
+        values.pop(0)
+    command_index = 0
+    while command_index < len(values) and values[command_index].startswith("-"):
+        option = values[command_index]
+        if option in {"--config", "--context", "--host", "-H", "--log-level"}:
+            command_index += 2
+        else:
+            command_index += 1
+    command = values[command_index:]
+    global_options = values[:command_index]
+    explicit_target = any(
+        value in {"--config", "--context", "-c", "--host", "-H"}
+        or value.startswith(("--config=", "--context=", "--host=", "-H="))
+        or (value.startswith("-H") and value != "-H")
+        or (value.startswith("-c") and value != "-c")
+        for value in global_options
+    )
+    is_ps = bool(command) and (
+        command[0] == "ps"
+        or (len(command) >= 2 and command[0] == "container" and command[1] in {"ls", "list"})
+    )
+    if explicit_target or not is_ps or any(
+        value in {"-q", "--quiet", "--format"} or value.startswith("--format=")
+        for value in command
+    ):
+        return subprocess.run(["docker", *values], check=False).returncode
+    try:
+        client = discover_manager_client()
+        if client is None or not client.supports(FEATURE_CLUSTER_CONTAINER_CLI):
+            return subprocess.run(["docker", *values], check=False).returncode
+        filters = []
+        all_containers = False
+        latest = False
+        limit = None
+        no_trunc = False
+        show_size = False
+        index = 1 if command[0] == "ps" else 2
+        while index < len(command):
+            value = command[index]
+            if value in {"-a", "--all"}:
+                all_containers = True
+            elif value in {"-l", "--latest"}:
+                latest = True
+            elif value == "--no-trunc":
+                no_trunc = True
+            elif value in {"-s", "--size"}:
+                show_size = True
+            elif value in {"-f", "--filter"} and index + 1 < len(command):
+                index += 1
+                filters.append(command[index])
+            elif value.startswith("--filter="):
+                filters.append(value.split("=", 1)[1])
+            elif value in {"-n", "--last"} and index + 1 < len(command):
+                index += 1
+                limit = int(command[index])
+            elif value.startswith("--last="):
+                limit = int(value.split("=", 1)[1])
+            else:
+                return subprocess.run(["docker", *values], check=False).returncode
+            index += 1
+        payload = client.list_containers(
+            all_containers=all_containers,
+            filters=filters,
+            limit=limit,
+            latest=latest,
+            size=show_size,
+        )
+        return _print_cluster_containers(payload, no_trunc=no_trunc, show_size=show_size)
+    except (RuntimeError, ValueError) as exc:
+        print(f"docker ps: {exc}", file=sys.stderr)
+        return 2
 
 
 def physical_stack_name(namespace: str, stack: str) -> str:
@@ -1519,6 +1748,9 @@ def main(args: List[str] = None):
     shell_auth_parser = subparsers.add_parser("shell-auth", help=argparse.SUPPRESS)
     shell_auth_parser.add_argument("operation", choices=("ensure", "status"), help=argparse.SUPPRESS)
 
+    docker_parser = subparsers.add_parser("docker", help=argparse.SUPPRESS)
+    docker_parser.add_argument("docker_args", nargs=argparse.REMAINDER, help=argparse.SUPPRESS)
+
     # Build subcommand
     build_parser = subparsers.add_parser("build", help="Build images using docker-compose")
     build_parser.add_argument("compose_file", help="Path to the compose file")
@@ -1563,6 +1795,9 @@ def main(args: List[str] = None):
     node_parser = subparsers.add_parser("node", help="Inspect Docker Swarm nodes")
     node_subparsers = node_parser.add_subparsers(dest="node_command", required=True)
     node_subparsers.add_parser("ls", help="List Docker Swarm nodes and their labels")
+    node_subparsers.add_parser("current", help="Show the node selected in this managed shell")
+    node_use_parser = node_subparsers.add_parser("use", help="Select a node for node-local Docker commands")
+    node_use_parser.add_argument("node", help="Node id, id prefix, hostname, or 'cluster'")
 
     cat_parser = subparsers.add_parser(
         "cat", help="Print the docker compose of specific version. Defaults to latest version if not specified."
@@ -1611,6 +1846,9 @@ def main(args: List[str] = None):
             return 2
         return 0
 
+    if args.command == "docker":
+        return _managed_docker(args.docker_args)
+
     if args.command == "login":
         try:
             config = resolve_login_config(
@@ -1620,6 +1858,8 @@ def main(args: List[str] = None):
                 timeout_secs=args.timeout_secs,
             )
             current_shell_config = active_shell_config_dir(config.context_name)
+            if current_shell_config is None:
+                current_shell_config = getattr(config, "docker_config_dir", None)
             if shell_session_active():
                 result = login_for_active_shell(config)
                 config_dir = current_shell_config
@@ -1670,6 +1910,9 @@ def main(args: List[str] = None):
                     timeout_secs=args.timeout_secs,
                 )
                 persist_shell_context(config)
+            else:
+                if manager_target is not None:
+                    persist_shell_context(config)
             if shell_session_active() and os.getenv(SHELL_CONTEXT_ENV) == config.context_name:
                 print(f"docker-stack shell context={config.context_name} is already active")
                 return
@@ -1762,6 +2005,19 @@ def main(args: List[str] = None):
         elif args.command == "node":
             if args.node_command == "ls":
                 docker.node.ls()
+            elif args.node_command == "current":
+                try:
+                    print(_read_selected_node())
+                except RuntimeError as exc:
+                    print(f"docker-stack node current: {exc}", file=sys.stderr)
+                    return 2
+            elif args.node_command == "use":
+                try:
+                    selected = _select_node(args.node)
+                except RuntimeError as exc:
+                    print(f"docker-stack node use: {exc}", file=sys.stderr)
+                    return 2
+                print(f"Docker node selection: {selected}")
 
         elif args.command == "rm":
             docker.stack.rm(args.stack_name, namespace=args.namespace)

{docker_stack-2.1.2 → docker_stack-2.2.0}/docker_stack/login.py

@@ -25,6 +25,7 @@ class DockerManagerLoginConfig:
     context_name: str
     timeout_secs: int
     skip_tls_verify: bool = False
+    docker_config_dir: Optional[Path] = None
 
     @property
     def docker_context_host(self) -> str:
@@ -267,15 +268,23 @@ def resolve_login_config(
     current_context_name = None
     current_context_target = None
     inferred_context_name = None
+    resolved_docker_config_dir = None
     if not manager_url and not manager_target and not env_manager_value:
         current_context_name, current_context_target = current_docker_context_target()
 
     raw_manager_value = manager_url or manager_target or env_manager_value or current_context_target or "http://localhost:8080"
     if manager_target and "://" not in manager_target and ":" not in manager_target:
-        context_target = docker_context_target(manager_target)
+        isolated_config_dir = isolated_docker_config_dir(manager_target)
+        isolated_context_target = docker_context_target(
+            manager_target,
+            isolated_config_dir,
+        )
+        context_target = isolated_context_target or docker_context_target(manager_target)
         if context_target:
             raw_manager_value = context_target
             inferred_context_name = manager_target
+            if isolated_context_target:
+                resolved_docker_config_dir = isolated_config_dir
     if manager_target:
         resolved_manager_url, skip_tls_verify = detect_manager_url(raw_manager_value, verify_ssl=verify_ssl)
     elif manager_url:
@@ -302,6 +311,7 @@ def resolve_login_config(
         or "dm-proxy",
         timeout_secs=int(timeout_secs or os.getenv("DOCKER_MANAGER_LOGIN_TIMEOUT_SECS", "300")),
         skip_tls_verify=skip_tls_verify,
+        docker_config_dir=resolved_docker_config_dir,
     )
 
 

{docker_stack-2.1.2 → docker_stack-2.2.0}/docker_stack/manager_api.py

@@ -18,6 +18,7 @@ from docker_stack.shell_auth import ensure_shell_access
 FEATURE_MESUDIP_DOCKER_ENTERPRISE = "mesudip-docker-enterprise-v1"
 FEATURE_STACK_QUERY = "docker_stack_query_v1"
 FEATURE_STACK_DEPLOY = "docker_stack_deploy_v1"
+FEATURE_CLUSTER_CONTAINER_CLI = "cluster_container_cli_v1"
 DEFAULT_NAMESPACE = "default"
 
 
@@ -490,6 +491,7 @@ class ManagerApiClient:
 
             nodes.append(
                 {
+                    "id": str(item.get("ID") or ""),
                     "hostname": str(description.get("Hostname") or spec.get("Name") or item.get("ID") or "-"),
                     "role": role,
                     "manager_status": manager_status,
@@ -502,6 +504,39 @@ class ManagerApiClient:
 
         return {"nodes": nodes}
 
+    def list_containers(
+        self,
+        *,
+        all_containers: bool = False,
+        filters: Optional[list[str]] = None,
+        limit: Optional[int] = None,
+        latest: bool = False,
+        size: bool = False,
+    ) -> Dict[str, Any]:
+        docker_filters: Dict[str, list[str]] = {}
+        for raw_filter in filters or []:
+            key, separator, value = raw_filter.partition("=")
+            key = key.strip()
+            if not key or not separator:
+                raise RuntimeError(f"Invalid Docker filter: {raw_filter}")
+            docker_filters.setdefault(key, []).append(value)
+        params: Dict[str, Any] = {
+            "all": "1" if all_containers else "0",
+            "size": "1" if size else "0",
+        }
+        if docker_filters:
+            params["filters"] = json.dumps(docker_filters, separators=(",", ":"))
+        if limit is not None:
+            params["limit"] = str(limit)
+        if latest:
+            params["latest"] = "1"
+        payload = self._request_json(
+            f"/api/docker-stack/containers?{urllib.parse.urlencode(params)}"
+        )
+        if not isinstance(payload, dict) or not isinstance(payload.get("containers"), list):
+            raise RuntimeError("Docker-Manager containers response is invalid")
+        return payload
+
     def resolve_config(
         self,
         *,

{docker_stack-2.1.2 → docker_stack-2.2.0}/docker_stack/shell_auth.py

@@ -32,6 +32,7 @@ SHELL_SOCKET_ENV = "DOCKER_STACK_SHELL_SOCKET"
 SHELL_SECRET_ENV = "DOCKER_STACK_SHELL_SECRET"
 SHELL_CONTEXT_ENV = "DOCKER_STACK_SHELL_CONTEXT"
 SHELL_STATUS_ENV = "DOCKER_STACK_SHELL_STATUS"
+SHELL_NODE_STATE_ENV = "DOCKER_STACK_SHELL_NODE_STATE"
 SHELL_ORIGINAL_ZDOTDIR_ENV = "DOCKER_STACK_SHELL_ORIGINAL_ZDOTDIR"
 SHELL_AUTH_TIMEOUT_ENV = "DOCKER_STACK_SHELL_AUTH_TIMEOUT_SECS"
 
@@ -530,9 +531,11 @@ def _write_shell_wrappers(
     *,
     context_name: str,
     status_path: Path,
+    node_state_path: Optional[Path] = None,
 ) -> Dict[str, str]:
     context = _prompt_context(context_name)
     status_path_value = str(status_path)
+    node_state_path_value = str(node_state_path or status_path.with_name("node-selection"))
     no_color = bool(os.getenv("NO_COLOR"))
     bash_rc = session_dir / "bashrc"
     zsh_dir = session_dir / "zsh"
@@ -542,11 +545,18 @@ def _write_shell_wrappers(
         os.getenv(SHELL_ORIGINAL_ZDOTDIR_ENV) or os.getenv("ZDOTDIR", str(Path.home()))
     )
     original_zshrc = original_zshrc_root / ".zshrc"
+    original_zsh_history = original_zshrc_root / ".zsh_history"
     bash_rc.write_text(
         f'''[ -f {json.dumps(str(original_bashrc))} ] && source {json.dumps(str(original_bashrc))}
 __docker_stack_base_ps1="$PS1"
 __docker_stack_prompt_update() {{
-  local state expires now color reset
+  local state expires now color reset node
+  if [ -n "${{DOCKER_HOST:-}}" ]; then
+    color='\\[\\e[31m\\]'; reset='\\[\\e[0m\\]'
+    [ {str(no_color).lower()} = true ] && color= && reset=
+    PS1="${{color}}(docker:!DOCKER_HOST)${{reset}} ${{__docker_stack_base_ps1}}"
+    return
+  fi
   read -r state expires < {json.dumps(status_path_value)} 2>/dev/null || state=error
   now=$(date +%s)
   if [ "$state" = active ] && [ "${{expires:-0}}" -gt $((now + {REFRESH_WINDOW_SECS})) ]; then color='\\[\\e[32m\\]';
@@ -554,21 +564,35 @@ __docker_stack_prompt_update() {{
   else color='\\[\\e[31m\\]'; fi
   reset='\\[\\e[0m\\]'
   [ {str(no_color).lower()} = true ] && color= && reset=
-  PS1="${{color}}(docker:{context})${{reset}} ${{__docker_stack_base_ps1}}"
+  node=$(cat {json.dumps(node_state_path_value)} 2>/dev/null || printf cluster)
+  PS1="${{color}}(docker:{context}@${{node}})${{reset}} ${{__docker_stack_base_ps1}}"
 }}
 case ";${{PROMPT_COMMAND:-}};" in *';__docker_stack_prompt_update;'*) ;; *) PROMPT_COMMAND="__docker_stack_prompt_update${{PROMPT_COMMAND:+;$PROMPT_COMMAND}}";; esac
-docker() {{ docker-stack shell-auth ensure || return $?; command docker "$@"; }}
+docker() {{ docker-stack shell-auth ensure || return $?; docker-stack docker -- "$@"; }}
 ''',
         encoding="utf-8",
     )
     os.chmod(bash_rc, 0o600)
     zsh_rc = zsh_dir / ".zshrc"
     zsh_rc.write_text(
-        f'''[ -f {json.dumps(str(original_zshrc))} ] && source {json.dumps(str(original_zshrc))}
+        f'''typeset -g __docker_stack_session_zdotdir="$ZDOTDIR"
+typeset -g ZDOTDIR={json.dumps(str(original_zshrc_root))}
+typeset -g HISTFILE={json.dumps(str(original_zsh_history))}
+typeset -g SHELL_SESSION_HISTORY=0
+[ -f {json.dumps(str(original_zshrc))} ] && source {json.dumps(str(original_zshrc))}
+[[ -r "$HISTFILE" ]] && fc -R "$HISTFILE"
+typeset -g ZDOTDIR="$__docker_stack_session_zdotdir"
+unset __docker_stack_session_zdotdir
 autoload -Uz add-zsh-hook
 typeset -g __docker_stack_base_prompt="$PROMPT"
 __docker_stack_prompt_update() {{
-  local state expires now color reset
+  local state expires now color reset node
+  if [[ -n "${{DOCKER_HOST:-}}" ]]; then
+    color='%F{{red}}'; reset='%f'
+    [[ -n "${{NO_COLOR:-}}" ]] && color= && reset=
+    PROMPT="${{color}}(docker:!DOCKER_HOST)${{reset}} ${{__docker_stack_base_prompt}}"
+    return
+  fi
   read -r state expires < {json.dumps(status_path_value)} 2>/dev/null || state=error
   now=$(date +%s)
   if [[ "$state" = active && "${{expires:-0}}" -gt $((now + {REFRESH_WINDOW_SECS})) ]]; then color='%F{{green}}';
@@ -576,10 +600,11 @@ __docker_stack_prompt_update() {{
   else color='%F{{red}}'; fi
   reset='%f'
   [[ -n "${{NO_COLOR:-}}" ]] && color= && reset=
-  PROMPT="${{color}}(docker:{context})${{reset}} ${{__docker_stack_base_prompt}}"
+  node=$(cat {json.dumps(node_state_path_value)} 2>/dev/null || printf cluster)
+  PROMPT="${{color}}(docker:{context}@${{node}})${{reset}} ${{__docker_stack_base_prompt}}"
 }}
 add-zsh-hook precmd __docker_stack_prompt_update
-docker() {{ docker-stack shell-auth ensure || return $?; command docker "$@"; }}
+docker() {{ docker-stack shell-auth ensure || return $?; docker-stack docker -- "$@"; }}
 ''',
         encoding="utf-8",
     )
@@ -638,6 +663,9 @@ def run_managed_shell(config: DockerManagerLoginConfig, result: DockerManagerLog
         update_access_header(config_path, result.access_token)
         socket_path = session_dir / "auth.sock"
         status_path = session_dir / "status"
+        node_state_path = session_dir / "node-selection"
+        node_state_path.write_text("cluster\n", encoding="utf-8")
+        os.chmod(node_state_path, 0o600)
         shell_secret = os.urandom(32).hex()
         broker_env = dict(os.environ)
         for key in (SHELL_SOCKET_ENV, SHELL_SECRET_ENV, SHELL_CONTEXT_ENV, SHELL_STATUS_ENV):
@@ -689,12 +717,14 @@ def run_managed_shell(config: DockerManagerLoginConfig, result: DockerManagerLog
             shell,
             context_name=config.context_name,
             status_path=status_path,
+            node_state_path=node_state_path,
         )
         env = dict(os.environ)
         env[SHELL_SOCKET_ENV] = str(socket_path)
         env[SHELL_SECRET_ENV] = shell_secret
         env[SHELL_CONTEXT_ENV] = config.context_name
         env[SHELL_STATUS_ENV] = str(status_path)
+        env[SHELL_NODE_STATE_ENV] = str(node_state_path)
         env[SHELL_AUTH_TIMEOUT_ENV] = str(max(1, config.timeout_secs) + 5)
         env.update(wrapper_env)
         for key in ("DOCKER_HOST", "DOCKER_TLS_VERIFY", "DOCKER_CERT_PATH", "DOCKER_API_VERSION", "DOCKER_MACHINE_NAME"):

{docker_stack-2.1.2 → docker_stack-2.2.0}/docker_stack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docker-stack
-Version: 2.1.2
+Version: 2.2.0
 Summary: CLI for deploying and managing Docker stacks.
 Home-page: https://github.com/mesudip/docker-stack
 Author: Sudip Bhattarai
@@ -84,7 +84,10 @@ Use this option when CI can connect directly to the target Docker daemon.
 
 #### 2. Docker-Manager
 
-Use the bundled action when deploying through Docker-Manager:
+Use the bundled action when deploying through
+[Docker-Manager](https://github.com/mesudip/docker-enterprise). The manager
+repository contains the server source, installation instructions, and deployment
+documentation.
 
 For a full compose deployment directly from CI, use the action to configure
 Docker-Manager authentication and then run the normal `docker-stack deploy`
@@ -162,11 +165,40 @@ Stack commands use the `default` namespace unless `-n/--namespace` is supplied.
 Listings print the selected namespace; `docker-stack ls -A` (or
 `--all-namespaces`) lists every visible namespace.
 
-The prompt displays `(docker:office)`, keeps the selected manager context active,
+The prompt displays `(docker:office@cluster)`, keeps the selected manager context active,
 and refreshes authentication when needed. The session supports `docker` and
 `docker compose`; legacy `docker-compose` is not supported. If authentication
 expires, run `docker-stack login` again.
 
+Container listing is cluster-aware and includes the owning Swarm node. Select a
+node when working with daemon-local resources such as volumes and images:
+
+```bash
+docker ps
+docker-stack node current
+docker-stack node use worker-02
+docker volume ls
+docker image ls
+docker-stack node use cluster
+```
+
+Node selection is stored only in the managed shell's isolated Docker
+configuration and appears in the prompt as `(docker:office@worker-02)`.
+Selected-node requests remain subject to the manager's Docker permissions;
+image management is root-only because the manager does not define delegated
+image permissions.
+
+Cluster-aware output is enabled after the manager has observed compatible
+agents on every discovered node. The manager remembers that capability until it
+restarts, so a temporary agent outage does not make the CLI revert to a legacy
+feature decision. A partial cluster listing prints the available containers,
+reports each failed node on stderr with its incident id, and exits non-zero.
+
+`docker ps --quiet` and `docker ps --format ...` use Docker's native formatter
+and therefore do not add the `NODE` column. Explicit Docker overrides such as
+`--context`, `--host`/`-H`, and `--config` bypass managed cluster formatting and
+are sent unchanged to the Docker CLI.
+
 ## Core Capabilities
 
 -   **Advanced Deployments on Plain Docker Daemons:**

{docker_stack-2.1.2 → docker_stack-2.2.0}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="docker-stack",
-    version="2.1.2",
+    version="2.2.0",
     description="CLI for deploying and managing Docker stacks.",
     long_description=open("README.md").read(),  # You can include a README file to describe your package
     long_description_content_type="text/markdown",

{docker_stack-2.1.2 → docker_stack-2.2.0}/tests/test_docker_stack.py

@@ -8,7 +8,15 @@ from types import SimpleNamespace
 import pytest
 import yaml
 
-from docker_stack.cli import DOCKER_SHELL_ENDPOINT_ENV_VARS, Docker, active_shell_config_dir, open_context_shell
+from docker_stack.cli import (
+    DOCKER_SHELL_ENDPOINT_ENV_VARS,
+    Docker,
+    _managed_docker,
+    _read_selected_node,
+    _select_node,
+    active_shell_config_dir,
+    open_context_shell,
+)
 from docker_stack.helpers import Command
 from docker_stack.login import UnknownShellContextError
 from docker_stack import main
@@ -19,6 +27,134 @@ def decode_x_files(compose_content):
     return {item["path"]: base64.b64decode(item["content"]).decode("utf-8") for item in data.get("x-files", [])}
 
 
+def test_node_use_updates_only_managed_shell_config(monkeypatch, tmp_path):
+    config_path = tmp_path / "config.json"
+    config_path.write_text(json.dumps({"HttpHeaders": {"Authorization": "Bearer token"}}), encoding="utf-8")
+    node_state = tmp_path / "node-selection"
+    monkeypatch.setenv("DOCKER_STACK_SHELL_SOCKET", str(tmp_path / "auth.sock"))
+    monkeypatch.setenv("DOCKER_STACK_SHELL_SECRET", "secret")
+    monkeypatch.setenv("DOCKER_CONFIG", str(tmp_path))
+    monkeypatch.setenv("DOCKER_STACK_SHELL_NODE_STATE", str(node_state))
+    client = SimpleNamespace(
+        list_nodes=lambda: {
+            "nodes": [
+                {"id": "node-worker-123", "hostname": "worker-02", "state": "Ready"},
+            ]
+        }
+    )
+    monkeypatch.setattr("docker_stack.cli._manager_with_cluster_cli", lambda: client)
+
+    assert _select_node("worker-02") == "worker-02"
+    payload = json.loads(config_path.read_text(encoding="utf-8"))
+    assert payload["HttpHeaders"]["Authorization"] == "Bearer token"
+    assert payload["HttpHeaders"]["X-Docker-Manager-Node"] == "node-worker-123"
+    assert _read_selected_node() == "node-worker-123"
+    assert node_state.read_text(encoding="utf-8").strip() == "worker-02"
+
+    assert _select_node("cluster") == "cluster"
+    payload = json.loads(config_path.read_text(encoding="utf-8"))
+    assert "X-Docker-Manager-Node" not in payload["HttpHeaders"]
+
+
+def test_managed_docker_ps_renders_node_column(monkeypatch, capsys):
+    client = SimpleNamespace(
+        supports=lambda feature: feature == "cluster_container_cli_v1",
+        list_containers=lambda **_kwargs: {
+            "containers": [
+                {
+                    "node_id": "node-1",
+                    "node_name": "worker-02",
+                    "docker": {
+                        "Id": "abcdef1234567890",
+                        "Image": "nginx:1.27",
+                        "Command": "nginx",
+                        "Created": 1,
+                        "Status": "Up 1 hour",
+                        "Ports": [{"PrivatePort": 80, "Type": "tcp"}],
+                        "Names": ["/web.1.test"],
+                    },
+                }
+            ],
+            "node_errors": [],
+        }
+    )
+    monkeypatch.setattr("docker_stack.cli.discover_manager_client", lambda: client)
+
+    assert _managed_docker(["ps"]) == 0
+    output = capsys.readouterr().out
+    assert "CONTAINER ID" in output
+    assert "NODE" in output
+    assert "worker-02" in output
+    assert "abcdef123456" in output
+
+
+def test_managed_docker_ps_forwards_global_latest_and_limit(monkeypatch):
+    calls = []
+    client = SimpleNamespace(
+        supports=lambda feature: feature == "cluster_container_cli_v1",
+        list_containers=lambda **kwargs: calls.append(kwargs)
+        or {"containers": [], "node_errors": []},
+    )
+    monkeypatch.setattr("docker_stack.cli.discover_manager_client", lambda: client)
+
+    assert _managed_docker(["ps", "--latest"]) == 0
+    assert _managed_docker(["ps", "--last", "3"]) == 0
+
+    assert calls[0]["latest"] is True
+    assert calls[0]["limit"] is None
+    assert calls[1]["latest"] is False
+    assert calls[1]["limit"] == 3
+
+
+def test_managed_docker_delegates_format_to_real_docker(monkeypatch):
+    calls = []
+    monkeypatch.setattr(
+        "docker_stack.cli.subprocess.run",
+        lambda command, **_kwargs: calls.append(command) or SimpleNamespace(returncode=7),
+    )
+
+    assert _managed_docker(["ps", "--format", "{{.ID}}"]) == 7
+    assert calls == [["docker", "ps", "--format", "{{.ID}}"]]
+
+
+@pytest.mark.parametrize(
+    "arguments",
+    [
+        ["--context", "other", "ps"],
+        ["--context=other", "ps"],
+        ["-H", "tcp://other:2375", "ps"],
+        ["-H=tcp://other:2375", "ps"],
+        ["--config", "/tmp/other-docker-config", "ps"],
+    ],
+)
+def test_managed_docker_delegates_explicit_target_overrides(monkeypatch, arguments):
+    calls = []
+    monkeypatch.setattr(
+        "docker_stack.cli.subprocess.run",
+        lambda command, **_kwargs: calls.append(command) or SimpleNamespace(returncode=6),
+    )
+    monkeypatch.setattr(
+        "docker_stack.cli.discover_manager_client",
+        lambda: pytest.fail("explicit Docker targets must bypass managed cluster discovery"),
+    )
+
+    assert _managed_docker(arguments) == 6
+    assert calls == [["docker", *arguments]]
+
+
+def test_managed_docker_ps_delegates_when_manager_lacks_cluster_feature(monkeypatch):
+    calls = []
+    client = SimpleNamespace(supports=lambda _feature: False)
+    monkeypatch.setattr("docker_stack.cli.discover_manager_client", lambda: client)
+    monkeypatch.setattr(
+        "docker_stack.cli.subprocess.run",
+        lambda command, **_kwargs: calls.append(command) or SimpleNamespace(returncode=9),
+    )
+
+    assert _managed_docker(["ps"]) == 9
+    assert calls == [["docker", "ps"]]
+
+
 class RecordingManager:
     def __init__(self):
         self.calls = []
@@ -1023,6 +1159,37 @@ def test_login_prefers_existing_context_for_portless_target(monkeypatch, capsys)
     assert "DOCKER_CONTEXT=office" in output
 
 
+def test_login_named_context_reuses_persisted_isolated_config(monkeypatch, tmp_path, capsys):
+    (tmp_path / "config.json").write_text("{}\n", encoding="utf-8")
+    captured = {}
+    monkeypatch.setattr(
+        "docker_stack.cli.resolve_login_config",
+        lambda **_kwargs: SimpleNamespace(
+            manager_url="https://172.31.3.3:2376",
+            context_name="saas-a",
+            docker_context_host="tcp://172.31.3.3:2376",
+            skip_tls_verify=False,
+            docker_config_dir=tmp_path,
+        ),
+    )
+
+    def fake_ensure(config, docker_config_dir=None):
+        captured["context"] = config.context_name
+        captured["config_dir"] = docker_config_dir
+        return docker_config_dir, None
+
+    monkeypatch.setattr("docker_stack.cli.ensure_isolated_login", fake_ensure)
+    monkeypatch.setattr(
+        "docker_stack.cli.docker_manager_login",
+        lambda _config: pytest.fail("named persisted login must not use global Docker config"),
+    )
+
+    main(["login", "saas-a"])
+
+    assert captured == {"context": "saas-a", "config_dir": tmp_path}
+    assert f"DOCKER_CONFIG={tmp_path}" in capsys.readouterr().out
+
+
 def test_login_inside_shell_updates_existing_isolated_config(monkeypatch, tmp_path, capsys):
     captured = {}
 
@@ -1167,6 +1334,27 @@ def test_shell_unknown_context_prompts_for_manager_url_and_creates_it(monkeypatc
     assert "Creating Docker-Manager shell context 'prod1'" in output
 
 
+def test_shell_explicit_target_persists_context_before_opening(monkeypatch):
+    config = SimpleNamespace(
+        manager_url="https://172.31.3.3:2376",
+        context_name="saas-a",
+        docker_context_host="tcp://172.31.3.3:2376",
+        skip_tls_verify=False,
+        timeout_secs=30,
+    )
+    events = []
+    monkeypatch.setattr("docker_stack.cli.resolve_shell_login_config", lambda **_kwargs: config)
+    monkeypatch.setattr("docker_stack.cli.persist_shell_context", lambda value: events.append(("persist", value.context_name)))
+    monkeypatch.setattr("docker_stack.cli.browser_login", lambda _config: events.append(("login", "saas-a")) or SimpleNamespace(expires_at=None))
+    monkeypatch.setattr("docker_stack.cli.run_managed_shell", lambda _config, _result: 0)
+
+    with pytest.raises(SystemExit) as excinfo:
+        main(["shell", "--context", "saas-a", "https://172.31.3.3:2376"])
+
+    assert excinfo.value.code == 0
+    assert events[:2] == [("persist", "saas-a"), ("login", "saas-a")]
+
+
 def test_shell_inside_same_context_reports_already_active(monkeypatch, capsys):
     def fake_resolve_shell_login_config(**_kwargs):
         return SimpleNamespace(

{docker_stack-2.1.2 → docker_stack-2.2.0}/tests/test_login.py

@@ -384,6 +384,26 @@ def test_resolve_login_config_prefers_named_context_for_portless_target(monkeypa
     assert config.skip_tls_verify is True
 
 
+def test_resolve_login_config_prefers_isolated_named_context(monkeypatch, tmp_path):
+    monkeypatch.setattr("docker_stack.login.isolated_docker_config_dir", lambda _name: tmp_path)
+    monkeypatch.setattr(
+        "docker_stack.login.docker_context_target",
+        lambda context_name, docker_config_dir=None: (
+            "tcp://172.31.3.3:2376" if context_name == "saas-a" and docker_config_dir == tmp_path else None
+        ),
+    )
+    monkeypatch.setattr(
+        "docker_stack.login.detect_manager_url",
+        lambda value, verify_ssl=False: ("https://172.31.3.3:2376", False),
+    )
+
+    config = resolve_login_config(manager_target="saas-a")
+
+    assert config.manager_url == "https://172.31.3.3:2376"
+    assert config.context_name == "saas-a"
+    assert config.docker_config_dir == tmp_path
+
+
 def test_resolve_login_config_uses_current_context_target(monkeypatch):
     monkeypatch.setattr(
         "docker_stack.login.current_docker_context_target",

{docker_stack-2.1.2 → docker_stack-2.2.0}/tests/test_shell_auth.py

@@ -1,5 +1,6 @@
 import json
 import os
+import shutil
 import socket
 import subprocess
 import tempfile
@@ -289,8 +290,60 @@ def test_prompt_hooks_only_read_local_status_and_docker_wrapper_preflights(tmp_p
     wrapper = (tmp_path / "bashrc").read_text(encoding="utf-8")
     prompt_function = wrapper.split("__docker_stack_prompt_update() {", 1)[1].split("}", 1)[0]
     assert "shell-auth" not in prompt_function
-    assert "docker-stack shell-auth ensure || return $?; command docker \"$@\"" in wrapper
-    assert "(docker:office)" in wrapper
+    assert "docker-stack shell-auth ensure || return $?; docker-stack docker -- \"$@\"" in wrapper
+    assert "(docker:office@${node})" in wrapper
+    assert "(docker:!DOCKER_HOST)" in wrapper
+
+    zsh_wrapper = (tmp_path / "zsh" / ".zshrc").read_text(encoding="utf-8")
+    assert '[[ -n "${DOCKER_HOST:-}" ]]' in zsh_wrapper
+    assert "(docker:!DOCKER_HOST)" in zsh_wrapper
+    assert f"typeset -g HISTFILE={json.dumps(str(tmp_path / '.zsh_history'))}" in zsh_wrapper
+    assert '[[ -r "$HISTFILE" ]] && fc -R "$HISTFILE"' in zsh_wrapper
+
+
+def test_zsh_wrapper_loads_and_persists_original_history(tmp_path, monkeypatch):
+    zsh = shutil.which("zsh")
+    if zsh is None:
+        pytest.skip("zsh is not installed")
+
+    original_zdotdir = tmp_path / "original-zdotdir"
+    original_zdotdir.mkdir()
+    (original_zdotdir / ".zshrc").write_text(
+        "HISTSIZE=100\nSAVEHIST=100\nsetopt append_history\n",
+        encoding="utf-8",
+    )
+    history_path = original_zdotdir / ".zsh_history"
+    history_path.write_text(": 1:0;existing-managed-shell-history\n", encoding="utf-8")
+    status_path = tmp_path / "status"
+    status_path.write_text("active 9999999999\n", encoding="utf-8")
+
+    monkeypatch.setenv("ZDOTDIR", str(original_zdotdir))
+    wrapper_env = _write_shell_wrappers(
+        tmp_path,
+        zsh,
+        context_name="office",
+        status_path=status_path,
+    )
+    env = dict(os.environ)
+    env.update(wrapper_env)
+    env.pop("TERM_SESSION_ID", None)
+
+    result = subprocess.run(
+        [
+            zsh,
+            "-i",
+            "-c",
+            'fc -l 1; print -s "persisted-managed-shell-history"',
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+        env=env,
+    )
+
+    assert result.returncode == 0, result.stderr
+    assert "existing-managed-shell-history" in result.stdout
+    assert "persisted-managed-shell-history" in history_path.read_text(encoding="utf-8")
 
 
 def test_broker_stop_erases_in_memory_credentials_and_socket(tmp_path, monkeypatch):