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

docker_stack/cli.py

@@ -15,13 +15,24 @@ import json
 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 (
+    browser_login,
     ensure_isolated_login,
     format_expiry,
     login as docker_manager_login,
+    persist_shell_context,
     resolve_login_config,
     resolve_shell_login_config,
     setup_auth as docker_manager_setup_auth,
     switch_docker_context,
+    UnknownShellContextError,
+)
+from docker_stack.shell_auth import (
+    SHELL_CONTEXT_ENV,
+    ShellAuthError,
+    ensure_shell_access,
+    login_for_active_shell,
+    run_managed_shell,
+    shell_session_active,
 )
 from docker_stack.manager_api import (
     FEATURE_STACK_DEPLOY,
@@ -39,6 +50,55 @@ DOCKER_SHELL_ENDPOINT_ENV_VARS = (
     "DOCKER_API_VERSION",
     "DOCKER_MACHINE_NAME",
 )
+DEFAULT_NAMESPACE = "default"
+
+
+def physical_stack_name(namespace: str, stack: str) -> str:
+    return stack if namespace == DEFAULT_NAMESPACE else f"{namespace}--{stack}"
+
+
+def _namespace_default() -> str:
+    return os.getenv("DOCKER_STACK_NAMESPACE", DEFAULT_NAMESPACE).strip() or DEFAULT_NAMESPACE
+
+
+def _add_namespace_argument(parser: argparse.ArgumentParser, help_text: str = "Stack namespace") -> None:
+    parser.add_argument(
+        "-n",
+        "--namespace",
+        default=_namespace_default(),
+        help=f"{help_text} (default: %(default)s)",
+    )
+
+
+def _add_listing_namespace_arguments(parser: argparse.ArgumentParser) -> None:
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument(
+        "-n",
+        "--namespace",
+        default=_namespace_default(),
+        help="Stack namespace (default: %(default)s)",
+    )
+    group.add_argument(
+        "-A",
+        "--all-namespaces",
+        "-all-namespaces",
+        action="store_true",
+        help="List stacks across all namespaces",
+    )
+
+
+def _prompt_for_manager_target(context_name: str) -> str:
+    if not sys.stdin.isatty():
+        raise RuntimeError(
+            f"Unknown shell context '{context_name}'. Run "
+            f"'docker-stack shell --context {context_name} <manager-url>' to create it."
+        )
+    print(f"Docker context '{context_name}' does not exist yet.")
+    print("Enter the Docker-Manager URL to create it (for example https://manager.example.com:2376).")
+    target = input(f"Manager URL for {context_name}: ").strip()
+    if not target:
+        raise RuntimeError(f"Manager URL is required to create shell context '{context_name}'")
+    return target
 
 
 @dataclass
@@ -323,13 +383,36 @@ class DockerStack:
         content = ("\n".join(lines) + "\n").encode("utf-8")
         return {"path": ".env", "content": self._b64_content(content)}
 
+    def _prepare_manager_secret_sources(self, compose_data: dict, base_dir: Path) -> None:
+        secrets = compose_data.get("secrets", {})
+        if not isinstance(secrets, dict):
+            return
+        for name, details in secrets.items():
+            if not isinstance(details, dict):
+                continue
+            if "x-template-file" in details:
+                filename = base_dir / details["x-template-file"]
+                details["x-content"] = envsubst_load_file(str(filename), os.environ)
+                details.pop("x-template-file", None)
+            elif "file" in details:
+                filename = base_dir / details["file"]
+                details["x-content"] = filename.read_text(encoding="utf-8")
+                details.pop("file", None)
+            elif "environment" in details:
+                env_name = str(details["environment"]).strip()
+                env_value = os.environ.get(env_name)
+                if env_value in (None, ""):
+                    raise ValueError(f"Secret {name} references environment variable {env_name}, but it is not set.")
+                details["x-content"] = env_value
+                details.pop("environment", None)
+
     def _collect_config_source_files(self, compose_data: dict, base_dir: Path) -> Tuple[List[Dict[str, str]], List[str]]:
         x_files = []
         env_sources = []
+        seen_paths = set()
         configs = compose_data.get("configs", {})
         if not isinstance(configs, dict):
             return x_files, env_sources
-
         for details in configs.values():
             if not isinstance(details, dict):
                 continue
@@ -337,17 +420,26 @@ class DockerStack:
             if not source_path:
                 continue
             filename = (base_dir / source_path).resolve()
+            relative_path = self._relative_source_name(filename, base_dir)
             content = filename.read_bytes()
-            x_files.append(
-                {
-                    "path": self._relative_source_name(filename, base_dir),
-                    "content": self._b64_content(content),
-                }
-            )
+            if relative_path not in seen_paths:
+                x_files.append(
+                    {
+                        "path": relative_path,
+                        "content": self._b64_content(content),
+                    }
+                )
+                seen_paths.add(relative_path)
             env_sources.append(content.decode("utf-8", errors="ignore"))
         return x_files, env_sources
 
-    def rendered_compose_file(self, compose_file, stack=None, include_build=True) -> RenderedCompose:
+    def rendered_compose_file(
+        self,
+        compose_file,
+        stack=None,
+        include_build=True,
+        namespace: str = DEFAULT_NAMESPACE,
+    ) -> RenderedCompose:
         compose_path = Path(compose_file).resolve()
         template_bytes = compose_path.read_bytes()
         template_content = template_bytes.decode("utf-8")
@@ -357,6 +449,9 @@ class DockerStack:
         source_x_files: List[Dict[str, str]] = []
         env_sources = [template_content]
         secret_env_vars = self._secret_environment_vars(compose_data)
+        manager_deploy = self._manager_client_for_feature(FEATURE_STACK_DEPLOY) if stack else None
+        if manager_deploy:
+            self._prepare_manager_secret_sources(compose_data, base_dir)
         if stack:
             source_x_files, config_env_sources = self._collect_config_source_files(compose_data, base_dir)
             env_sources.extend(config_env_sources)
@@ -365,14 +460,27 @@ class DockerStack:
             for k, v in services.items():
                 if "build" in v:
                     del v["build"]
-        if stack:
+        # A manager-backed deploy must send portable source definitions to the
+        # stack API. The manager owns validation, config/secret versioning and
+        # materialization; resolving those objects here can mutate a dry-run and
+        # can pin a service to an old physical object name. Raw daemon deploys
+        # keep the legacy client-side materialization path.
+        if stack and not manager_deploy:
             if "configs" in compose_data:
                 compose_data["configs"] = self._process_x_content(
-                    compose_data["configs"], self.docker.config, base_dir=str(base_dir), stack=stack
+                    compose_data["configs"],
+                    self.docker.config,
+                    base_dir=str(base_dir),
+                    stack=stack,
+                    namespace=namespace,
                 )
             if "secrets" in compose_data:
                 compose_data["secrets"] = self._process_x_content(
-                    compose_data["secrets"], self.docker.secret, base_dir=str(base_dir), stack=stack
+                    compose_data["secrets"],
+                    self.docker.secret,
+                    base_dir=str(base_dir),
+                    stack=stack,
+                    namespace=namespace,
                 )
 
         # Define the replacements for '$' to '$$' for env variables in compose files
@@ -394,26 +502,38 @@ class DockerStack:
     def decode_yaml(self, data: str) -> dict:
         return yaml.safe_load(data)
 
-    def render_compose_file(self, compose_file, stack=None, include_build=True):
+    def render_compose_file(self, compose_file, stack=None, include_build=True, namespace: str = DEFAULT_NAMESPACE):
         """
         Render the Docker Compose file with environment variables and create Docker configs/secrets.
         """
-        return self.rendered_compose_file(compose_file, stack, include_build=include_build)
+        return self.rendered_compose_file(
+            compose_file,
+            stack,
+            include_build=include_build,
+            namespace=namespace,
+        )
 
-    def _process_x_content(self, objects, manager: DockerObjectManager, base_dir="", stack=None):
+    def _process_x_content(
+        self,
+        objects,
+        manager: DockerObjectManager,
+        base_dir="",
+        stack=None,
+        namespace: str = DEFAULT_NAMESPACE,
+    ):
         """
         Process configs or secrets with x-content keys.
         Returns a tuple: (processed_objects, commands)
         """
         processed_objects = {}
         manager_client = self._manager_client_for_feature(FEATURE_STACK_DEPLOY)
-        namespace = os.getenv("DOCKER_STACK_NAMESPACE", "default")
+        object_stack = physical_stack_name(namespace, stack) if stack else None
 
         def docker_object_name_for(name, explicit_name=None):
             if explicit_name:
                 return explicit_name
-            if stack:
-                return f"{stack}_{name}"
+            if object_stack:
+                return f"{object_stack}_{name}"
             return name
 
         def normalize_labels(labels):
@@ -457,7 +577,7 @@ class DockerStack:
                 processed_objects[name] = {"name": response["actual_name"], "external": True}
                 return
 
-            object_name, command = manager.create(docker_object_name, data, labels=labels, stack=stack)
+            object_name, command = manager.create(docker_object_name, data, labels=labels, stack=object_stack)
             if not command.isNop():
                 self.commands.append(command)
                 if is_generated_secret:
@@ -528,14 +648,29 @@ class DockerStack:
     def _manager_client_for_feature(self, feature_name: str) -> Optional[ManagerApiClient]:
         client = self.docker.manager_client()
         if not client:
+            if os.getenv("DOCKER_MANAGER_URL", "").strip():
+                raise RuntimeError(
+                    "Docker-Manager is configured via DOCKER_MANAGER_URL, but docker-stack could not initialize a manager client"
+                )
             return None
         try:
             if client.supports(feature_name):
                 return client
-        except RuntimeError:
+        except RuntimeError as exc:
+            if os.getenv("DOCKER_MANAGER_URL", "").strip():
+                raise RuntimeError(f"Docker-Manager feature detection failed for {feature_name}: {exc}") from exc
             return None
+        if os.getenv("DOCKER_MANAGER_URL", "").strip():
+            raise RuntimeError(
+                f"Docker-Manager is configured via DOCKER_MANAGER_URL, but /version did not advertise required feature {feature_name}"
+            )
         return None
 
+    @staticmethod
+    def _raise_if_manager_is_explicit(exc: RuntimeError) -> None:
+        if os.getenv("DOCKER_MANAGER_URL", "").strip():
+            raise exc
+
     @staticmethod
     def _normalize_version(value: str) -> str:
         if value.startswith("v") or value.startswith("V"):
@@ -546,16 +681,55 @@ class DockerStack:
     def _version_sort_key(raw: str):
         return int(raw) if raw.isdigit() else raw
 
-    def _print_stack_listing(self, stack_versions: Dict[str, List[str]]) -> None:
-        max_stack_name_length = max(len(stack) for stack in stack_versions) if stack_versions else 10
-        header_stack = "Stack Name".ljust(max_stack_name_length)
+    @staticmethod
+    def _compact_versions(versions: List[str]) -> str:
+        numeric = sorted({int(version.lstrip("vV")) for version in versions if version.lstrip("vV").isdigit()})
+        other = sorted({version for version in versions if not version.lstrip("vV").isdigit()})
+        compact = []
+        start = end = None
+
+        def append_range(first: int, last: int) -> None:
+            if last - first >= 2:
+                compact.append(f"v{first}...v{last}")
+            elif last == first:
+                compact.append(f"v{first}")
+            else:
+                compact.extend((f"v{first}", f"v{last}"))
 
-        print(f"{header_stack} | Versions")
-        print("-" * (max_stack_name_length + 12))
+        for version in numeric:
+            if start is None:
+                start = end = version
+            elif version == end + 1:
+                end = version
+            else:
+                append_range(start, end)
+                start = end = version
+        if start is not None:
+            append_range(start, end)
+        compact.extend(other)
+        return ", ".join(compact)
+
+    def _print_stack_listing(self, stack_versions: Dict[Tuple[str, str], List[str]], namespace: Optional[str]) -> None:
+        max_stack_name_length = max((len(stack) for _, stack in stack_versions), default=10)
+        header_stack = "Stack Name".ljust(max_stack_name_length)
 
-        for stack, versions in sorted(stack_versions.items()):
-            versions_str = ", ".join(sorted(versions, key=self._version_sort_key))
-            print(f"{stack.ljust(max_stack_name_length)} | {versions_str}")
+        if namespace is not None:
+            print(f"Namespace: {namespace}")
+            print(f"{header_stack} | Versions")
+            print("-" * (max_stack_name_length + 12))
+        else:
+            max_namespace_length = max((len(item_namespace) for item_namespace, _ in stack_versions), default=9)
+            header_namespace = "Namespace".ljust(max_namespace_length)
+            print("Namespace: all")
+            print(f"{header_namespace} | {header_stack} | Versions")
+            print("-" * (max_namespace_length + max_stack_name_length + 15))
+
+        for (item_namespace, stack), versions in sorted(stack_versions.items()):
+            versions_str = self._compact_versions(versions)
+            if namespace is None:
+                print(f"{item_namespace.ljust(max_namespace_length)} | {stack.ljust(max_stack_name_length)} | {versions_str}")
+            else:
+                print(f"{stack.ljust(max_stack_name_length)} | {versions_str}")
 
     def _print_versions(self, versions_list: List[Tuple[str, str]]) -> None:
         rows = [("Version", "Tag")] + versions_list
@@ -568,13 +742,13 @@ class DockerStack:
         for version, tag in sorted(versions_list, key=lambda x: self._version_sort_key(x[0])):
             print(f"{version.ljust(max_version_length)} | {tag.ljust(max_tag_length)}")
 
-    def ls(self):
+    def ls(self, namespace: Optional[str] = DEFAULT_NAMESPACE):
         client = self._manager_client_for_feature(FEATURE_STACK_QUERY)
         if client:
             try:
-                payload = client.list_stacks()
+                payload = client.list_stacks(namespace=namespace)
                 stack_versions = {
-                    str(item.get("stack")): [
+                    (str(item.get("namespace") or namespace or DEFAULT_NAMESPACE), str(item.get("stack"))): [
                         str(version)
                         for version in (
                             item.get("versions") if isinstance(item.get("versions"), list) else item.get("available_versions", [])
@@ -584,15 +758,17 @@ class DockerStack:
                     for item in payload.get("stacks", [])
                     if str(item.get("stack", "")).strip()
                 }
-                self._print_stack_listing(stack_versions)
+                self._print_stack_listing(stack_versions, namespace)
+                if namespace is not None:
+                    return {stack: versions for (_, stack), versions in stack_versions.items()}
                 return stack_versions
-            except RuntimeError:
-                pass
+            except RuntimeError as exc:
+                self._raise_if_manager_is_explicit(exc)
 
         cmd = ["docker", "config", "ls", "--format", "{{.ID}}\t{{.Name}}\t{{.Labels}}"]
         raw_output = run_cli_command(cmd, log=False)
         output = raw_output.split("\n") if raw_output else []
-        stack_versions: Dict[str, List[str]] = {}
+        stack_versions: Dict[Tuple[str, str], List[str]] = {}
 
         for line in output:
             parts = line.split("\t")
@@ -600,11 +776,14 @@ class DockerStack:
                 labels = {k: v for k, v in (label.split("=") for label in parts[2].split(",") if "=" in label)}
                 stack_name = labels.get("mesudip.stack.name")
                 version = labels.get("mesudip.object.version", "unknown")
+                object_namespace = labels.get("com.mesudip.namespace", DEFAULT_NAMESPACE)
 
-                if stack_name:
-                    stack_versions.setdefault(stack_name, []).append(version)
+                if stack_name and (namespace is None or object_namespace == namespace):
+                    stack_versions.setdefault((object_namespace, stack_name), []).append(version)
 
-        self._print_stack_listing(stack_versions)
+        self._print_stack_listing(stack_versions, namespace)
+        if namespace is not None:
+            return {stack: versions for (_, stack), versions in stack_versions.items()}
         return stack_versions
 
     def cat(self, name: str, version: str, namespace: str = "default"):
@@ -620,13 +799,14 @@ class DockerStack:
                 compose = payload.get("compose")
                 if isinstance(compose, str):
                     return compose
-            except RuntimeError:
-                pass
+            except RuntimeError as exc:
+                self._raise_if_manager_is_explicit(exc)
 
+        history_name = physical_stack_name(namespace, name)
         if normalized_version == "1":
-            config_name = f"{name}"
+            config_name = history_name
         else:
-            config_name = f"{name}_v{normalized_version}"
+            config_name = f"{history_name}_v{normalized_version}"
 
         cmd = ["docker", "config", "inspect", config_name]
         output = run_cli_command(cmd, log=False)
@@ -657,8 +837,8 @@ class DockerStack:
                 if print_output:
                     self._print_versions(versions_list)
                 return versions_list
-            except RuntimeError:
-                pass
+            except RuntimeError as exc:
+                self._raise_if_manager_is_explicit(exc)
 
         cmd = ["docker", "config", "ls", "--format", "{{.Name}}\t{{.Labels}}"]
         raw_output = run_cli_command(cmd, log=False)
@@ -672,8 +852,9 @@ class DockerStack:
                 stack = labels.get("mesudip.stack.name")
                 version = labels.get("mesudip.object.version", "unknown")
                 tag = labels.get("mesudip.stack.tag", "")
+                object_namespace = labels.get("com.mesudip.namespace", DEFAULT_NAMESPACE)
 
-                if stack == stack_name:
+                if stack == stack_name and object_namespace == namespace:
                     versions_list.append((version, tag))
 
         if print_output:
@@ -706,7 +887,8 @@ class DockerStack:
             if not rollback_version and tag:
                 try:
                     versions_payload = manager_query.list_stack_versions(stack_name, namespace=namespace) if manager_query else {}
-                except RuntimeError:
+                except RuntimeError as exc:
+                    self._raise_if_manager_is_explicit(exc)
                     versions_payload = {}
                 for item in versions_payload.get("versions", []):
                     if str(item.get("tag", "")) == tag:
@@ -743,7 +925,8 @@ class DockerStack:
                 resolved = payload.get("version")
                 if isinstance(resolved, str) and resolved.strip():
                     version = resolved
-            except RuntimeError:
+            except RuntimeError as exc:
+                self._raise_if_manager_is_explicit(exc)
                 compose_content = None
 
         if compose_content is None:
@@ -776,6 +959,9 @@ class DockerStack:
         tag=None,
         namespace: str = "default",
         dry_run: bool = False,
+        prune: bool = False,
+        resolve_image: Optional[str] = None,
+        force_update: bool = False,
     ):
         stored_content = stored_content if stored_content is not None else rendered_content
         labels = [
@@ -787,7 +973,19 @@ class DockerStack:
             labels.append(f"mesudip.stack.tag={tag}")
 
         manager_deploy = self._manager_client_for_feature(FEATURE_STACK_DEPLOY)
-        manager_options = {"with_registry_auth": with_registry_auth} if with_registry_auth else {}
+        if manager_deploy and tag:
+            raise RuntimeError(
+                "Docker-Manager stack deploy does not expose deployment tags; refusing to silently ignore --tag"
+            )
+        manager_options = {}
+        if with_registry_auth:
+            manager_options["with_registry_auth"] = True
+        if prune:
+            manager_options["prune"] = True
+        if resolve_image:
+            manager_options["resolve_image"] = resolve_image
+        if force_update:
+            manager_options["force_update"] = True
         if manager_deploy and dry_run:
             self._validate_via_manager(
                 manager_deploy,
@@ -816,13 +1014,26 @@ class DockerStack:
             )
             return
 
-        _, cmd = self.docker.config.increment(stack_name, stored_content, labels=labels, stack=stack_name)
+        if force_update:
+            raise RuntimeError("--force-update is supported only by the Docker-Manager stack deploy API")
+
+        physical_stack = physical_stack_name(namespace, stack_name)
+        _, cmd = self.docker.config.increment(
+            physical_stack,
+            stored_content,
+            labels=labels,
+            stack=physical_stack,
+        )
         if not cmd.isNop():
             self.commands.append(cmd)
 
-        cmd = ["docker", "stack", "deploy", "-c", "-", stack_name]
+        cmd = ["docker", "stack", "deploy", "-c", "-", physical_stack]
         if with_registry_auth:
             cmd.insert(3, "--with-registry-auth")
+        if prune:
+            cmd.insert(3, "--prune")
+        if resolve_image:
+            cmd[3:3] = ["--resolve-image", resolve_image]
         self.commands.append(Command(cmd, stdin=rendered_content, give_console=True))
 
     @staticmethod
@@ -859,12 +1070,32 @@ class DockerStack:
         rendered_content: str,
         options: Dict[str, object],
     ) -> Optional[str]:
-        payload = manager_client.deploy_stack(
-            stack=stack_name,
-            namespace=namespace,
-            compose=rendered_content,
-            options=options,
-        )
+        if not hasattr(manager_client, "deploy_stack_stream"):
+            payload = manager_client.deploy_stack(
+                stack=stack_name,
+                namespace=namespace,
+                compose=rendered_content,
+                options=options,
+            )
+        else:
+            try:
+                payload = manager_client.deploy_stack_stream(
+                    stack=stack_name,
+                    namespace=namespace,
+                    compose=rendered_content,
+                    options=options,
+                    on_event=DockerStack._print_manager_deploy_event,
+                )
+            except RuntimeError as exc:
+                message = str(exc)
+                if "POST /api/stacks/deploy/stream" not in message or "HTTP 404" not in message:
+                    raise
+                payload = manager_client.deploy_stack(
+                    stack=stack_name,
+                    namespace=namespace,
+                    compose=rendered_content,
+                    options=options,
+                )
         warnings = payload.get("warnings") or []
         for warning in warnings:
             print(f"[manager] {warning}")
@@ -874,8 +1105,51 @@ class DockerStack:
             print(stdout.rstrip())
         if isinstance(stderr, str) and stderr.strip():
             print(stderr.rstrip())
+        generated_secrets = payload.get("generated_secrets") or []
+        if generated_secrets:
+            print("\n----- Newly Generated Secrets -----")
+            for item in generated_secrets:
+                if not isinstance(item, dict):
+                    continue
+                logical_name = str(item.get("logical_name") or item.get("actual_name") or "secret")
+                value = item.get("value")
+                if value is not None:
+                    print(f"{logical_name}: {value}")
+            print("---------------------------------\n")
         return None
 
+    @staticmethod
+    def _print_manager_deploy_event(event: Dict[str, object]) -> None:
+        event_name = event.get("event")
+        data = event.get("data")
+        if not isinstance(data, dict):
+            data = {}
+        if event_name == "stdout":
+            line = str(data.get("line") or "").rstrip()
+            if line:
+                print(line, flush=True)
+        elif event_name == "stderr":
+            line = str(data.get("line") or "").rstrip()
+            if line:
+                print(line, file=sys.stderr, flush=True)
+        elif event_name == "command":
+            program = data.get("program") or "manager"
+            stack = data.get("stack")
+            suffix = f" {stack}" if stack else ""
+            print(f"[manager] {program}{suffix}", flush=True)
+        elif event_name == "resource":
+            kind = data.get("kind")
+            logical_name = data.get("logical_name")
+            actual_name = data.get("actual_name")
+            if kind and logical_name and actual_name:
+                print(f"[manager] {kind} {logical_name} -> {actual_name}", flush=True)
+        elif event_name == "service_progress":
+            service = data.get("service") or "service"
+            status = data.get("status") or "progress"
+            message = data.get("message") or data.get("error") or ""
+            if message:
+                print(f"[manager] {service}: {status}: {message}", flush=True)
+
     @staticmethod
     def _rollback_via_manager(
         manager_client: ManagerApiClient,
@@ -909,9 +1183,17 @@ class DockerStack:
         show_generated=True,
         namespace: str = "default",
         dry_run: bool = False,
+        prune: bool = False,
+        resolve_image: Optional[str] = None,
+        force_update: bool = False,
     ):
         self.generated_secrets = {}  # Reset for each deployment
-        rendered = self.render_compose_file(compose_file, stack=stack_name, include_build=False)
+        rendered = self.render_compose_file(
+            compose_file,
+            stack=stack_name,
+            include_build=False,
+            namespace=namespace,
+        )
         self._deploy(
             stack_name,
             rendered.clean,
@@ -920,6 +1202,9 @@ class DockerStack:
             tag=tag,
             namespace=namespace,
             dry_run=dry_run,
+            prune=prune,
+            resolve_image=resolve_image,
+            force_update=force_update,
         )
 
         if show_generated and self.generated_secrets:
@@ -937,8 +1222,22 @@ class DockerStack:
         if self.docker.secret:
             self.commands.extend(self.docker.secret.prune(keep=5))
 
-    def rm(self, stack_name):
-        self.commands.append(Command(["docker", "stack", "rm", stack_name], give_console=True))
+    def rm(self, stack_name, namespace: str = "default"):
+        manager = self._manager_client_for_feature(FEATURE_STACK_DEPLOY)
+        if manager:
+            self.commands.append(
+                CallbackCommand(
+                    f"docker-manager stack rm {stack_name}",
+                    lambda: manager.remove_stack(stack=stack_name, namespace=namespace),
+                )
+            )
+            return
+        self.commands.append(
+            Command(
+                ["docker", "stack", "rm", physical_stack_name(namespace, stack_name)],
+                give_console=True,
+            )
+        )
 
     def push(self, compose_file):
         compose_data = self.read_compose_file(compose_file)
@@ -1064,8 +1363,8 @@ class DockerNode:
                     )
                 DockerNode._print_rows(rows)
                 return rows
-            except RuntimeError:
-                pass
+            except RuntimeError as exc:
+                self.docker.stack._raise_if_manager_is_explicit(exc)
 
         nodes_output = run_cli_command(["docker", "node", "ls", "--format", "{{json .}}"], log=False)
         rows = []
@@ -1112,6 +1411,78 @@ def active_shell_config_dir(context_name: str) -> Optional[Path]:
     return Path(docker_config)
 
 
+GITHUB_WORKFLOW_RESTRICTED_MESSAGE = "github workflow tokens are restricted to stack APIs and service image updates"
+
+
+def _format_command(command) -> str:
+    if isinstance(command, (list, tuple)):
+        return " ".join(str(part) for part in command)
+    return str(command)
+
+
+def _error_output(exc: subprocess.CalledProcessError) -> str:
+    values = []
+    stdout = getattr(exc, "stdout", None) or getattr(exc, "output", None)
+    stderr = getattr(exc, "stderr", None)
+    if stdout:
+        values.append(str(stdout).strip())
+    if stderr:
+        values.append(str(stderr).strip())
+    return "\n".join(value for value in values if value)
+
+
+def _manager_deploy_suggestion(message: str) -> Optional[str]:
+    if GITHUB_WORKFLOW_RESTRICTED_MESSAGE in message:
+        return (
+            "Suggestion: this workflow is using a Docker-Manager GitHub token, but docker-stack fell back to a raw Docker CLI API. "
+            "Run the mesudip/docker-stack@v2 setup action before deploy, keep DOCKER_MANAGER_URL/DOCKER_CONTEXT from that step, "
+            "and make sure the manager /version endpoint advertises docker-stack deploy support."
+        )
+    lowered = message.lower()
+    if "github workflow" in lowered and ("trusted" in lowered or "not allowed" in lowered or "forbidden" in lowered):
+        return (
+            "Suggestion: configure a trusted workflow/deployment rule on Docker-Manager for this repository, workflow file, "
+            "stack, namespace, and service scope, then rerun the deploy."
+        )
+    if "external network" in lowered and "outside the stack scope" in lowered:
+        return (
+            "Suggestion: the compose file references an external Docker network that Docker-Manager does not consider owned "
+            "by this stack. Either allow that external network in the Docker-Manager deployment rule, attach the service to "
+            "a stack-owned network, or relabel/recreate the existing network with the expected stack ownership before deploying."
+        )
+    if "manager request failed" in lowered and "/version" in lowered:
+        return (
+            "Suggestion: check that the manager URL is reachable from the runner and that the setup action exported "
+            "DOCKER_MANAGER_URL and the matching Docker auth headers."
+        )
+    if "docker-manager is configured" in lowered and "did not advertise required feature" in lowered:
+        return (
+            "Suggestion: deploy the current Docker-Manager server code and verify GET /version returns MesudipFeatures "
+            "including mesudip-docker-enterprise-v1 or docker_stack_deploy_v1 for this manager endpoint."
+        )
+    return None
+
+
+def _format_called_process_error(exc: subprocess.CalledProcessError) -> str:
+    output = _error_output(exc)
+    lines = [f"docker-stack: command failed with exit code {exc.returncode}: {_format_command(exc.cmd)}"]
+    if output:
+        lines.append(output)
+    suggestion = _manager_deploy_suggestion(output)
+    if suggestion:
+        lines.extend(["", suggestion])
+    return "\n".join(lines)
+
+
+def _format_runtime_error(exc: RuntimeError) -> str:
+    message = str(exc).strip() or exc.__class__.__name__
+    lines = [f"docker-stack: {message}"]
+    suggestion = _manager_deploy_suggestion(message)
+    if suggestion:
+        lines.extend(["", suggestion])
+    return "\n".join(lines)
+
+
 def main(args: List[str] = None):
     parser = argparse.ArgumentParser(description="Deploy and manage Docker stacks.")
     subparsers = parser.add_subparsers(dest="command", required=True)
@@ -1122,7 +1493,7 @@ def main(args: List[str] = None):
     login_parser.add_argument("--context", "--context-name", dest="context_name", help="Docker context name to create or update")
     login_parser.add_argument("--timeout-secs", type=int, help="Login timeout in seconds")
 
-    shell_parser = subparsers.add_parser("shell", help="Open an isolated bash shell for a Docker-Manager context")
+    shell_parser = subparsers.add_parser("shell", help="Open an authenticated Bash/Zsh shell for a Docker-Manager context")
     shell_parser.add_argument("target", nargs="?", help="Context name, or manager host/URL when used with --context")
     shell_parser.add_argument("--context", "--context-name", dest="context_name", help="Shell context name to create or reuse")
     shell_parser.add_argument("--timeout-secs", type=int, help="Login timeout in seconds")
@@ -1145,6 +1516,9 @@ def main(args: List[str] = None):
     setup_auth_parser.add_argument("--github-oidc-token", help="GitHub OIDC token for trusted publishing")
     setup_auth_parser.add_argument("--verify-ssl", action="store_true", help=argparse.SUPPRESS)
 
+    shell_auth_parser = subparsers.add_parser("shell-auth", help=argparse.SUPPRESS)
+    shell_auth_parser.add_argument("operation", choices=("ensure", "status"), 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")
@@ -1159,19 +1533,32 @@ def main(args: List[str] = None):
     deploy_parser.add_argument("stack_name", help="Name of the stack")
     deploy_parser.add_argument("compose_file", help="Path to the compose file")
     deploy_parser.add_argument("--with-registry-auth", action="store_true", help="Use registry authentication")
-    deploy_parser.add_argument("--namespace", default=os.getenv("DOCKER_STACK_NAMESPACE", "default"), help="Deployment namespace")
+    deploy_parser.add_argument("--prune", action="store_true", help="Remove services no longer referenced by the compose file")
+    deploy_parser.add_argument(
+        "--resolve-image",
+        choices=("always", "changed", "never"),
+        help="Control image digest resolution during deploy",
+    )
+    deploy_parser.add_argument(
+        "--force-update",
+        action="store_true",
+        help="Force service task updates (Docker-Manager deploys only)",
+    )
+    _add_namespace_argument(deploy_parser, "Deployment namespace")
     deploy_parser.add_argument("-t", "--tag", help="Tag the current deployment for later checkout", required=False)
     deploy_parser.add_argument("--show-generated", action="store_true", default=True, help="Show newly generated secrets after deployment")
 
     # Remove subcommand
     rm_parser = subparsers.add_parser("rm", help="Remove a deployed stack")
     rm_parser.add_argument("stack_name", help="Name of the stack")
+    _add_namespace_argument(rm_parser)
 
     # Prune command
     subparsers.add_parser("prune", help="Remove old versions of configs and secrets")
 
     # Ls command
-    subparsers.add_parser("ls", help="List docker-stacks")
+    ls_parser = subparsers.add_parser("ls", help="List docker-stacks")
+    _add_listing_namespace_arguments(ls_parser)
 
     node_parser = subparsers.add_parser("node", help="Inspect Docker Swarm nodes")
     node_subparsers = node_parser.add_subparsers(dest="node_command", required=True)
@@ -1182,12 +1569,12 @@ def main(args: List[str] = None):
     )
     cat_parser.add_argument("stack_name", help="Name of the stack")
     cat_parser.add_argument("version", nargs="?", help="Stack version to cat. Defaults to latest if omitted.")
-    cat_parser.add_argument("--namespace", default=os.getenv("DOCKER_STACK_NAMESPACE", "default"), help="Stack namespace")
+    _add_namespace_argument(cat_parser)
 
     checkout_parser = subparsers.add_parser("checkout", help="Deploy specific version of the stack")
     checkout_parser.add_argument("stack_name", help="Name of the stack")
     checkout_parser.add_argument("version", help="Stack version to cat")
-    checkout_parser.add_argument("--namespace", default=os.getenv("DOCKER_STACK_NAMESPACE", "default"), help="Stack namespace")
+    _add_namespace_argument(checkout_parser)
 
     # version_parser = subparsers.add_parser("version",help="Deploy specific version of the stack")
     # version_parser.add_argument("stack_name", help="Name of the stack")
@@ -1195,7 +1582,7 @@ def main(args: List[str] = None):
 
     version_parser = subparsers.add_parser("version", aliases=["versions"], help="Deploy specific version of the stack")
     version_parser.add_argument("stack_name", help="Name of the stack")
-    version_parser.add_argument("--namespace", default=os.getenv("DOCKER_STACK_NAMESPACE", "default"), help="Stack namespace")
+    _add_namespace_argument(version_parser)
 
     parser.add_argument(
         "-u", "--user", help="Registry credentials in format hostname:username:password", action="append", required=False, default=[]
@@ -1208,6 +1595,22 @@ def main(args: List[str] = None):
 
     args = parser.parse_args(args if args else sys.argv[1:])
 
+    if args.command == "shell-auth":
+        try:
+            if args.operation == "ensure":
+                ensure_shell_access(required=True)
+            else:
+                from docker_stack.shell_auth import shell_auth_request
+
+                payload = shell_auth_request("status", required=True)
+                print(json.dumps(payload))
+        except ShellAuthError as exc:
+            print(f"docker-stack shell-auth: {exc}", file=sys.stderr)
+            if exc.requires_login:
+                print("Run: docker-stack login", file=sys.stderr)
+            return 2
+        return 0
+
     if args.command == "login":
         try:
             config = resolve_login_config(
@@ -1217,7 +1620,10 @@ 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:
+            if shell_session_active():
+                result = login_for_active_shell(config)
+                config_dir = current_shell_config
+            elif current_shell_config:
                 config_dir, result = ensure_isolated_login(config, docker_config_dir=current_shell_config)
             else:
                 config_dir = None
@@ -1247,30 +1653,43 @@ def main(args: List[str] = None):
         shell_name = args.target if args.context_name is None else None
         manager_target = args.target if args.context_name is not None else None
         try:
-            config = resolve_shell_login_config(
-                shell_name=shell_name,
-                manager_target=manager_target,
-                context_name=args.context_name,
-                timeout_secs=args.timeout_secs,
-            )
-            existing_shell_config = active_shell_config_dir(config.context_name)
-            config_dir, result = ensure_isolated_login(config)
+            try:
+                config = resolve_shell_login_config(
+                    shell_name=shell_name,
+                    manager_target=manager_target,
+                    context_name=args.context_name,
+                    timeout_secs=args.timeout_secs,
+                )
+            except UnknownShellContextError as exc:
+                manager_target = _prompt_for_manager_target(exc.context_name)
+                print(f"Creating Docker-Manager shell context '{exc.context_name}'...")
+                config = resolve_shell_login_config(
+                    shell_name=None,
+                    manager_target=manager_target,
+                    context_name=exc.context_name,
+                    timeout_secs=args.timeout_secs,
+                )
+                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
+            result = browser_login(config)
         except RuntimeError as exc:
             print(f"docker-stack shell: {exc}", file=sys.stderr)
             sys.exit(2)
-        if existing_shell_config:
-            print(f"Refreshing current shell context={config.context_name}")
-        else:
-            print(f"Opening shell context={config.context_name}")
+        print(f"Opening shell context={config.context_name}")
         print(f"Shell manager={config.manager_url}")
-        print(f"DOCKER_CONFIG={config_dir}")
         if result is not None:
             expiry = format_expiry(result.expires_at)
             if expiry:
                 print(f"Access token expires in {expiry}")
         else:
             print("Access token already active.")
-        sys.exit(open_context_shell(config_dir, config.context_name))
+        try:
+            sys.exit(run_managed_shell(config, result))
+        except ShellAuthError as exc:
+            print(f"docker-stack shell: {exc}", file=sys.stderr)
+            sys.exit(2)
 
     if args.command == "setup-auth":
         try:
@@ -1314,59 +1733,72 @@ def main(args: List[str] = None):
                 print("Docker-Manager auth header cleared from ~/.docker/config.json.")
             return
 
-    docker = Docker(registries=args.user)
-    docker.load_env()
-
-    if args.command == "build":
-        docker.stack.build_and_push(args.compose_file, push=args.push)
-    elif args.command == "push":
-        docker.stack.push(args.compose_file)
-    elif args.command == "deploy":
-        docker.stack.deploy(
-            args.stack_name,
-            args.compose_file,
-            args.with_registry_auth,
-            tag=args.tag,
-            show_generated=args.show_generated,
-            namespace=args.namespace,
-            dry_run=args.ro,
-        )
-    elif args.command == "ls":
-        docker.stack.ls()
-    elif args.command == "node":
-        if args.node_command == "ls":
-            docker.node.ls()
-
-    elif args.command == "rm":
-        docker.stack.rm(args.stack_name)
-    elif args.command == "prune":
-        docker.stack.prune()
-    elif args.command == "cat":
-        version_to_cat = args.version
-        if version_to_cat is None:
-            versions_list = docker.stack.versions(args.stack_name, namespace=args.namespace, print_output=False)
-            if versions_list:
-                # Assuming versions are integers, find the maximum
-                latest_version = max(int(v[0]) for v in versions_list if v[0].isdigit())
-                version_to_cat = str(latest_version)
-            else:
-                print(f"No versions found for stack '{args.stack_name}'.")
-                sys.exit(1)
-        print(docker.stack.cat(args.stack_name, version_to_cat, namespace=args.namespace))
-    elif args.command == "checkout":
-        docker.stack.checkout(
-            args.stack_name,
-            args.version,
-            namespace=args.namespace,
-            dry_run=args.ro,
-        )
-    elif args.command == "versions" or args.command == "version":
-        docker.stack.versions(args.stack_name, namespace=args.namespace)
-    if args.ro:
-        print("Following commands were not executed:")
-        [print(" >> " + str(x)) for x in docker.stack.commands if x]
-    else:
-        [x.execute() for x in docker.stack.commands]
+    try:
+        docker = Docker(registries=args.user)
+        docker.load_env()
+
+        if hasattr(args, "namespace") and args.command != "ls":
+            print(f"Namespace: {args.namespace}", file=sys.stderr)
+
+        if args.command == "build":
+            docker.stack.build_and_push(args.compose_file, push=args.push)
+        elif args.command == "push":
+            docker.stack.push(args.compose_file)
+        elif args.command == "deploy":
+            docker.stack.deploy(
+                args.stack_name,
+                args.compose_file,
+                args.with_registry_auth,
+                tag=args.tag,
+                show_generated=args.show_generated,
+                namespace=args.namespace,
+                dry_run=args.ro,
+                prune=args.prune,
+                resolve_image=args.resolve_image,
+                force_update=args.force_update,
+            )
+        elif args.command == "ls":
+            docker.stack.ls(namespace=None if args.all_namespaces else (args.namespace or DEFAULT_NAMESPACE))
+        elif args.command == "node":
+            if args.node_command == "ls":
+                docker.node.ls()
+
+        elif args.command == "rm":
+            docker.stack.rm(args.stack_name, namespace=args.namespace)
+        elif args.command == "prune":
+            docker.stack.prune()
+        elif args.command == "cat":
+            version_to_cat = args.version
+            if version_to_cat is None:
+                versions_list = docker.stack.versions(args.stack_name, namespace=args.namespace, print_output=False)
+                if versions_list:
+                    # Assuming versions are integers, find the maximum
+                    latest_version = max(int(v[0]) for v in versions_list if v[0].isdigit())
+                    version_to_cat = str(latest_version)
+                else:
+                    print(f"No versions found for stack '{args.stack_name}'.")
+                    sys.exit(1)
+            print(docker.stack.cat(args.stack_name, version_to_cat, namespace=args.namespace))
+        elif args.command == "checkout":
+            docker.stack.checkout(
+                args.stack_name,
+                args.version,
+                namespace=args.namespace,
+                dry_run=args.ro,
+            )
+        elif args.command == "versions" or args.command == "version":
+            docker.stack.versions(args.stack_name, namespace=args.namespace)
+        if args.ro:
+            print("Following commands were not executed:")
+            [print(" >> " + str(x)) for x in docker.stack.commands if x]
+        else:
+            [x.execute() for x in docker.stack.commands]
+    except subprocess.CalledProcessError as exc:
+        print(_format_called_process_error(exc), file=sys.stderr)
+        sys.exit(exc.returncode or 2)
+    except RuntimeError as exc:
+        print(_format_runtime_error(exc), file=sys.stderr)
+        sys.exit(2)
 
 
 if __name__ == "__main__":