kcm-workspace 0.1.0__tar.gz

kcm_workspace-0.1.0/AUTHORS.md

@@ -0,0 +1,3 @@
+# Authors
+
+- Kelson da Costa Medeiros <kelsoncm@gmail.com>, Tech Leader & Developer

kcm_workspace-0.1.0/LICENSE.md

@@ -0,0 +1,23 @@
+# License
+
+## The MIT License (MIT)
+
+Copyright (c) 2026 python-by-kelsoncm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kcm_workspace-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: kcm-workspace
+Version: 0.1.0
+Summary: Base class for docker compose workspace scripts (clone, setup, launch, shell, manage and more)
+Author-email: Kelson da Costa Medeiros <kelsoncm@gmail.com>
+License: # License
+        
+        ## The MIT License (MIT)
+        
+        Copyright (c) 2026 python-by-kelsoncm
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/python-by-kelsoncm/python-kcm-workspace
+Project-URL: Bug Tracker, https://github.com/python-by-kelsoncm/python-kcm-workspace/issues
+Project-URL: Download, https://github.com/python-by-kelsoncm/python-kcm-workspace/releases/
+Keywords: docker,compose,workspace,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+License-File: AUTHORS.md
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.6.0; extra == "dev"
+Requires-Dist: black>=26.3.1; extra == "dev"
+Requires-Dist: ruff>=0.15.11; extra == "dev"
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
+Dynamic: license-file
+
+# kcm-workspace
+
+Classe base para os scripts de workspace baseados em `docker compose`
+(`clone`, `setup`, `launch`, `shell`, `manage`, `git` e outros).
+
+Cada projeto tem, em `<projeto>/workspace/<projeto>`, um script que estende
+`Workspace` e informa no construtor o que é específico dele.
+
+## Uso
+
+```python
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["kcm-workspace>=0.1.0"]
+# ///
+from kcm_workspace import GitClone, Workspace
+
+GITBASE = "git@github.com:minha-org"
+
+
+class Projeto(Workspace):
+    def __init__(self):
+        super().__init__(
+            __file__,
+            git_clones=[GitClone("app", f"{GITBASE}/app.git")],
+            mk_volumes=["db"],
+            cli_dict={"db": "psql"},
+            shell_dict={"db": "sh"},
+        )
+
+    def collectstatic(self) -> int:
+        """Coleta os estáticos. Aplica-se a: $services_names$"""
+        return self._execute("docker compose exec web python manage.py collectstatic")
+
+
+if __name__ == "__main__":
+    Projeto.main()
+```
+
+- `GitClone.folder` relativo é resolvido a partir da pasta do projeto (pai de `workspace`).
+- Um método vira comando quando a docstring termina com `Aplica-se a: <escopos>`.
+- Comandos desconhecidos são repassados para `docker compose`.
+- No Windows, use um wrapper `<projeto>.ps1`:
+
+```powershell
+$nomeSemExtensao = (Get-Item $PSCommandPath).BaseName
+uv run --script "$PSScriptRoot\$nomeSemExtensao" @args
+```
+
+## Atributos disponíveis
+
+`project_name`, `project_dir`, `workspace_dir`, `volumes_dir`, `home`, `argv`,
+`git_clones`, `mk_volumes`, `moodle_plugins`, `cli_dict`, `shell_dict`.
+
+## Métodos auxiliares
+
+`_execute(cmd, *args)`, `_service_is_running(svc)`, `_service_is_healthy(svc)`,
+`_prefixed_envs(prefix)`, `_resolve_django_service_and_args()`, `_verb`.
+
+## Desenvolvimento
+
+```bash
+uv pip install -e ".[dev]"
+pytest --cov=kcm_workspace
+```

kcm_workspace-0.1.0/README.md

@@ -0,0 +1,66 @@
+# kcm-workspace
+
+Classe base para os scripts de workspace baseados em `docker compose`
+(`clone`, `setup`, `launch`, `shell`, `manage`, `git` e outros).
+
+Cada projeto tem, em `<projeto>/workspace/<projeto>`, um script que estende
+`Workspace` e informa no construtor o que é específico dele.
+
+## Uso
+
+```python
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["kcm-workspace>=0.1.0"]
+# ///
+from kcm_workspace import GitClone, Workspace
+
+GITBASE = "git@github.com:minha-org"
+
+
+class Projeto(Workspace):
+    def __init__(self):
+        super().__init__(
+            __file__,
+            git_clones=[GitClone("app", f"{GITBASE}/app.git")],
+            mk_volumes=["db"],
+            cli_dict={"db": "psql"},
+            shell_dict={"db": "sh"},
+        )
+
+    def collectstatic(self) -> int:
+        """Coleta os estáticos. Aplica-se a: $services_names$"""
+        return self._execute("docker compose exec web python manage.py collectstatic")
+
+
+if __name__ == "__main__":
+    Projeto.main()
+```
+
+- `GitClone.folder` relativo é resolvido a partir da pasta do projeto (pai de `workspace`).
+- Um método vira comando quando a docstring termina com `Aplica-se a: <escopos>`.
+- Comandos desconhecidos são repassados para `docker compose`.
+- No Windows, use um wrapper `<projeto>.ps1`:
+
+```powershell
+$nomeSemExtensao = (Get-Item $PSCommandPath).BaseName
+uv run --script "$PSScriptRoot\$nomeSemExtensao" @args
+```
+
+## Atributos disponíveis
+
+`project_name`, `project_dir`, `workspace_dir`, `volumes_dir`, `home`, `argv`,
+`git_clones`, `mk_volumes`, `moodle_plugins`, `cli_dict`, `shell_dict`.
+
+## Métodos auxiliares
+
+`_execute(cmd, *args)`, `_service_is_running(svc)`, `_service_is_healthy(svc)`,
+`_prefixed_envs(prefix)`, `_resolve_django_service_and_args()`, `_verb`.
+
+## Desenvolvimento
+
+```bash
+uv pip install -e ".[dev]"
+pytest --cov=kcm_workspace
+```

kcm_workspace-0.1.0/kcm_workspace/__init__.py

@@ -0,0 +1,5 @@
+from .color import Color
+from .workspace import HOME, GitClone, Workspace
+
+__all__ = ["HOME", "Color", "GitClone", "Workspace"]
+__version__ = "0.1.0"

kcm_workspace-0.1.0/kcm_workspace/color.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+
+
+class Color:
+    ENDC = "\033[0m"
+
+    @staticmethod
+    def r(text: str | Path) -> str:
+        """Returns a *red* string"""
+        return f"\033[91m{text}{Color.ENDC}"
+
+    @staticmethod
+    def b(text: str | Path) -> str:
+        """Returns a *blue* string"""
+        return f"\033[94m{text}{Color.ENDC}"
+
+    @staticmethod
+    def g(text: str | Path) -> str:
+        """Returns a *green* string"""
+        return f"\033[92m{text}{Color.ENDC}"
+
+    @staticmethod
+    def c(text: str | Path) -> str:
+        """Returns a *cyan* string"""
+        return f"\033[96m{text}{Color.ENDC}"
+
+    @staticmethod
+    def m(text: str | Path) -> str:
+        """Returns a *magenta* string"""
+        return f"\033[95m{text}{Color.ENDC}"
+
+    @staticmethod
+    def y(text: str | Path) -> str:
+        """Returns a *yellow* string"""
+        return f"\033[93m{text}{Color.ENDC}"
+
+    @staticmethod
+    def s(text: str | Path) -> str:
+        """Returns a *strong* string"""
+        return f"\033[1m{text}{Color.ENDC}"
+
+    @staticmethod
+    def u(text: str | Path) -> str:
+        """Returns a *underlined* string"""
+        return f"\033[4m{text}{Color.ENDC}"

kcm_workspace-0.1.0/kcm_workspace/workspace.py

@@ -0,0 +1,425 @@
+import glob
+import inspect
+import os
+import re
+import subprocess  # nosec B404
+import sys
+import time
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from .color import Color
+
+HOME = Path(os.environ.get("HOME") or os.environ.get("USERPROFILE") or os.path.expanduser("~"))
+WINDOWS_HOSTS = Path(r"C:\Windows\System32\drivers\etc\hosts")
+POSIX_HOSTS = Path("/etc/hosts")
+
+NATIVES = {
+    "build": "Build or rebuild services.",
+    "convert": "Converts the compose file to platform's canonical format.",
+    "cp": "Copy files/folders between a service container and the local filesystem.",
+    "create": "Creates containers for a service.",
+    "down": "Stop and remove containers: networks.",
+    "events": "Receive real time events from containers.",
+    "exec": "Execute a command in a running container.",
+    "images": "List images used by the created containers.",
+    "kill": "Force stop service containers.",
+    "logs": "View output from containers.",
+    "ls": "List running compose projects.",
+    "pause": "Pause services.",
+    "port": "Print the public port for a port binding.",
+    "ps": "List containers.",
+    "pull": "Pull service images.",
+    "push": "Push service images.",
+    "restart": "Restart service containers.",
+    "rm": "Removes stopped service containers.",
+    "run": "Run a one-off command on a service.",
+    "start": "Start services.",
+    "stop": "Stop services.",
+    "top": "Display the running processes.",
+    "unpause": "Unpause services.,",
+    "up": "Create and start containers.",
+    "version": "Show the Docker Compose version information.",
+}
+
+
+@dataclass
+class GitClone:
+    """Repositório a ser clonado. ``folder`` relativo é resolvido a partir da pasta do projeto."""
+
+    folder: str | Path
+    url: str
+    branch: str = "main"
+
+
+class Workspace:
+    """Base dos scripts de workspace.
+
+    Cada projeto estende esta classe e informa no construtor o que é específico dele.
+    Um método vira comando quando a docstring termina com ``Aplica-se a: <escopos>``.
+    """
+
+    def __init__(
+        self,
+        script_file: str | Path,
+        git_clones: list[GitClone] | None = None,
+        mk_volumes: list[str] | None = None,
+        moodle_plugins: list[str] | None = None,
+        cli_dict: dict[str, str] | None = None,
+        shell_dict: dict[str, str] | None = None,
+        argv: list[str] | None = None,
+    ):
+        self.script = Path(script_file).resolve()
+        self.project_name = self.script.stem
+        self.workspace_dir = self.script.parent
+        self.project_dir = self.workspace_dir.parent
+        self.volumes_dir = Path(os.environ.get("VOLUMES_DIR", self.project_dir / "volumes"))
+        self.home = HOME
+
+        self.git_clones = [GitClone(self.project_dir / g.folder, g.url, g.branch) for g in (git_clones or [])]
+        self.mk_volumes = mk_volumes or []
+        self.moodle_plugins = moodle_plugins or []
+        self.cli_dict = cli_dict or {}
+        self.shell_dict = shell_dict or {}
+
+        self.argv = list(sys.argv if argv is None else argv)
+        self._command_name = self.argv[1] if len(self.argv) > 1 else "help"
+        self._scope_name = self.argv[2] if len(self.argv) >= 3 else "env"
+        self._service_name = self._scope_name if self._scope_name != "env" else ""
+
+        self._services: list[str] = []
+        self._repositories: set[str] = set()
+        self._commands: dict = {}
+        self._scopes: dict[str, list[str]] = {}
+        self._descriptions: dict[str, str] = {}
+
+    # ------------------------------------------------------------------ execução
+
+    def run(self) -> int:
+        """Lê .env e docker compose, carrega os comandos e executa o solicitado."""
+        try:
+            os.chdir(self.workspace_dir)
+            print(f"Trabalhando em {Color.c(self.workspace_dir)}")
+            self._read_envs()
+            self._read_compose()
+            self._load_commands()
+            if len(self.argv) == 1:
+                return self.help()
+            if self._command_name not in self._commands:
+                print(f"{Color.g('docker compose')} {Color.b(self._command_name)} {Color.m(' '.join(self.argv[2:]))}")
+                return self._execute("docker", "compose", *self.argv[1:])
+            return self._commands[self._command_name]() or 0
+        except KeyboardInterrupt:
+            print(f"\n{Color.r('Interrompido pelo usuário')}")
+            return 130
+
+    @classmethod
+    def main(cls) -> None:
+        """Ponto de entrada: ``if __name__ == "__main__": MeuProjeto.main()``."""
+        sys.exit(cls().run())
+
+    # ------------------------------------------------------------------ internos
+
+    def _read_envs(self) -> None:
+        env_file = self.workspace_dir / ".env"
+        if not env_file.exists():
+            return
+        try:
+            content = env_file.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            content = env_file.read_text()
+        for line in content.splitlines():
+            if line.startswith("#") or line.strip() == "" or "=" not in line:
+                continue
+            varname, varval = line.split("=", 1)
+            if varname == "COMPOSE_PROJECT_NAME" and varval != self.project_name:
+                raise ValueError(f"No arquivo .env está como {line}, mas devia ser {varname}={self.project_name}")
+            os.environ[varname] = varval
+
+    def _read_compose(self) -> None:
+        result = subprocess.run(  # nosec B603 B607
+            ["docker", "compose", "config"], capture_output=True, text=True, cwd=self.workspace_dir
+        )
+        self._services = []
+        repositories = [""]
+        for line in result.stdout.splitlines():
+            service = re.search(r"^  (\w*):$", line)
+            if service and service.group(1) != "default":
+                self._services.append(service.group(1))
+            image = re.search(r"^(    image: )(.*)$", line)
+            if image:
+                name = image.group(2)
+                repositories.append(name.split("/")[0] if name.count("/") > 1 else "")
+        self._repositories = set(repositories)
+
+    def _load_commands(self) -> None:
+        for name, func in inspect.getmembers(type(self), inspect.isfunction):
+            match = re.search(r"^(.*)(Aplica-se a: )(.*)$", func.__doc__ or "", re.MULTILINE)
+            if match is None:
+                continue
+            scopes = match.group(3)
+            scopes = scopes.replace("$services_names$", ",".join(self._services))
+            scopes = scopes.replace("$restore_dirs$", ",".join(self._prefixed_envs("RESTORE_DIR_").keys()))
+            scopes = scopes.replace("$download_files$", ",".join(self._prefixed_envs("DOWNLOAD_FILE").keys()))
+            self._commands[name] = getattr(self, name)
+            self._scopes[name] = scopes.split(",")
+            self._descriptions[name] = match.group(1) + match.group(2)
+
+    def _container_lines(self) -> list[str]:
+        result = subprocess.run(["docker", "container", "ps"], capture_output=True, text=True)  # nosec B603 B607
+        return result.stdout.splitlines()
+
+    def _service_is_running(self, service_name: str) -> bool:
+        pattern = f".*{self.project_name}-{service_name}-1.*"
+        return any(re.match(pattern, line) for line in self._container_lines())
+
+    def _service_is_healthy(self, service_name: str) -> bool:
+        pattern = f".*{self.project_name}-{service_name}-1.*"
+        return any(re.match(pattern, line) and "healthy" in line for line in self._container_lines())
+
+    def _execute(self, executable_file: str, *args: str) -> int:
+        command = " ".join([executable_file, *args])
+        print(Color.g("Executando: "), Color.b(command))
+        p = subprocess.Popen(  # nosec B602
+            command, stdin=sys.stdin, stdout=sys.stdout, stderr=sys.stdout, shell=True, cwd=self.workspace_dir
+        )
+        return p.wait()
+
+    def _write_shell_file(self, filename: str) -> None:
+        shell_file = self.home / filename
+        if shell_file.exists() and str(self.workspace_dir) not in shell_file.read_text(encoding="utf-8"):
+            with shell_file.open("a", encoding="utf-8") as f:
+                f.write(f"\nPATH=$PATH:{self.workspace_dir}\n")
+            print("Lembre-se de executar o comando abaixo:")
+            print(Color.g(f"source ~/{filename}"), "\n")
+
+    @staticmethod
+    def _prefixed_envs(prefix: str) -> dict[str, str]:
+        return {k[len(prefix) :].lower(): v for k, v in os.environ.items() if k.startswith(prefix)}
+
+    @property
+    def _verb(self) -> str:
+        return "exec" if self._service_is_running(self._service_name) else "run --rm"
+
+    @property
+    def _default_django(self) -> str:
+        django_svc = os.environ.get("DEFAULT_DJANGO", "web")
+        return django_svc if django_svc in self._services else "web"
+
+    def _resolve_django_service_and_args(self) -> tuple[str, str, list[str]]:
+        if self._service_name in self._services:
+            service, args = self._service_name, self.argv[3:]
+        else:
+            service, args = self._default_django, self.argv[2:]
+        verb = "exec" if self._service_is_running(service) else "run --rm"
+        return service, verb, args
+
+    def _write_hosts(self) -> None:
+        hosts = self._prefixed_envs("HOSTS")
+        if "" not in hosts or ":" not in hosts[""]:
+            return
+        hosts_name, hosts_value = hosts[""].split(":", 1)
+        hosts_file = WINDOWS_HOSTS if sys.platform == "win32" else POSIX_HOSTS
+        try:
+            content = hosts_file.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            print(Color.y(f"Arquivo de hosts ({hosts_file}) não encontrado."))
+            return
+        if hosts_value in content:
+            return
+        print(f"Adicionando este {hosts_value} em {hosts_file}:")
+        nls = "#" * 70
+        new_hosts = f"\n{nls}\n## {hosts_name}\n{nls}\n{hosts_value}\n"
+        if sys.platform != "win32":
+            self._execute(f"echo '{new_hosts}' | sudo tee -a {hosts_file}")
+            return
+        try:
+            with hosts_file.open("a", encoding="utf-8") as f:
+                f.write(new_hosts)
+        except PermissionError:
+            print(
+                Color.r(
+                    f"Permissão negada ao escrever em {hosts_file}. Execute o terminal como Administrador "
+                    f"ou adicione manualmente a linha abaixo em {hosts_file}:\n{hosts_value}"
+                )
+            )
+
+    def _mk_volumes(self) -> None:
+        for mkvol in self.mk_volumes:
+            vol = self.volumes_dir / mkvol
+            print(vol)
+            vol.mkdir(parents=True, exist_ok=True)
+            if sys.platform != "win32":
+                self._execute(f"sudo chmod -R 777 {vol}")
+
+    # ------------------------------------------------------------------ comandos
+
+    def help(self) -> int:
+        """Imprime esta ajuda. Aplica-se a: env"""
+        print(f"""Uso:\n{Color.r(f'{self.project_name} [OPTIONS] COMMAND')}\n\nOptions:
+    {Color.m('--ansi')} {Color.y('string')}                Control when to print ANSI control characters ("never"|"always"|"auto") (default "auto")
+    {Color.m('--compatibility')}              Run compose in backward compatibility mode
+    {Color.m('--env-file')} {Color.y('string')}            Specify an alternate environment file.
+{Color.m('-f')}, {Color.m('--file')} {Color.y('stringArray')}           Compose configuration files
+    {Color.m('--profile')} {Color.y('stringArray')}        Specify a profile to enable
+    {Color.m('--project-directory')} {Color.y('string')}   Specify an alternate working directory (default: the path of the, first specified, Compose file)
+    {Color.m('-p')}, {Color.m('--project-name')} {Color.y('string')}    Project name\nComandos:""")  # noqa: E501
+        for m in list(NATIVES.keys()) + list(self._commands.keys()):
+            fixed = Color.m(f"{m:22}")
+            description = self._descriptions.get(m, NATIVES.get(m, " Sem descrição"))
+            scopes = Color.c(", ".join(self._scopes.get(m, [" Ver `docker compose`"])))
+            print(f"  {fixed} - {description}{scopes}")
+        print(f"Execute '{self.script.name} COMMAND help' para imprimir a ajuda.")
+        return 0
+
+    def relaunch(self) -> int:
+        """Para e depois inicia ambiente ou o serviço especificado, não faz lock do CLI. Aplica-se a: $services_names$,env"""  # noqa: E501
+        self._execute(f"docker compose down {self._service_name}")
+        return self._execute(f"docker compose up -d {self._service_name}")
+
+    def launch(self) -> int:
+        """Mostra o status ambiente ou o serviço especificado. Aplica-se a: $services_names$,env"""
+        self.relaunch()
+        return self._execute(f"docker compose logs -f {self._service_name}")
+
+    def exec(self) -> int:
+        """Executa um comando em um serviço que já esteja em execução. Aplica-se a: $services_names$,env"""
+        return self._execute(f"docker compose {self._verb} {self._service_name} ", *self.argv[3:])
+
+    def clone(self) -> int:
+        """Clona todos os repositórios. Aplica-se a: env"""
+        for g in self.git_clones:
+            folder = Path(g.folder)
+            folder.parent.mkdir(mode=0o770, parents=True, exist_ok=True)
+            if not folder.exists():
+                print(f"Clonando {Color.c(folder)} do repositório {Color.y(g.url)} na branch {Color.m(g.branch)}")
+                self._execute(f'git clone -b {g.branch} {g.url} "{folder}"')
+        return 0
+
+    def setup(self) -> int:
+        """Executa o setup do ambiente, ou seja, clona todos os repositórios e configura o PATH e o hosts. Aplica-se a: env"""  # noqa: E501
+        self._execute(f"docker compose down {self._service_name}")
+        self.clone()
+        self._write_hosts()
+        self._mk_volumes()
+        self._write_shell_file(".bashrc")
+        self._write_shell_file(".zshrc")
+        return 0
+
+    def deploy(self) -> int:
+        """Para tudo, constrói as imagens, iniciar os serviços background e acompanha o log. Aplica-se a: env"""
+        self.setup()
+        return self._execute("docker compose up -d")
+
+    def undeploy(self) -> int:
+        """Pára todo o ambiente e remove os volumes. Aplica-se a: $services_names$,env"""
+        return self._execute("docker compose down -v")
+
+    def git(self) -> int:
+        """Executa o comando git em todos os repositórios git. Aplica-se a: env"""
+        git_arguments = " ".join(self.argv[2:]) if len(self.argv) > 2 else "status"
+        print(f"Executando {Color.b('git ' + git_arguments)} em {Color.m(self.workspace_dir)}")
+        self._execute(f'git -C "{self.workspace_dir}" {git_arguments}')
+        for g in self.git_clones:
+            if Path(g.folder).exists():
+                print(f"Executando {Color.b('git ' + git_arguments)} em {Color.m(g.folder)}")
+                self._execute(f'git -C "{g.folder}" {git_arguments}')
+            else:
+                print(f"O projeto {g.folder} NÃO foi clonado ainda.")
+        return 0
+
+    def cli(self) -> int:
+        """Executa a CLI padrão do serviço, pode ser php -a, shell_plus, psql ou redis-cli. Bash por padrão. Usará exec se possível, caso contrário será run. Aplica-se a: $services_names$"""  # noqa: E501
+        cmd = self.cli_dict.get(self._service_name, "bash")
+        return self._execute(f"docker compose {self._verb} {self._service_name} {cmd} ", *self.argv[3:])
+
+    def shell(self) -> int:
+        """Executa o bash ou sh de um serviço, usará exec se já estiver em execução, run caso contrário. Aplica-se a: $services_names$"""  # noqa: E501
+        cmd = self.shell_dict.get(self._service_name, "bash")
+        return self._execute(f"docker compose {self._verb} {self._service_name} {cmd} ", *self.argv[3:])
+
+    def shell_root(self) -> int:
+        """Executa o bash ou sh de um serviço como root, usará exec se já estiver em execução, run caso contrário. Aplica-se a: $services_names$"""  # noqa: E501
+        cmd = self.shell_dict.get(self._service_name, "bash")
+        return self._execute(f"docker compose {self._verb} -u root {self._service_name} {cmd} ", *self.argv[3:])
+
+    def wait(self) -> int:
+        """Aguarda até o banco de dados estar disponível. Aplica-se a: db"""
+        while not self._service_is_healthy("db"):
+            print(Color.y("Aguardando o banco de dados estar disponível..."))
+            time.sleep(3)
+        print(Color.g("Banco de dados disponível!"))
+        return 0
+
+    def manage(self) -> int:
+        """Executa o manage.py do do serviço. Aplica-se a: $services_names$"""
+        service, verb, args = self._resolve_django_service_and_args()
+        return self._execute(f"docker compose {verb} {service} python3 manage.py ", *args)
+
+    def makemigrations(self) -> int:
+        """Criar as migrações pendentes do serviço. Aplica-se a: $services_names$"""
+        service, verb, args = self._resolve_django_service_and_args()
+        return self._execute(f"docker compose {verb} {service} python3 manage.py makemigrations", *args)
+
+    def migrate(self) -> int:
+        """Aplica as migrações pendentes do serviço. Aplica-se a: $services_names$"""
+        service, verb, args = self._resolve_django_service_and_args()
+        return self._execute(f"docker compose {verb} {service} python3 manage.py migrate", *args)
+
+    def show_urls(self) -> int:
+        """Mostra as URL do serviço. Aplica-se a: $services_names$"""
+        service, verb, args = self._resolve_django_service_and_args()
+        return self._execute(f"docker compose {verb} {service} python manage.py show_urls", *args)
+
+    def test(self) -> int:
+        """Executa os testes unitários do serviço. Aplica-se a: $services_names$"""
+        service, verb, args = self._resolve_django_service_and_args()
+        self._execute(f"docker compose {verb} {service} coverage run manage.py test", *args)
+        return self._execute(f"docker compose {verb} {service} coverage report", *args)
+
+    def lint(self) -> int:
+        """Formata o código do serviço com black. Aplica-se a: $services_names$"""
+        service, verb, args = self._resolve_django_service_and_args()
+        return self._execute(f"docker compose {verb} {service} black --line-length 120 .", *args)
+
+    def compress_plugins(self) -> int:
+        """Comprime todos os plugins Moodle. Aplica-se a: env"""
+
+        def zip_with_prefix(folder_path: Path, zip_path: Path, prefix: str) -> None:
+            zip_path.parent.mkdir(parents=True, exist_ok=True)
+            with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zipf:
+                for file_path in folder_path.rglob("*"):
+                    if not file_path.is_file() or {".git", ".idea"} & set(file_path.parts):
+                        continue
+                    zipf.write(file_path, Path(prefix) / file_path.relative_to(folder_path))
+
+        build_dir = self.workspace_dir / "build" / "plugins"
+        for plugin_fullname in self.moodle_plugins:
+            plugin_name = plugin_fullname.split("_", 1)[1]
+            plugin_dir = self.project_dir / plugin_fullname
+            for line in (plugin_dir / "version.php").read_text(encoding="utf-8").splitlines():
+                if not line.startswith("$plugin->version"):
+                    continue
+                plugin_version = line.split("=")[1].replace(";", "").split()[0]
+                plugin_package = build_dir / f"{plugin_fullname}-{plugin_version}.zip"
+                if plugin_package.exists():
+                    print(f"Plugin {Color.c(plugin_package)} {Color.r('JÁ existe')}.")
+                    continue
+                print(f"Plugin {Color.c(plugin_package)} {Color.g('NÃO existe')}.")
+                for old_zip in glob.glob(str(build_dir / f"{plugin_fullname}-*.zip")):
+                    try:
+                        os.remove(old_zip)
+                    except OSError:
+                        pass
+                zip_with_prefix(plugin_dir, plugin_package, plugin_name)
+        return 0
+
+    def publish(self) -> int:
+        """Comprime os plugins Moodle e constrói e publica a imagem do serviço ava. Aplica-se a: env"""
+        self.compress_plugins()
+        return self._execute("docker compose build --progress plain --push ava")
+
+    def code(self) -> int:
+        """Abre o workspace no VS Code. Aplica-se a: env"""
+        return self._execute(f'code "{self.workspace_dir / f"{self.project_name}.code-workspace"}"')

kcm_workspace-0.1.0/kcm_workspace.egg-info/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: kcm-workspace
+Version: 0.1.0
+Summary: Base class for docker compose workspace scripts (clone, setup, launch, shell, manage and more)
+Author-email: Kelson da Costa Medeiros <kelsoncm@gmail.com>
+License: # License
+        
+        ## The MIT License (MIT)
+        
+        Copyright (c) 2026 python-by-kelsoncm
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/python-by-kelsoncm/python-kcm-workspace
+Project-URL: Bug Tracker, https://github.com/python-by-kelsoncm/python-kcm-workspace/issues
+Project-URL: Download, https://github.com/python-by-kelsoncm/python-kcm-workspace/releases/
+Keywords: docker,compose,workspace,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+License-File: AUTHORS.md
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.6.0; extra == "dev"
+Requires-Dist: black>=26.3.1; extra == "dev"
+Requires-Dist: ruff>=0.15.11; extra == "dev"
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
+Dynamic: license-file
+
+# kcm-workspace
+
+Classe base para os scripts de workspace baseados em `docker compose`
+(`clone`, `setup`, `launch`, `shell`, `manage`, `git` e outros).
+
+Cada projeto tem, em `<projeto>/workspace/<projeto>`, um script que estende
+`Workspace` e informa no construtor o que é específico dele.
+
+## Uso
+
+```python
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["kcm-workspace>=0.1.0"]
+# ///
+from kcm_workspace import GitClone, Workspace
+
+GITBASE = "git@github.com:minha-org"
+
+
+class Projeto(Workspace):
+    def __init__(self):
+        super().__init__(
+            __file__,
+            git_clones=[GitClone("app", f"{GITBASE}/app.git")],
+            mk_volumes=["db"],
+            cli_dict={"db": "psql"},
+            shell_dict={"db": "sh"},
+        )
+
+    def collectstatic(self) -> int:
+        """Coleta os estáticos. Aplica-se a: $services_names$"""
+        return self._execute("docker compose exec web python manage.py collectstatic")
+
+
+if __name__ == "__main__":
+    Projeto.main()
+```
+
+- `GitClone.folder` relativo é resolvido a partir da pasta do projeto (pai de `workspace`).
+- Um método vira comando quando a docstring termina com `Aplica-se a: <escopos>`.
+- Comandos desconhecidos são repassados para `docker compose`.
+- No Windows, use um wrapper `<projeto>.ps1`:
+
+```powershell
+$nomeSemExtensao = (Get-Item $PSCommandPath).BaseName
+uv run --script "$PSScriptRoot\$nomeSemExtensao" @args
+```
+
+## Atributos disponíveis
+
+`project_name`, `project_dir`, `workspace_dir`, `volumes_dir`, `home`, `argv`,
+`git_clones`, `mk_volumes`, `moodle_plugins`, `cli_dict`, `shell_dict`.
+
+## Métodos auxiliares
+
+`_execute(cmd, *args)`, `_service_is_running(svc)`, `_service_is_healthy(svc)`,
+`_prefixed_envs(prefix)`, `_resolve_django_service_and_args()`, `_verb`.
+
+## Desenvolvimento
+
+```bash
+uv pip install -e ".[dev]"
+pytest --cov=kcm_workspace
+```

kcm_workspace-0.1.0/kcm_workspace.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+AUTHORS.md
+LICENSE.md
+README.md
+pyproject.toml
+kcm_workspace/__init__.py
+kcm_workspace/color.py
+kcm_workspace/workspace.py
+kcm_workspace.egg-info/PKG-INFO
+kcm_workspace.egg-info/SOURCES.txt
+kcm_workspace.egg-info/dependency_links.txt
+kcm_workspace.egg-info/requires.txt
+kcm_workspace.egg-info/top_level.txt
+tests/test_workspace.py

kcm_workspace-0.1.0/kcm_workspace.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kcm_workspace-0.1.0/kcm_workspace.egg-info/requires.txt

@@ -0,0 +1,7 @@
+
+[dev]
+pre-commit>=4.6.0
+black>=26.3.1
+ruff>=0.15.11
+pytest>=9.0.3
+pytest-cov>=7.1.0

kcm_workspace-0.1.0/kcm_workspace.egg-info/top_level.txt

@@ -0,0 +1 @@
+kcm_workspace

kcm_workspace-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kcm-workspace"
+version = "0.1.0"
+description = "Base class for docker compose workspace scripts (clone, setup, launch, shell, manage and more)"
+readme = "README.md"
+license = { file = "LICENSE.md" }
+authors = [{ name = "Kelson da Costa Medeiros", email = "kelsoncm@gmail.com" }]
+keywords = ["docker", "compose", "workspace", "cli"]
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pre-commit>=4.6.0",
+    "black>=26.3.1",
+    "ruff>=0.15.11",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/python-by-kelsoncm/python-kcm-workspace"
+"Bug Tracker" = "https://github.com/python-by-kelsoncm/python-kcm-workspace/issues"
+Download = "https://github.com/python-by-kelsoncm/python-kcm-workspace/releases/"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["kcm_workspace*"]
+
+[tool.coverage.run]
+source = ["kcm_workspace"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+
+[tool.ruff]
+line-length = 120
+force-exclude = true
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "S"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101", "S108"]
+"kcm_workspace/workspace.py" = ["S602", "S603", "S607"]
+
+[tool.black]
+line-length = 120

kcm_workspace-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kcm_workspace-0.1.0/tests/test_workspace.py

@@ -0,0 +1,264 @@
+import os
+import subprocess
+import zipfile
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+import kcm_workspace.workspace as ws_module
+from kcm_workspace import Color, GitClone, Workspace
+
+COMPOSE_CONFIG = """name: demo
+services:
+  db:
+    image: postgres:16
+  web:
+    image: ghcr.io/org/web:latest
+networks:
+  default:
+    name: demo_default
+"""
+
+
+class Demo(Workspace):
+    def __init__(self, script, argv, **kwargs):
+        super().__init__(script, argv=argv, **kwargs)
+
+    def extra(self) -> int:
+        """Comando do projeto. Aplica-se a: $services_names$,env"""
+        return self._execute("echo", "extra")
+
+    def not_a_command(self):
+        """Sem escopo."""
+
+
+@pytest.fixture
+def project(tmp_path: Path) -> Path:
+    workspace = tmp_path / "demo" / "workspace"
+    workspace.mkdir(parents=True)
+    script = workspace / "demo"
+    script.write_text("#!/usr/bin/env python3\n")
+    return script
+
+
+@pytest.fixture
+def calls(monkeypatch):
+    """Captura comandos executados e simula docker."""
+
+    class Executed(list):
+        containers = {"value": ""}
+
+    executed = Executed()
+    containers = executed.containers
+
+    def fake_run(cmd, **kwargs):
+        if cmd[:3] == ["docker", "compose", "config"]:
+            return SimpleNamespace(stdout=COMPOSE_CONFIG, returncode=0)
+        if cmd[:3] == ["docker", "container", "ps"]:
+            return SimpleNamespace(stdout=containers["value"], returncode=0)
+        raise AssertionError(cmd)
+
+    class FakePopen:
+        def __init__(self, command, **kwargs):
+            executed.append(command)
+
+        def wait(self):
+            return 0
+
+    monkeypatch.setattr(subprocess, "run", fake_run)
+    monkeypatch.setattr(subprocess, "Popen", FakePopen)
+    monkeypatch.chdir(os.getcwd())
+    return executed
+
+
+def make(project: Path, *args: str, **kwargs) -> Demo:
+    return Demo(project, ["demo", *args], **kwargs)
+
+
+def test_paths(project: Path, monkeypatch):
+    monkeypatch.delenv("VOLUMES_DIR", raising=False)
+    w = make(project, git_clones=[GitClone("app", "url"), GitClone(project.parent.parent / "abs", "u2", "dev")])
+    assert w.project_name == "demo"
+    assert w.workspace_dir == project.parent
+    assert w.project_dir == project.parent.parent
+    assert w.volumes_dir == project.parent.parent / "volumes"
+    assert w.git_clones[0].folder == project.parent.parent / "app"
+    assert w.git_clones[1].folder == project.parent.parent / "abs"
+    assert w.git_clones[1].branch == "dev"
+
+
+def test_help_without_args(project, calls, capsys):
+    assert make(project).run() == 0
+    out = capsys.readouterr().out
+    assert "extra" in out and "relaunch" in out and "not_a_command" not in out
+    assert "db,web,env" in out.replace(Color.ENDC, "").replace("\033[96m", "").replace(", ", ",")
+
+
+def test_command_with_service(project, calls):
+    assert make(project, "extra", "web").run() == 0
+    assert calls == ["echo extra"]
+
+
+def test_passthrough_to_compose(project, calls):
+    make(project, "ps", "-a").run()
+    assert calls == ["docker compose ps -a"]
+
+
+def test_exec_uses_run_when_not_running(project, calls):
+    make(project, "exec", "web", "ls").run()
+    assert calls == ["docker compose run --rm web  ls"]
+
+
+def test_exec_uses_exec_when_running(project, calls):
+    calls.containers["value"] = "abc demo-web-1 Up"
+    make(project, "exec", "web", "ls").run()
+    assert calls == ["docker compose exec web  ls"]
+
+
+def test_cli_and_shell(project, calls):
+    make(project, "cli", "db", cli_dict={"db": "psql"}).run()
+    make(project, "shell", "db", shell_dict={"db": "sh"}).run()
+    make(project, "shell_root", "web").run()
+    assert calls == [
+        "docker compose run --rm db psql ",
+        "docker compose run --rm db sh ",
+        "docker compose run --rm -u root web bash ",
+    ]
+
+
+def test_django_commands(project, calls, monkeypatch):
+    monkeypatch.delenv("DEFAULT_DJANGO", raising=False)
+    for cmd in ("manage", "makemigrations", "migrate", "show_urls", "test", "lint"):
+        make(project, cmd).run()
+    make(project, "migrate", "db", "app").run()
+    assert calls[0] == "docker compose run --rm web python3 manage.py "
+    assert calls[2] == "docker compose run --rm web python3 manage.py migrate"
+    assert "coverage report" in calls[5]
+    assert calls[-1] == "docker compose run --rm db python3 manage.py migrate app"
+
+
+def test_relaunch_launch_deploy_undeploy(project, calls, monkeypatch):
+    monkeypatch.setattr(ws_module, "HOME", project.parent)
+    make(project, "launch", "web").run()
+    make(project, "undeploy").run()
+    assert calls[:3] == ["docker compose down web", "docker compose up -d web", "docker compose logs -f web"]
+    assert calls[3] == "docker compose down -v"
+
+
+def test_setup(project, calls, monkeypatch, tmp_path):
+    home = tmp_path / "home"
+    home.mkdir()
+    (home / ".bashrc").write_text("# vazio\n")
+    hosts = tmp_path / "hosts"
+    hosts.write_text("127.0.0.1 localhost\n")
+    monkeypatch.setattr(ws_module, "WINDOWS_HOSTS", hosts)
+    monkeypatch.setattr(ws_module, "POSIX_HOSTS", hosts)
+    monkeypatch.setattr(ws_module.sys, "platform", "win32")
+    monkeypatch.setenv("HOSTS", "demo:127.0.0.1 demo.local")
+    monkeypatch.setenv("VOLUMES_DIR", str(tmp_path / "vols"))
+    w = make(project, "setup", git_clones=[GitClone("app", "git@x:app.git")], mk_volumes=["db"])
+    w.home = home
+    assert w.run() == 0
+    assert any(c.startswith("git clone -b main git@x:app.git") for c in calls)
+    assert "127.0.0.1 demo.local" in hosts.read_text()
+    assert (tmp_path / "vols" / "db").is_dir()
+    assert str(project.parent) in (home / ".bashrc").read_text()
+
+
+def test_write_hosts_posix_and_missing(project, calls, monkeypatch, tmp_path):
+    hosts = tmp_path / "hosts"
+    hosts.write_text("")
+    monkeypatch.setattr(ws_module, "POSIX_HOSTS", hosts)
+    monkeypatch.setattr(ws_module.sys, "platform", "linux")
+    monkeypatch.setenv("HOSTS", "demo:127.0.0.1 demo.local")
+    w = make(project)
+    w._write_hosts()
+    assert "sudo tee -a" in calls[-1]
+    monkeypatch.setattr(ws_module, "POSIX_HOSTS", tmp_path / "nao-existe")
+    w._write_hosts()
+    w.mk_volumes = ["x"]
+    w.volumes_dir = tmp_path / "v"
+    w._mk_volumes()
+    assert calls[-1].startswith("sudo chmod -R 777")
+
+
+def test_write_hosts_permission_denied(project, calls, monkeypatch, tmp_path, capsys):
+    hosts = tmp_path / "hosts"
+    hosts.write_text("")
+    monkeypatch.setattr(ws_module, "WINDOWS_HOSTS", hosts)
+    monkeypatch.setattr(ws_module.sys, "platform", "win32")
+    monkeypatch.setenv("HOSTS", "demo:127.0.0.1 demo.local")
+
+    original_open = Path.open
+
+    def deny(self, mode="r", *args, **kwargs):
+        if "a" in mode:
+            raise PermissionError
+        return original_open(self, mode, *args, **kwargs)
+
+    monkeypatch.setattr(Path, "open", deny)
+    make(project)._write_hosts()
+    assert "Permissão negada" in capsys.readouterr().out
+
+
+def test_read_envs(project, calls):
+    (project.parent / ".env").write_text("# comentário\n\nKCM_TEST_VAR=a=b\nCOMPOSE_PROJECT_NAME=demo\n")
+    make(project, "ps").run()
+    assert os.environ["KCM_TEST_VAR"] == "a=b"
+    (project.parent / ".env").write_text("COMPOSE_PROJECT_NAME=outro\n")
+    with pytest.raises(ValueError, match="devia ser COMPOSE_PROJECT_NAME=demo"):
+        make(project, "ps").run()
+
+
+def test_git(project, calls, tmp_path):
+    (project.parent.parent / "app").mkdir()
+    make(project, "git", "pull", git_clones=[GitClone("app", "u"), GitClone("falta", "u")]).run()
+    assert calls[0].endswith("pull") and len(calls) == 2
+
+
+def test_wait(project, calls, monkeypatch):
+    states = iter(["", "x demo-db-1 Up (healthy)"])
+    monkeypatch.setattr(Workspace, "_container_lines", lambda self: next(states).splitlines())
+    monkeypatch.setattr(ws_module.time, "sleep", lambda s: None)
+    assert make(project, "wait", "db").run() == 0
+
+
+def test_compress_and_publish(project, calls):
+    plugin = project.parent.parent / "local_demo"
+    (plugin / ".git").mkdir(parents=True)
+    (plugin / ".git" / "HEAD").write_text("x")
+    (plugin / "version.php").write_text("<?php\n$plugin->version = 2026102800;\n")
+    build = project.parent / "build" / "plugins"
+    build.mkdir(parents=True)
+    (build / "local_demo-1.zip").write_text("velho")
+    make(project, "publish", moodle_plugins=["local_demo"]).run()
+    package = build / "local_demo-2026102800.zip"
+    assert package.exists() and not (build / "local_demo-1.zip").exists()
+    with zipfile.ZipFile(package) as z:
+        assert z.namelist() == ["demo/version.php"]
+    make(project, "compress_plugins", moodle_plugins=["local_demo"]).run()
+    assert calls[-1] == "docker compose build --progress plain --push ava"
+
+
+def test_code(project, calls):
+    make(project, "code").run()
+    assert calls[0].startswith("code ") and calls[0].endswith('demo.code-workspace"')
+
+
+def test_keyboard_interrupt(project, calls, monkeypatch):
+    def boom(self):
+        raise KeyboardInterrupt
+
+    monkeypatch.setattr(Demo, "_read_envs", boom)
+    assert make(project, "ps").run() == 130
+
+
+def test_main_exits_with_code(project, calls, monkeypatch):
+    class Main(Workspace):
+        def __init__(self):
+            super().__init__(project, argv=["demo", "ps"])
+
+    with pytest.raises(SystemExit) as exc:
+        Main.main()
+    assert exc.value.code == 0