@ngocsangairvds/vsaf 4.1.9 → 4.1.10

package/skills/vds-skill/runtime/platform_core/tests/test_alembic_runtime.py

@@ -0,0 +1,300 @@
+"""Unit tests for vds_platform_core.alembic.runtime (WP-5.2 / ADR-INF-12).
+
+All tests are fully synthetic — no real Postgres, no real Alembic runner.
+alembic.context and SQLAlchemy are mocked at the boundary so the helper
+module's logic is exercised in isolation.
+
+TDD discipline:
+  - These tests were written BEFORE runtime.py existed (RED step).
+  - They must fail until runtime.py is implemented (GREEN step).
+
+Coverage targets:
+  - resolve_database_url: single env var lookup; RuntimeError on missing.
+    (v2.15.12: removed force_psycopg_v3 + fallback-list semantics — no-fallback
+    directive; per-stanza connect_query in pgbouncer.ini handles search_path.)
+  - run_migrations_offline: version_table_schema defaulting; explicit "sched"
+    override; include_name plumbing; correct configure kwargs; no SET search_path.
+  - run_migrations_online: same defaulting/override; engine_from_config called;
+    context.configure called with connection kwarg; no text("SET search_path")
+    executed on the connection.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_include_name():
+    """Return a trivial include_name callable for wiring tests."""
+
+    def _fn(name: str | None, type_: str, parent_names: dict[str, Any]) -> bool:
+        return True
+
+    return _fn
+
+
+# ---------------------------------------------------------------------------
+# resolve_database_url
+# ---------------------------------------------------------------------------
+
+
+class TestResolveDatabaseUrl:
+    """Tests for resolve_database_url (v2.15.12 single-var, no-fallback)."""
+
+    def test_returns_value_when_env_var_set(self, monkeypatch):
+        """The env var's value is returned when set."""
+        monkeypatch.setenv("MY_DSN", "postgresql://host/db")
+        from vds_platform_core.alembic.runtime import resolve_database_url
+
+        result = resolve_database_url(env_var="MY_DSN")
+        assert result == "postgresql://host/db"
+
+    def test_raises_runtime_error_when_unset(self, monkeypatch):
+        """RuntimeError raised when env var is unset."""
+        monkeypatch.delenv("MY_DSN", raising=False)
+        import pytest
+        from vds_platform_core.alembic.runtime import resolve_database_url
+
+        with pytest.raises(RuntimeError, match="MY_DSN"):
+            resolve_database_url(env_var="MY_DSN")
+
+    def test_raises_runtime_error_when_empty_string(self, monkeypatch):
+        """RuntimeError raised when env var is set to empty string."""
+        monkeypatch.setenv("MY_DSN", "")
+        import pytest
+        from vds_platform_core.alembic.runtime import resolve_database_url
+
+        with pytest.raises(RuntimeError, match="MY_DSN"):
+            resolve_database_url(env_var="MY_DSN")
+
+    def test_value_returned_verbatim_no_rewriting(self, monkeypatch):
+        """v2.15.12: no URL rewriting (force_psycopg_v3 removed); returned as-is."""
+        url = "postgresql+asyncpg://host/db"
+        monkeypatch.setenv("MY_DSN", url)
+        from vds_platform_core.alembic.runtime import resolve_database_url
+
+        result = resolve_database_url(env_var="MY_DSN")
+        assert result == url
+
+
+# ---------------------------------------------------------------------------
+# run_migrations_offline
+# ---------------------------------------------------------------------------
+
+
+class TestRunMigrationsOffline:
+    """Tests for run_migrations_offline."""
+
+    def _run(self, mock_context, *, schema, version_table_schema=None, **extra):
+        """Helper: patch alembic.context and call run_migrations_offline."""
+        from sqlalchemy import MetaData
+        from vds_platform_core.alembic.runtime import run_migrations_offline
+
+        include_name = _make_include_name()
+        kwargs = {
+            "target_metadata": MetaData(),
+            "schema": schema,
+            "url": "postgresql+psycopg://host/db",
+            "include_name": include_name,
+        }
+        if version_table_schema is not None:
+            kwargs["version_table_schema"] = version_table_schema
+        kwargs.update(extra)
+        run_migrations_offline(**kwargs)
+
+    def test_version_table_schema_defaults_to_schema(self):
+        """When version_table_schema omitted, it defaults to the schema argument."""
+        with patch("vds_platform_core.alembic.runtime.context") as mock_ctx:
+            mock_ctx.begin_transaction.return_value.__enter__ = MagicMock(return_value=None)
+            mock_ctx.begin_transaction.return_value.__exit__ = MagicMock(return_value=False)
+            self._run(mock_ctx, schema="memory")
+            configure_call = mock_ctx.configure.call_args
+            assert configure_call.kwargs["version_table_schema"] == "memory"
+
+    def test_explicit_version_table_schema_sched_preserved(self):
+        """Explicit version_table_schema='sched' overrides the default."""
+        with patch("vds_platform_core.alembic.runtime.context") as mock_ctx:
+            mock_ctx.begin_transaction.return_value.__enter__ = MagicMock(return_value=None)
+            mock_ctx.begin_transaction.return_value.__exit__ = MagicMock(return_value=False)
+            self._run(mock_ctx, schema="sched", version_table_schema="sched")
+            configure_call = mock_ctx.configure.call_args
+            assert configure_call.kwargs["version_table_schema"] == "sched"
+
+    def test_include_name_callable_wired(self):
+        """The include_name callable is passed through to context.configure."""
+        with patch("vds_platform_core.alembic.runtime.context") as mock_ctx:
+            mock_ctx.begin_transaction.return_value.__enter__ = MagicMock(return_value=None)
+            mock_ctx.begin_transaction.return_value.__exit__ = MagicMock(return_value=False)
+            from sqlalchemy import MetaData
+
+            fn = _make_include_name()
+            from vds_platform_core.alembic.runtime import run_migrations_offline
+
+            run_migrations_offline(
+                target_metadata=MetaData(),
+                schema="audit_state",
+                url="postgresql+psycopg://host/db",
+                include_name=fn,
+            )
+            configure_call = mock_ctx.configure.call_args
+            assert configure_call.kwargs["include_name"] is fn
+
+    def test_offline_configure_receives_url_and_literal_binds(self):
+        """context.configure receives url= and literal_binds=True for offline mode."""
+        with patch("vds_platform_core.alembic.runtime.context") as mock_ctx:
+            mock_ctx.begin_transaction.return_value.__enter__ = MagicMock(return_value=None)
+            mock_ctx.begin_transaction.return_value.__exit__ = MagicMock(return_value=False)
+            self._run(mock_ctx, schema="progress")
+            configure_kwargs = mock_ctx.configure.call_args.kwargs
+            assert configure_kwargs["url"] == "postgresql+psycopg://host/db"
+            assert configure_kwargs["literal_binds"] is True
+            assert configure_kwargs["include_schemas"] is True
+
+    def test_run_migrations_called_inside_transaction(self):
+        """context.run_migrations() is called inside begin_transaction context."""
+        with patch("vds_platform_core.alembic.runtime.context") as mock_ctx:
+            tx_ctx = MagicMock()
+            tx_ctx.__enter__ = MagicMock(return_value=None)
+            tx_ctx.__exit__ = MagicMock(return_value=False)
+            mock_ctx.begin_transaction.return_value = tx_ctx
+            self._run(mock_ctx, schema="memory")
+            mock_ctx.begin_transaction.assert_called_once()
+            mock_ctx.run_migrations.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# run_migrations_online
+# ---------------------------------------------------------------------------
+
+
+class TestRunMigrationsOnline:
+    """Tests for run_migrations_online."""
+
+    def _build_alembic_config(self):
+        """Build a minimal mock alembic config."""
+        cfg = MagicMock()
+        cfg.get_section.return_value = {}
+        cfg.config_ini_section = "alembic"
+        return cfg
+
+    def _run(self, mock_context, mock_engine_from_config, *, schema, version_table_schema=None):
+        """Helper: patch context + engine_from_config and call run_migrations_online."""
+        from sqlalchemy import MetaData
+        from vds_platform_core.alembic.runtime import run_migrations_online
+
+        mock_conn = MagicMock()
+        mock_conn.__enter__ = MagicMock(return_value=mock_conn)
+        mock_conn.__exit__ = MagicMock(return_value=False)
+        mock_engine = MagicMock()
+        mock_engine.connect.return_value = mock_conn
+        mock_engine_from_config.return_value = mock_engine
+
+        mock_tx = MagicMock()
+        mock_tx.__enter__ = MagicMock(return_value=None)
+        mock_tx.__exit__ = MagicMock(return_value=False)
+        mock_context.begin_transaction.return_value = mock_tx
+
+        alembic_cfg = self._build_alembic_config()
+
+        include_name = _make_include_name()
+        kwargs = {
+            "target_metadata": MetaData(),
+            "schema": schema,
+            "url": "postgresql+psycopg://host/db",
+            "include_name": include_name,
+            "alembic_config": alembic_cfg,
+        }
+        if version_table_schema is not None:
+            kwargs["version_table_schema"] = version_table_schema
+        run_migrations_online(**kwargs)
+        return mock_conn, mock_engine
+
+    def test_version_table_schema_defaults_to_schema_online(self):
+        """version_table_schema defaults to schema when not provided (online mode)."""
+        with (
+            patch("vds_platform_core.alembic.runtime.context") as mock_ctx,
+            patch("vds_platform_core.alembic.runtime.engine_from_config") as mock_efc,
+        ):
+            self._run(mock_ctx, mock_efc, schema="memory")
+            configure_kwargs = mock_ctx.configure.call_args.kwargs
+            assert configure_kwargs["version_table_schema"] == "memory"
+
+    def test_explicit_sched_version_table_schema_preserved_online(self):
+        """version_table_schema='sched' preserved from caller (WP-5.1 contract)."""
+        with (
+            patch("vds_platform_core.alembic.runtime.context") as mock_ctx,
+            patch("vds_platform_core.alembic.runtime.engine_from_config") as mock_efc,
+        ):
+            self._run(mock_ctx, mock_efc, schema="sched", version_table_schema="sched")
+            configure_kwargs = mock_ctx.configure.call_args.kwargs
+            assert configure_kwargs["version_table_schema"] == "sched"
+
+    def test_engine_from_config_called_with_url(self):
+        """engine_from_config is called with sqlalchemy.url injected."""
+        with (
+            patch("vds_platform_core.alembic.runtime.context") as mock_ctx,
+            patch("vds_platform_core.alembic.runtime.engine_from_config") as mock_efc,
+        ):
+            self._run(mock_ctx, mock_efc, schema="audit_state")
+            assert mock_efc.called
+            call_kwargs = mock_efc.call_args
+            # First positional arg is the config dict
+            config_dict = call_kwargs.args[0] if call_kwargs.args else call_kwargs.kwargs.get("configuration", {})
+            assert config_dict.get("sqlalchemy.url") == "postgresql+psycopg://host/db"
+
+    def test_context_configure_receives_connection(self):
+        """context.configure must receive connection= (not url=) in online mode."""
+        with (
+            patch("vds_platform_core.alembic.runtime.context") as mock_ctx,
+            patch("vds_platform_core.alembic.runtime.engine_from_config") as mock_efc,
+        ):
+            _conn, _ = self._run(mock_ctx, mock_efc, schema="progress")
+            configure_kwargs = mock_ctx.configure.call_args.kwargs
+            assert "connection" in configure_kwargs
+            assert "url" not in configure_kwargs
+
+    def test_no_set_search_path_executed_on_connection(self):
+        """connection.execute must NEVER be called with SET search_path.
+
+        ADR-INF-11 §SA2.0 Implicit-TX Gotcha: executing SET search_path outside
+        a transaction silently breaks the alembic_version CREATE/INSERT.
+        The helper must NEVER call connection.execute with any SET statement.
+        """
+        with (
+            patch("vds_platform_core.alembic.runtime.context") as mock_ctx,
+            patch("vds_platform_core.alembic.runtime.engine_from_config") as mock_efc,
+        ):
+            conn, _ = self._run(mock_ctx, mock_efc, schema="memory")
+            # Verify connection.execute was never called with SET search_path
+            for call_args in conn.execute.call_args_list:
+                args = call_args.args
+                if args:
+                    stmt = str(args[0])
+                    assert "SET search_path" not in stmt, (
+                        f"connection.execute called with SET search_path: {stmt!r}. "
+                        "ADR-INF-11 §SA2.0 Implicit-TX Gotcha forbids this."
+                    )
+
+    def test_include_schemas_true_in_online_configure(self):
+        """include_schemas=True must be in context.configure kwargs."""
+        with (
+            patch("vds_platform_core.alembic.runtime.context") as mock_ctx,
+            patch("vds_platform_core.alembic.runtime.engine_from_config") as mock_efc,
+        ):
+            self._run(mock_ctx, mock_efc, schema="audit_state")
+            configure_kwargs = mock_ctx.configure.call_args.kwargs
+            assert configure_kwargs.get("include_schemas") is True
+
+    def test_run_migrations_called_in_online_mode(self):
+        """context.run_migrations() called inside begin_transaction in online mode."""
+        with (
+            patch("vds_platform_core.alembic.runtime.context") as mock_ctx,
+            patch("vds_platform_core.alembic.runtime.engine_from_config") as mock_efc,
+        ):
+            self._run(mock_ctx, mock_efc, schema="sched")
+            mock_ctx.run_migrations.assert_called_once()

package/skills/vds-skill/runtime/platform_core/tests/test_auth.py

@@ -0,0 +1,84 @@
+"""Tests for vds_platform_core.http.auth — TSK-7.3b."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from vds_platform_core.http.auth import with_auth
+from vds_platform_core.protocols import HTTPClient
+
+
+class _StubClient:
+    def __init__(self) -> None:
+        self.last_get_kw: dict[str, Any] = {}
+        self.last_post_kw: dict[str, Any] = {}
+        self.closed = False
+
+    async def get(self, url: str, **kw: Any) -> dict[str, Any]:
+        self.last_get_kw = kw
+        return {}
+
+    async def post(self, url: str, **kw: Any) -> dict[str, Any]:
+        self.last_post_kw = kw
+        return {}
+
+    async def aclose(self) -> None:
+        self.closed = True
+
+
+class _TokenResolver:
+    def __init__(self, token: str | None) -> None:
+        self._token = token
+
+    def resolve(self) -> str | None:
+        return self._token
+
+
+def test_with_auth_returns_http_client() -> None:
+    """with_auth result satisfies the HTTPClient protocol."""
+    assert isinstance(with_auth(_StubClient(), _TokenResolver("tok")), HTTPClient)
+
+
+def test_with_auth_injects_default_authorization_header() -> None:
+    """Token injected into Authorization header on GET by default."""
+    stub = _StubClient()
+    asyncio.run(with_auth(stub, _TokenResolver("Bearer abc")).get("https://x.com"))
+    assert stub.last_get_kw["headers"]["Authorization"] == "Bearer abc"
+
+
+def test_with_auth_uses_custom_header_name() -> None:
+    """custom header_name is used instead of Authorization."""
+    stub = _StubClient()
+    asyncio.run(with_auth(stub, _TokenResolver("tok"), header_name="X-API-Key").get("https://x.com"))
+    assert stub.last_get_kw["headers"]["X-API-Key"] == "tok"
+
+
+def test_with_auth_none_resolver_skips_injection() -> None:
+    """When resolver returns None, no header is injected."""
+    stub = _StubClient()
+    asyncio.run(with_auth(stub, _TokenResolver(None)).get("https://x.com"))
+    assert "Authorization" not in stub.last_get_kw.get("headers", {})
+
+
+def test_with_auth_does_not_overwrite_existing_header() -> None:
+    """User-supplied Authorization header is preserved (setdefault semantics)."""
+    stub = _StubClient()
+    asyncio.run(
+        with_auth(stub, _TokenResolver("server-token")).get("https://x.com", headers={"Authorization": "user-token"})
+    )
+    assert stub.last_get_kw["headers"]["Authorization"] == "user-token"
+
+
+def test_with_auth_delegates_aclose() -> None:
+    """aclose() is forwarded to the underlying client."""
+    stub = _StubClient()
+    asyncio.run(with_auth(stub, _TokenResolver("tok")).aclose())
+    assert stub.closed is True
+
+
+def test_with_auth_injects_on_post() -> None:
+    """Header is also injected on POST requests."""
+    stub = _StubClient()
+    asyncio.run(with_auth(stub, _TokenResolver("tok")).post("https://x.com", json={"a": 1}))
+    assert stub.last_post_kw["headers"]["Authorization"] == "tok"

package/skills/vds-skill/runtime/platform_core/tests/test_config.py

@@ -0,0 +1,83 @@
+"""Tests for vds_platform_core.config."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic_settings.sources import DotEnvSettingsSource
+from vds_platform_core.config import VDS_BASE_SETTINGS_CONFIG, vds_settings_customise_sources
+
+
+class _DemoSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="DEMO__")
+    value: str = "default"
+
+
+class TestVDSBaseSettingsConfig:
+    def test_has_required_keys(self) -> None:
+        assert VDS_BASE_SETTINGS_CONFIG["env_file"] == "~/.vds/.env"
+        assert VDS_BASE_SETTINGS_CONFIG["dotenv_filtering"] == "match_prefix"
+        assert VDS_BASE_SETTINGS_CONFIG["env_nested_delimiter"] == "__"
+
+    def test_case_insensitive_flag(self) -> None:
+        """TSK-7.12a: case_sensitive=False must be present."""
+        assert VDS_BASE_SETTINGS_CONFIG["case_sensitive"] is False
+
+    def test_populate_by_name_flag(self) -> None:
+        """TSK-7.12a: populate_by_name=True must be present."""
+        assert VDS_BASE_SETTINGS_CONFIG["populate_by_name"] is True
+
+
+class TestSettingsCustomiseSources:
+    def test_returns_tuple_with_init_and_env_sources_first(self, tmp_path: Path) -> None:
+        env_file = tmp_path / ".env"
+        env_file.write_text("DEMO__VALUE=from-env\n", encoding="utf-8")
+
+        init_settings = object()
+        env_settings = object()
+        sources = vds_settings_customise_sources(
+            _DemoSettings,
+            init_settings,  # type: ignore[arg-type]
+            env_settings,  # type: ignore[arg-type]
+            object(),  # type: ignore[arg-type]
+            object(),  # type: ignore[arg-type]
+            env_paths=(env_file,),
+        )
+
+        assert isinstance(sources, tuple)
+        assert sources[0] is init_settings
+        assert sources[1] is env_settings
+
+    def test_custom_env_paths_add_dotenv_sources(self, tmp_path: Path) -> None:
+        env_file = tmp_path / "custom.env"
+        env_file.write_text("DEMO__VALUE=custom\n", encoding="utf-8")
+
+        sources = vds_settings_customise_sources(
+            _DemoSettings,
+            object(),  # type: ignore[arg-type]
+            object(),  # type: ignore[arg-type]
+            object(),  # type: ignore[arg-type]
+            object(),  # type: ignore[arg-type]
+            env_paths=(env_file,),
+        )
+        dotenv_sources = [source for source in sources if isinstance(source, DotEnvSettingsSource)]
+        assert len(dotenv_sources) == 1
+        assert Path(dotenv_sources[0].env_file) == env_file
+
+    def test_missing_env_paths_are_skipped(self, tmp_path: Path) -> None:
+        existing = tmp_path / "existing.env"
+        existing.write_text("DEMO__VALUE=ok\n", encoding="utf-8")
+        missing = tmp_path / "missing.env"
+
+        sources = vds_settings_customise_sources(
+            _DemoSettings,
+            object(),  # type: ignore[arg-type]
+            object(),  # type: ignore[arg-type]
+            object(),  # type: ignore[arg-type]
+            object(),  # type: ignore[arg-type]
+            env_paths=(missing, existing),
+        )
+        dotenv_sources = [source for source in sources if isinstance(source, DotEnvSettingsSource)]
+        assert len(dotenv_sources) == 1
+        assert Path(dotenv_sources[0].env_file) == existing

package/skills/vds-skill/runtime/platform_core/tests/test_credentials.py

@@ -0,0 +1,73 @@
+"""Tests for vds_platform_core.credentials — TSK-7.2."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pydantic import SecretStr
+from vds_platform_core.credentials import HeaderAuthResolver, resolve_secret
+
+if TYPE_CHECKING:
+    import pytest
+
+# ---------------------------------------------------------------------------
+# resolve_secret — 5 tests
+# ---------------------------------------------------------------------------
+
+
+def test_resolve_secret_secretstr() -> None:
+    """SecretStr is unwrapped to its plain string value."""
+    assert resolve_secret(SecretStr("abc")) == "abc"
+
+
+def test_resolve_secret_plain_str() -> None:
+    """Plain str passes through unchanged."""
+    assert resolve_secret("abc") == "abc"
+
+
+def test_resolve_secret_none() -> None:
+    """None returns None."""
+    assert resolve_secret(None) is None
+
+
+def test_resolve_secret_empty_str() -> None:
+    """Empty string is treated as absent and returns None."""
+    assert resolve_secret("") is None
+
+
+def test_resolve_secret_idempotent() -> None:
+    """resolve_secret applied twice is identical to applying it once."""
+    once = resolve_secret(SecretStr("x"))
+    twice = resolve_secret(once)
+    assert once == twice == "x"
+    # Nested-call form confirms idempotency in one expression:
+    assert resolve_secret(resolve_secret(SecretStr("x"))) == resolve_secret(SecretStr("x")) == "x"
+
+
+# ---------------------------------------------------------------------------
+# HeaderAuthResolver — 3 tests
+# ---------------------------------------------------------------------------
+
+
+def test_header_auth_resolver_attributes() -> None:
+    """Constructor stores token_field and header_name."""
+    resolver = HeaderAuthResolver(token_field="X-Token", header_name="Authorization")
+    assert resolver.token_field == "X-Token"
+    assert resolver.header_name == "Authorization"
+
+
+def test_header_auth_resolver_resolve_from_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    """resolve() returns the token value found in environment."""
+    monkeypatch.setenv("VDS_TEST_TOKEN", "bearer-abc")
+    resolver = HeaderAuthResolver(token_field="VDS_TEST_TOKEN", header_name="Authorization")
+    assert resolver.resolve() == "bearer-abc"
+
+
+def test_header_auth_resolver_resolve_missing_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    """resolve() returns None when the env var is not set."""
+    monkeypatch.delenv("VDS_MISSING_TOKEN_XYZ", raising=False)
+    resolver = HeaderAuthResolver(
+        token_field="VDS_MISSING_TOKEN_XYZ",
+        header_name="X-Api-Key",
+    )
+    assert resolver.resolve() is None

package/skills/vds-skill/runtime/platform_core/tests/test_env.py

@@ -0,0 +1,56 @@
+"""Tests for vds_platform_core.env — TSK-7.12b."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import vds_platform_core.env as _env_mod
+from vds_platform_core.env import DEFAULT_ENV_PATHS
+
+if TYPE_CHECKING:
+    import pytest
+
+
+def test_default_env_paths_is_tuple() -> None:
+    """DEFAULT_ENV_PATHS is a non-empty tuple of Path objects."""
+    assert isinstance(DEFAULT_ENV_PATHS, tuple)
+    assert len(DEFAULT_ENV_PATHS) == 1
+    assert isinstance(DEFAULT_ENV_PATHS[0], Path)
+
+
+def test_default_env_paths_default_is_vds_dot_env() -> None:
+    """Without env overrides, path is ~/.vds/.env."""
+    path = (
+        _env_mod._vds_env_path.__wrapped__()
+        if hasattr(_env_mod._vds_env_path, "__wrapped__")
+        else _env_mod._vds_env_path()
+    )
+    assert path == Path.home() / ".vds" / ".env"
+
+
+def test_vds_env_file_override(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    """VDS_ENV_FILE env var is honoured."""
+    custom = tmp_path / "custom.env"
+    monkeypatch.setenv("VDS_ENV_FILE", str(custom))
+    assert _env_mod._vds_env_path() == custom.resolve()
+
+
+def test_vds_config_dir_override(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    """VDS_CONFIG_DIR env var shifts the root directory."""
+    monkeypatch.delenv("VDS_ENV_FILE", raising=False)
+    monkeypatch.setenv("VDS_CONFIG_DIR", str(tmp_path))
+    assert _env_mod._vds_env_path() == tmp_path.resolve() / ".env"
+
+
+def test_vds_env_file_takes_precedence_over_config_dir(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    """VDS_ENV_FILE wins over VDS_CONFIG_DIR when both are set."""
+    custom = tmp_path / "direct.env"
+    monkeypatch.setenv("VDS_ENV_FILE", str(custom))
+    monkeypatch.setenv("VDS_CONFIG_DIR", str(tmp_path / "other"))
+    assert _env_mod._vds_env_path() == custom.resolve()
+
+
+def test_default_env_paths_exported_in_all() -> None:
+    """DEFAULT_ENV_PATHS is listed in __all__."""
+    assert "DEFAULT_ENV_PATHS" in _env_mod.__all__