pz-cli 5.0.0__py3-none-any.whl

pz_core/assembly/settings/compiler.py

@@ -0,0 +1,786 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from pathlib import Path
+import tomllib
+from typing import TYPE_CHECKING, Any
+
+from pz_core.assembly.app_discovery import (
+    discover_declared_app_references,
+    resolve_declared_app_import_roots,
+    resolve_declared_app_id,
+    resolve_package_root,
+)
+from pz_core.assembly.project import active_project_import_root
+from pz_core.assembly.settings.host_project_overrides import (
+    apply_host_project_env_overrides,
+)
+from pz_core.core.errors import PzError
+from pz_core.runtime.environment_integrity import (
+    validate_installed_app_identities,
+    validate_process_environment,
+    validate_project_config_identity,
+)
+from pz_core.utils import PROJECT_JSONC_NAME, iter_env_items, load_jsonc_file
+if TYPE_CHECKING:
+    from pz_core.assembly.project import ProjectContext
+
+
+PROJECT_JSONC_FILE_NAME = PROJECT_JSONC_NAME
+DEFAULT_PZ_ENV_NAME = "develop"
+PZ_ENV_SELECTOR_ENV_NAME = "PZ_ENV"
+_LEGACY_ENV_FIELD = "pyz" + "za_env"
+
+
+def _normalize_env_value(value: Any) -> Any:
+    if not isinstance(value, str):
+        return value
+    text = value.strip()
+    if not text:
+        return text
+    if text[:1] in {"'", '"'} and text[-1:] == text[:1] and len(text) >= 2:
+        return text[1:-1]
+    return text
+
+
+def _read_dotenv(path: Path) -> dict[str, str]:
+    data: dict[str, str] = {}
+    if not path.is_file():
+        return data
+    for line_number, raw_line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[7:].strip()
+        if "=" not in line:
+            raise PzError(
+                code="PZ_DOTENV_INVALID",
+                message=f"Invalid .env entry at line {line_number}: missing '=' delimiter.",
+                stage="settings",
+                owner="runtime.settings",
+                action="read_dotenv",
+            )
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        if not key:
+            raise PzError(
+                code="PZ_DOTENV_INVALID",
+                message=f"Invalid .env entry at line {line_number}: key must be non-empty.",
+                stage="settings",
+                owner="runtime.settings",
+                action="read_dotenv",
+            )
+        if value[:1] in {"'", '"'}:
+            quote = value[0]
+            end_index = value.find(quote, 1)
+            if end_index == -1:
+                raise PzError(
+                    code="PZ_DOTENV_INVALID",
+                    message=f"Invalid .env entry at line {line_number}: unterminated quoted value.",
+                    stage="settings",
+                    owner="runtime.settings",
+                    action="read_dotenv",
+                )
+            trailing = value[end_index + 1 :].strip()
+            if trailing and not trailing.startswith("#"):
+                raise PzError(
+                    code="PZ_DOTENV_INVALID",
+                    message=f"Invalid .env entry at line {line_number}: unexpected trailing characters.",
+                    stage="settings",
+                    owner="runtime.settings",
+                    action="read_dotenv",
+                )
+            value = value[1:end_index]
+        elif " #" in value:
+            value = value.split(" #", 1)[0].rstrip()
+        if key in data:
+            raise PzError(
+                code="PZ_DOTENV_INVALID",
+                message=f"Invalid .env entry at line {line_number}: duplicate key '{key}'.",
+                stage="settings",
+                owner="runtime.settings",
+                action="read_dotenv",
+            )
+        data[key] = value
+    return data
+
+
+def _explicit_pz_env_snapshot() -> dict[str, str]:
+    snapshot = {
+        str(key): str(_normalize_env_value(value))
+        for key, value in iter_env_items()
+    }
+    validate_process_environment(snapshot)
+    return snapshot
+
+
+def _pz_env_env_file_path(project: "ProjectContext", pz_env: str | None) -> Path | None:
+    pz_env_name = str(pz_env or "").strip()
+    if not pz_env_name:
+        return None
+    return project.project_dir / f".env.{pz_env_name}"
+
+
+def load_project_env_file(
+    project: "ProjectContext",
+    *,
+    pz_env: str | None = None,
+) -> dict[str, str]:
+    if pz_env is None:
+        pz_env = _resolve_pz_env_name(_explicit_pz_env_snapshot())
+    payload = {
+        str(key): str(_normalize_env_value(value))
+        for key, value in _read_dotenv(project.env_file_path).items()
+    }
+    env_file_path = _pz_env_env_file_path(project, pz_env)
+    if env_file_path is not None:
+        for key, value in _read_dotenv(env_file_path).items():
+            payload[str(key)] = str(_normalize_env_value(value))
+    validate_process_environment(payload)
+    return payload
+
+
+def _deep_merge(base: dict[str, Any], incoming: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(base)
+    for key, value in incoming.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = _deep_merge(merged[key], value)
+            continue
+        merged[key] = value
+    return merged
+
+
+def _read_required_string(
+    value: Any,
+    *,
+    code: str,
+    message: str,
+    owner: str,
+    action: str,
+) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise PzError(
+            code=code,
+            message=message,
+            stage="settings",
+            owner=owner,
+            action=action,
+        )
+    return value.strip()
+
+
+def _read_app_module_path(
+    value: Any,
+    *,
+    owner: str,
+    action: str,
+) -> str:
+    normalized = _read_required_string(
+        value,
+        code="PZ_APP_PATH_INVALID",
+        message="App module path must be declared as a non-empty string.",
+        owner=owner,
+        action=action,
+    )
+    if ":" in normalized or normalized.endswith(".apps"):
+        raise PzError(
+            code="PZ_APP_PATH_INVALID",
+            message=(
+                f"App path '{normalized}' must declare a directory/package name only; "
+                "installed_apps does not accept '<pkg>.apps' or '<pkg>.apps:app'."
+            ),
+            stage="settings",
+            owner=owner,
+            action=action,
+        )
+    return normalized
+
+
+def _read_optional_pz_env_name(
+    value: Any,
+    *,
+    owner: str,
+    action: str,
+) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value.strip():
+        raise PzError(
+            code="PZ_ENV_INVALID",
+            message="pz_env must be declared as a non-empty string when configured.",
+            stage="settings",
+            owner=owner,
+            action=action,
+        )
+    return value.strip()
+
+
+def _package_root(module_path: str) -> Path | None:
+    return resolve_package_root(
+        _read_app_module_path(
+            module_path,
+            owner="settings",
+            action="package_root",
+        )
+    )
+
+
+def _resolve_pz_env_name(env: dict[str, str]) -> str:
+    selected = _read_optional_pz_env_name(
+        env.get(PZ_ENV_SELECTOR_ENV_NAME),
+        owner=PZ_ENV_SELECTOR_ENV_NAME,
+        action="compile_settings_snapshot",
+    )
+    if selected is None:
+        return DEFAULT_PZ_ENV_NAME
+    return selected
+
+
+def _is_non_empty_mapping(payload: dict[str, Any]) -> bool:
+    return bool(payload)
+
+
+def _read_project_root_config(project: "ProjectContext") -> dict[str, Any]:
+    if not project.project_config_path.is_file():
+        return {}
+    return load_jsonc_file(
+        project.project_config_path,
+        code="PZ_PROJECT_CONFIG_INVALID",
+        owner="runtime.settings",
+        action="read_project_config",
+    )
+
+
+def _reject_legacy_pz_env_selectors(
+    data: dict[str, Any],
+    *,
+    action: str,
+    selected_pz_env: str | None = None,
+) -> None:
+    legacy_paths: list[str] = []
+    if "environment" in data:
+        legacy_paths.append("environment")
+    if _LEGACY_ENV_FIELD in data:
+        legacy_paths.append(_LEGACY_ENV_FIELD)
+    if "pz_env" in data:
+        legacy_paths.append("pz_env")
+    project = data.get("project")
+    if isinstance(project, dict):
+        if "environment" in project:
+            legacy_paths.append("project.environment")
+        project_pz_env = project.get("pz_env")
+        allow_derived_project_pz_env = (
+            selected_pz_env is not None
+            and str(project_pz_env).strip() == str(selected_pz_env).strip()
+        )
+        if _LEGACY_ENV_FIELD in project:
+            legacy_paths.append(f"project.{_LEGACY_ENV_FIELD}")
+        if "pz_env" in project and not allow_derived_project_pz_env:
+            legacy_paths.append("project.pz_env")
+        if "env" in project:
+            legacy_paths.append("project.env")
+    if legacy_paths:
+        joined = ", ".join(f"`{item}`" for item in legacy_paths)
+        raise PzError(
+            code="PZ_PROJECT_CONFIG_INVALID",
+            message=f"Project environment selector keys are not allowed: {joined}. Use `PZ_ENV` instead.",
+            stage="settings",
+            owner="runtime.settings",
+            action=action,
+        )
+
+
+def _apply_project_http_runtime_settings(project: dict[str, Any]) -> None:
+    pz_env = str(project.get("pz_env") or DEFAULT_PZ_ENV_NAME).strip().lower()
+    declared_http = project.get("http")
+    http_payload = dict(declared_http) if isinstance(declared_http, dict) else {}
+    defaults: dict[str, Any]
+    if pz_env == "product":
+        defaults = {
+            "openapi_url": None,
+            "docs_url": None,
+            "redoc_url": None,
+        }
+    else:
+        defaults = {
+            "openapi_url": "/openapi.json",
+            "docs_url": "/docs",
+            "redoc_url": "/redoc",
+        }
+    project["http"] = _deep_merge(defaults, http_payload)
+
+
+def _pz_env_config_candidates(project: "ProjectContext", pz_env: str) -> tuple[Path, ...]:
+    pz_env_name = str(pz_env or "").strip()
+    if not pz_env_name:
+        return tuple()
+    return (project.project_dir / f"pz.{pz_env_name}.jsonc",)
+
+
+def _read_pz_env_override_config(project: "ProjectContext", pz_env: str) -> dict[str, Any]:
+    validate_project_config_identity(project.project_dir)
+    for path in _pz_env_config_candidates(project, pz_env):
+        payload = load_jsonc_file(
+            path,
+            code="PZ_PROJECT_CONFIG_INVALID",
+            owner="runtime.settings",
+            action="read_pz_env_config",
+        )
+        if payload:
+            return payload
+    return {}
+
+
+def _parse_env_value(raw: str) -> Any:
+    if not isinstance(raw, str):
+        raise PzError(
+            code="ENV_VALUE_INVALID",
+            message="Env override value must be a string.",
+            stage="settings",
+            owner="runtime.settings",
+            action="parse_env_value",
+        )
+    value = raw.strip()
+    lowered = value.lower()
+    if lowered == "true":
+        return True
+    if lowered == "false":
+        return False
+    if lowered == "null":
+        return None
+    if value.startswith("[") or value.startswith("{") or value.startswith('"') or value.startswith("'"):
+        try:
+            return tomllib.loads(f"v = {value}")["v"]
+        except Exception as exc:
+            if value.startswith("[") or value.startswith("{"):
+                try:
+                    return json.loads(value)
+                except Exception:
+                    pass
+            raise PzError(
+                code="ENV_VALUE_INVALID",
+                message="Env override value looks structured but could not be parsed.",
+                stage="settings",
+                owner="runtime.settings",
+                action="parse_env_value",
+            ) from exc
+    try:
+        return int(value)
+    except ValueError:
+        pass
+    try:
+        return float(value)
+    except ValueError:
+        pass
+    return value
+
+
+def _set_nested(mapping: dict[str, Any], path: tuple[str, ...], value: Any) -> None:
+    def _resolve_existing_key(current: dict[str, Any], key: str) -> str:
+        if key in current:
+            return key
+        lowered = str(key).lower()
+        for existing in current.keys():
+            if isinstance(existing, str) and existing.lower() == lowered:
+                return existing
+        return key
+
+    current = mapping
+    for key in path[:-1]:
+        resolved_key = _resolve_existing_key(current, key)
+        child = current.get(resolved_key)
+        if not isinstance(child, dict):
+            child = {}
+            current[resolved_key] = child
+        current = child
+    current[_resolve_existing_key(current, path[-1])] = value
+
+
+_CANONICAL_TOP_LEVEL_ENV_FIELDS: dict[str, tuple[str, ...]] = {
+    "cache_dir": ("cache_dir",),
+    "runtime_dir": ("runtime_dir",),
+    "site_theme": ("site_theme",),
+    "site_theme_by_lang": ("site_theme_by_lang",),
+    "site_theme_by_country": ("site_theme_by_country",),
+}
+
+_TOP_LEVEL_SECTION_PREFIXES = (
+    "project",
+    "routing",
+)
+
+
+def _read_top_level_env_override_path(key: str, *, owner: str) -> tuple[str, ...]:
+    nested_path: list[str] = []
+    for index, raw_part in enumerate(key.split("__")):
+        if not isinstance(raw_part, str):
+            raise PzError(
+                code="ENV_KEY_INVALID",
+                message=f"Env override path for '{owner}' must use string segments.",
+                stage="settings",
+                owner=owner,
+                action="compile_settings_snapshot",
+            )
+        part = raw_part.strip().lower()
+        if not part:
+            raise PzError(
+                code="ENV_KEY_INVALID",
+                message=f"Env override path for '{owner}' contains an empty segment at index {index}.",
+                stage="settings",
+                owner=owner,
+                action="compile_settings_snapshot",
+            )
+        nested_path.append(part)
+    return tuple(nested_path)
+
+
+def _apply_top_level_env_overrides(data: dict[str, Any], env: dict[str, str]) -> None:
+    for key, path in _CANONICAL_TOP_LEVEL_ENV_FIELDS.items():
+        raw_value = env.get(key)
+        if raw_value is None:
+            continue
+        _set_nested(data, path, _parse_env_value(raw_value))
+
+    for prefix in _TOP_LEVEL_SECTION_PREFIXES:
+        token = prefix + "__"
+        for key, raw_value in env.items():
+            if not key.startswith(token):
+                continue
+            nested = _read_top_level_env_override_path(key[len(token) :], owner=prefix)
+            _set_nested(data, (prefix,) + nested, _parse_env_value(raw_value))
+
+
+def _read_env_override_path(key: str, *, app_id: str) -> tuple[str, ...]:
+    nested_path: list[str] = []
+    for index, raw_part in enumerate(key.split("__")):
+        if not isinstance(raw_part, str):
+            raise PzError(
+                code="PZ_APP_ENV_KEY_INVALID",
+                message=f"Env override path for app '{app_id}' must use string segments.",
+                stage="settings",
+                owner=app_id,
+                action="compile_settings_snapshot",
+            )
+        part = raw_part.strip().lower()
+        if not part:
+            raise PzError(
+                code="PZ_APP_ENV_KEY_INVALID",
+                message=(
+                    f"Env override path for app '{app_id}' contains an empty segment "
+                    f"at index {index}."
+                ),
+                stage="settings",
+                owner=app_id,
+                action="compile_settings_snapshot",
+            )
+        nested_path.append(part)
+    return tuple(nested_path)
+
+
+def _configured_app_settings_map(data: dict[str, Any]) -> dict[str, Any]:
+    configured_apps = data.get("apps")
+    if configured_apps is None:
+        return {}
+    if isinstance(configured_apps, dict):
+        return dict(configured_apps)
+    raise PzError(
+        code="PZ_APPS_NAMESPACE_INVALID",
+        message="apps must be declared as a table keyed by app_id.",
+        stage="settings",
+        owner="apps",
+        action="compile_settings_snapshot",
+    )
+
+
+def _try_app_id_from_module_path(module_path: str) -> str | None:
+    normalized = _read_app_module_path(
+        module_path,
+        owner="installed_apps",
+        action="compile_settings_snapshot",
+    )
+    package_root = _package_root(normalized)
+    try:
+        app_id = resolve_declared_app_id(normalized)
+    except PzError as exc:
+        if exc.code == "PZ_APP_IMPORT_FAILED":
+            if package_root is None:
+                return None
+        raise
+    return app_id or None
+
+
+def _merge_app_settings(
+    configured_map: dict[str, Any],
+    env: dict[str, str],
+    installed_apps: tuple[str, ...],
+) -> dict[str, dict[str, Any]]:
+    app_settings: dict[str, dict[str, Any]] = {}
+    candidate_app_ids: list[str] = []
+    module_paths_by_app_id: dict[str, list[str]] = {}
+
+    for module_path in installed_apps:
+        normalized = _read_app_module_path(
+            module_path,
+            owner="installed_apps",
+            action="compile_settings_snapshot",
+        )
+        app_id = _try_app_id_from_module_path(normalized)
+        if app_id is None:
+            continue
+        if app_id not in candidate_app_ids:
+            candidate_app_ids.append(app_id)
+        bucket = module_paths_by_app_id.setdefault(app_id, [])
+        if normalized not in bucket:
+            bucket.append(normalized)
+    for app_id in configured_map:
+        if app_id not in candidate_app_ids:
+            candidate_app_ids.append(app_id)
+
+    for app_id in candidate_app_ids:
+        explicit = configured_map.get(app_id)
+        if explicit is None:
+            app_settings.setdefault(app_id, {})
+        elif isinstance(explicit, dict):
+            app_settings[app_id] = _deep_merge(app_settings.get(app_id, {}), explicit)
+        else:
+            raise PzError(
+                code="PZ_APP_SETTINGS_ENTRY_INVALID",
+                message=f"apps.{app_id} must be declared as a table.",
+                stage="settings",
+                owner=app_id,
+                action="compile_settings_snapshot",
+            )
+
+    for key, raw_value in env.items():
+        for app_id in tuple(app_settings.keys()):
+            prefix = app_id.replace("-", "_") + "__"
+            if not key.startswith(prefix):
+                continue
+            nested_path = _read_env_override_path(key[len(prefix):], app_id=app_id)
+            if nested_path:
+                _set_nested(app_settings.setdefault(app_id, {}), nested_path, _parse_env_value(raw_value))
+    return {app_id: dict(values) for app_id, values in app_settings.items()}
+
+
+def _resolve_declared_installed_apps(data: dict[str, Any]) -> tuple[str, ...]:
+    raw = data.get("installed_apps")
+    if raw in (None, (), []):
+        return tuple()
+    if not isinstance(raw, (list, tuple)):
+        raise PzError(
+            code="PZ_INSTALLED_APPS_INVALID",
+            message="installed_apps must be declared as an array of app module paths.",
+            stage="settings",
+            owner="installed_apps",
+            action="compile_settings_snapshot",
+        )
+    declared_apps: list[str] = []
+    for index, item in enumerate(raw):
+        declared_apps.append(
+            _read_required_string(
+                item,
+                code="PZ_APP_PATH_INVALID",
+                message=f"installed_apps[{index}] must declare a non-empty string app module path.",
+                owner="installed_apps",
+                action="compile_settings_snapshot",
+            )
+        )
+    resolved = tuple(declared_apps)
+    validate_installed_app_identities(resolved)
+    return resolved
+
+
+def _resolve_installed_apps(
+    declared_apps: tuple[str, ...],
+    *,
+    project_dir: Path,
+) -> tuple[str, ...]:
+    return tuple(
+        item.module_path
+        for item in discover_declared_app_references(declared_apps, project_dir=project_dir)
+    )
+
+
+def _resolve_import_roots(
+    declared_apps: tuple[str, ...],
+    *,
+    project_dir: Path,
+) -> tuple[Path, ...]:
+    return resolve_declared_app_import_roots(declared_apps, project_dir=project_dir)
+
+
+def _resolve_app_replacements(data: dict[str, Any]) -> dict[str, str]:
+    raw = data.get("app_replacements")
+    if raw is None and isinstance(data.get("core"), dict):
+        raw = data["core"].get("app_replacements")
+    if raw in (None, {}):
+        return {}
+    if not isinstance(raw, dict):
+        raise PzError(
+            code="PZ_APP_REPLACEMENTS_INVALID",
+            message="app_replacements must be declared as a table of source to replacement paths.",
+            stage="settings",
+            owner="app_replacements",
+            action="compile_settings_snapshot",
+        )
+    out: dict[str, str] = {}
+    for source, target in raw.items():
+        src = _read_required_string(
+            source,
+            code="PZ_APP_REPLACEMENT_ENTRY_INVALID",
+            message="app_replacements entries must declare source as a non-empty string path.",
+            owner="app_replacements",
+            action="compile_settings_snapshot",
+        )
+        dst = _read_required_string(
+            target,
+            code="PZ_APP_REPLACEMENT_ENTRY_INVALID",
+            message="app_replacements entries must declare replacement as a non-empty string path.",
+            owner="app_replacements",
+            action="compile_settings_snapshot",
+        )
+        out[src] = dst
+    return out
+
+
+@dataclass(frozen=True, slots=True)
+class SettingsSnapshot:
+    project_dir: Path
+    data: dict[str, Any]
+    installed_apps: tuple[str, ...]
+    app_replacements: dict[str, str]
+    apps: dict[str, dict[str, Any]]
+    declared_installed_apps: tuple[str, ...] = ()
+    import_roots: tuple[Path, ...] = ()
+
+    def get(self, *path: str, default: Any = None) -> Any:
+        current: Any = self.data
+        for key in path:
+            if not isinstance(current, dict):
+                return default
+            current = current.get(key)
+        return current if current is not None else default
+
+    def with_installed_apps(self, installed_apps: tuple[str, ...]) -> "SettingsSnapshot":
+        declared_apps: list[str] = []
+        for index, item in enumerate(installed_apps):
+            normalized = _read_required_string(
+                item,
+                code="PZ_APP_PATH_INVALID",
+                message=f"installed_apps[{index}] must declare a non-empty string app module path.",
+                owner="installed_apps",
+                action="with_installed_apps",
+            )
+            declared_apps.append(normalized)
+        validate_installed_app_identities(declared_apps)
+        normalized_apps = _resolve_installed_apps(tuple(declared_apps), project_dir=self.project_dir)
+        validate_installed_app_identities(normalized_apps)
+        import_roots = _resolve_import_roots(tuple(declared_apps), project_dir=self.project_dir)
+        with active_project_import_root(self.project_dir, extra_import_roots=import_roots):
+            app_settings = _merge_app_settings(
+                dict(self.apps),
+                {},
+                tuple(normalized_apps),
+            )
+        data = dict(self.data)
+        data["apps"] = app_settings
+        return SettingsSnapshot(
+            project_dir=self.project_dir,
+            data=data,
+            installed_apps=tuple(normalized_apps),
+            import_roots=tuple(import_roots),
+            app_replacements=dict(self.app_replacements),
+            apps=app_settings,
+            declared_installed_apps=tuple(declared_apps),
+        )
+
+    def app_settings(self, app_id: str) -> dict[str, Any]:
+        return dict(self.apps.get(app_id, {}))
+
+
+def compile_settings_snapshot_from_payload(
+    project_dir: Path | str,
+    payload: dict[str, Any],
+    *,
+    env: dict[str, str] | None = None,
+    selected_pz_env: str | None = None,
+) -> SettingsSnapshot:
+    resolved_project_dir = Path(project_dir).expanduser().resolve()
+    merged = _deep_merge({}, payload)
+    _reject_legacy_pz_env_selectors(
+        merged,
+        action="compile_settings_snapshot",
+        selected_pz_env=selected_pz_env,
+    )
+
+    env_snapshot = {
+        str(key): str(_normalize_env_value(value))
+        for key, value in dict(env or {}).items()
+        if value is not None
+    }
+    validate_process_environment(env_snapshot)
+    _apply_top_level_env_overrides(merged, env_snapshot)
+    apply_host_project_env_overrides(merged, env_snapshot)
+
+    declared_installed_apps = _resolve_declared_installed_apps(merged)
+    configured_apps = _configured_app_settings_map(merged)
+    installed_apps = _resolve_installed_apps(declared_installed_apps, project_dir=resolved_project_dir)
+    validate_installed_app_identities(installed_apps)
+    import_roots = _resolve_import_roots(declared_installed_apps, project_dir=resolved_project_dir)
+    app_replacements = _resolve_app_replacements(merged)
+    if selected_pz_env:
+        project_namespace = merged.get("project")
+        if not isinstance(project_namespace, dict):
+            project_namespace = {}
+            merged["project"] = project_namespace
+        project_namespace["pz_env"] = selected_pz_env
+    project_namespace = merged.get("project")
+    if not isinstance(project_namespace, dict):
+        project_namespace = {}
+        merged["project"] = project_namespace
+    _apply_project_http_runtime_settings(project_namespace)
+    with active_project_import_root(resolved_project_dir, extra_import_roots=import_roots):
+        app_settings = _merge_app_settings(
+            configured_apps,
+            env_snapshot,
+            installed_apps,
+        )
+    merged["apps"] = app_settings
+    return SettingsSnapshot(
+        project_dir=resolved_project_dir,
+        data=dict(merged),
+        installed_apps=installed_apps,
+        import_roots=import_roots,
+        app_replacements=dict(app_replacements),
+        apps=app_settings,
+        declared_installed_apps=declared_installed_apps,
+    )
+
+
+def compile_settings_snapshot(project: "ProjectContext") -> SettingsSnapshot:
+    explicit_env_snapshot = _explicit_pz_env_snapshot()
+    pz_env = _resolve_pz_env_name(explicit_env_snapshot)
+
+    env_snapshot = load_project_env_file(project, pz_env=pz_env)
+    for key, value in explicit_env_snapshot.items():
+        env_snapshot[key] = _normalize_env_value(value)
+
+    merged: dict[str, Any] = _read_project_root_config(project)
+    _reject_legacy_pz_env_selectors(merged, action="read_project_config")
+
+    merged = _deep_merge(merged, _read_pz_env_override_config(project, pz_env))
+    project_namespace = merged.get("project")
+    if not isinstance(project_namespace, dict):
+        project_namespace = {}
+        merged["project"] = project_namespace
+    project_namespace["pz_env"] = pz_env
+
+    return compile_settings_snapshot_from_payload(
+        project.project_dir,
+        merged,
+        env={key: str(value) for key, value in env_snapshot.items()},
+        selected_pz_env=pz_env,
+    )