docker-stack 2.1.2__py3-none-any.whl → 2.2.0__py3-none-any.whl

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/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/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/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.dist-info → docker_stack-2.2.0.dist-info}/METADATA

@@ -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.dist-info → docker_stack-2.2.0.dist-info}/RECORD

@@ -1,20 +1,20 @@
 docker_stack/__init__.py,sha256=qgHdW8ZDBlyk6FzIf8Mld_cJD1SjOfqo2dELg4pK668,880
-docker_stack/cli.py,sha256=i5Sk1JXlLaCn6OfPfBLpDlHXM3EiozicOKJfhiQEVf8,77672
+docker_stack/cli.py,sha256=yvBl8rI6GjpmgFyNBhP1shEDQUTTLjRJI2uzo8Q6xdg,88496
 docker_stack/command_runner.py,sha256=mNaUAVKtrJbji_5ARVPLKhc92avqllNKrVQj1A6S0dA,1252
 docker_stack/compose.py,sha256=_fAVesjyW5ecid46sYYhcu02yF1vqknDSCFYflJPDOE,534
 docker_stack/docker_objects.py,sha256=U6szytv5gKrmBYKqThSeMMXdiJ2u4STIQLkeqQ-Fn4Q,12103
 docker_stack/envsubst.py,sha256=gdEUpsjWJeNbbahySk56vUdQh1nns85o3LbU6SUBo3I,8337
 docker_stack/envsubst_merge.py,sha256=TwOu8BducG0rWnSreJGwesNi-VghCetljcf-aWceE8M,4971
 docker_stack/helpers.py,sha256=nJHaIS1vtFyPYclXVl3-Qd-1h55jnSy1LwdATDrF4hk,5953
-docker_stack/login.py,sha256=0Ow89JUQcuD-n7YEKeKs9YG2UNXaDfm8iLxUmBZCLNo,33507
-docker_stack/manager_api.py,sha256=OQkbbnP9oXOyRObzNZppmxgEuzs7mI65OIaPD8N3FlI,26942
+docker_stack/login.py,sha256=SNHL2S3InQ7Qc3ITV1VySazix1f7H0OD7IvTPBTgF4Y,33977
+docker_stack/manager_api.py,sha256=xb8RwY4LEn1usg9qhG9AfiCvBJ2tpQawVMLRwF3vYHY,28361
 docker_stack/markers.py,sha256=gqStnr0tNWZ1kzqvREc2jVQVQrevheShgJtL5QzSx4g,2388
 docker_stack/merge_conf.py,sha256=Pmsabcgf3SDyaWvf2OLsBPodzEqsvOIjj9xzn_qWXH0,1917
 docker_stack/registry.py,sha256=sWC1J9JDIrcYyhei1POYCZHJ0xUCKC2pveisSHMgYsQ,9036
-docker_stack/shell_auth.py,sha256=waJgM4TdewzZw4XGQcWQzESRvC3xkT6p3NJFdpSuWao,31545
+docker_stack/shell_auth.py,sha256=em0_lo1qnLIB4KHYqn4vQvqwKe7HkV9NM_I0VQTDDQ4,33082
 docker_stack/url_parser.py,sha256=Sk8GQE0nEiwCkijp1OltP2AfgtKEmM2hybcH_rBhfiI,6824
-docker_stack-2.1.2.dist-info/METADATA,sha256=oXqlKiNG9dn2Q40oDxPFCkSfYPSUUBrn4aks_b7P_50,12381
-docker_stack-2.1.2.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
-docker_stack-2.1.2.dist-info/entry_points.txt,sha256=mpe2RwIguARsosXIUBQEN2pKU53URqZCh2S4ATwDFL4,55
-docker_stack-2.1.2.dist-info/top_level.txt,sha256=zT6TPL54cLrt9LO_MNkhEpGGOmsoe2HV6Na5Ohy3_2c,13
-docker_stack-2.1.2.dist-info/RECORD,,
+docker_stack-2.2.0.dist-info/METADATA,sha256=xxDwMGLFu2AitS8ZFn0nOAVdTG-Z5yLxlfdW70qMkbg,13821
+docker_stack-2.2.0.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
+docker_stack-2.2.0.dist-info/entry_points.txt,sha256=mpe2RwIguARsosXIUBQEN2pKU53URqZCh2S4ATwDFL4,55
+docker_stack-2.2.0.dist-info/top_level.txt,sha256=zT6TPL54cLrt9LO_MNkhEpGGOmsoe2HV6Na5Ohy3_2c,13
+docker_stack-2.2.0.dist-info/RECORD,,