pz-cli 5.0.0__py3-none-any.whl

pz_core/authoring/project_settings_service.py

@@ -0,0 +1,1700 @@
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import shutil
+import time
+from collections.abc import Callable
+from contextlib import AbstractContextManager
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from pz_core.assembly.apps import compile_app_registry, compile_conventional_app_order, merge_explicit_app_order
+from pz_core.assembly.middlewares import compile_conventional_middleware_manifest, merge_explicit_middleware_order
+from pz_core.assembly.settings import compile_settings_snapshot_from_payload
+from pz_core.assembly.project import active_project_import_root
+from pz_core.runtime.discovery import (
+    discover_declared_app_references,
+    discover_leaf_app_packages,
+    import_app_settings_module,
+    resolve_declared_app_id,
+    resolve_import_roots_for_app_references,
+    resolve_package_root,
+)
+from pz_core.runtime.errors import PzError
+from pz_core.runtime.settings import active_settings_project
+from pz_core.utils.project_jsonc import PROJECT_JSONC_NAME, dump_jsonc_document, load_jsonc_file, load_jsonc_text
+from .templates.project.project_env import project_env_template
+from .templates.project.pz_env_env import pz_env_env_template
+from .templates.project.pz_env_jsonc import (
+    _annotate_project_base_url_comment,
+    pz_env_jsonc_template,
+)
+from .project_defaults import load_project_default_jsonc_payload
+from .scaffold_service import render_project_agents_file_text, write_project_agents_file
+
+
+try:  # pragma: no cover - fcntl is unavailable on some platforms.
+    import fcntl
+except Exception:  # pragma: no cover
+    fcntl = None  # type: ignore[assignment]
+
+
+_OWNER = "pz_core.authoring.project_settings"
+_MANAGED_PATHS = ("installed_apps", "middlewares")
+_UPDATE_BACKUP_DIRNAME = "pz-update-settings"
+_UPDATE_BACKUP_DEFAULT_KEEP_COUNT = 15
+_UPDATE_LOCK_NAME = "settings-update.lock"
+_ROOT_ENV_REDIRECTS: dict[tuple[str, ...], str] = {}
+_SECRET_TEMPLATE_KEY_TOKENS = ("password", "secret", "token", "key", "webhook")
+_SECRET_GENERATOR_PREFIX = "@pz:secret"
+_ROUTING_DEFAULT_KEYS = frozenset({"default_language", "all_supported_languages", "language_aliases"})
+_ROOT_DEFAULT_REFRESH_KEYS = frozenset({"commands"})
+_PZ_ENV_SETTINGS_TEMPLATES = {
+    "pz.develop.jsonc": lambda: pz_env_jsonc_template("develop"),
+    "pz.test.jsonc": lambda: pz_env_jsonc_template("test"),
+    "pz.product.jsonc": lambda: pz_env_jsonc_template("product"),
+}
+_PZ_ENV_ENV_TEMPLATES = {
+    ".env": project_env_template,
+    ".env.develop": lambda: pz_env_env_template("develop"),
+    ".env.test": lambda: pz_env_env_template("test"),
+    ".env.product": lambda: pz_env_env_template("product"),
+}
+
+
+SettingsPayloadNormalizer = Callable[[dict[str, Any]], dict[str, Any]]
+
+
+@dataclass(frozen=True, slots=True)
+class AppSettingsSource:
+    module_path: str
+    app_id: str
+    defaults: dict[str, Any]
+    normalize: SettingsPayloadNormalizer | None = None
+    secret_template: str = ""
+    root_defaults: dict[str, Any] | None = None
+    comments: dict[tuple[str, ...], tuple[str, ...]] | None = None
+    root_comments: dict[tuple[str, ...], tuple[str, ...]] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SettingsWriteResult:
+    path: Path
+    module_paths: tuple[str, ...]
+    created: bool
+
+
+@dataclass(frozen=True, slots=True)
+class SettingsUpdateDriftResult:
+    project_dir: Path
+    required: bool
+    changed_paths: tuple[Path, ...]
+    module_paths: tuple[str, ...]
+    command: str
+
+
+@dataclass(frozen=True, slots=True)
+class _SettingsUpdateDryRun:
+    project_dir: Path
+    config_path: Path
+    current_payload: dict[str, Any]
+    next_payload: dict[str, Any]
+    discovered_sources: tuple[AppSettingsSource, ...]
+    selected_sources: tuple[AppSettingsSource, ...]
+    root_env_assignments: dict[str, str]
+
+
+def discover_settings_sources(
+    project_dir: str | Path | None = None,
+    *,
+    include_project_apps_container: bool = False,
+) -> tuple[AppSettingsSource, ...]:
+    resolved_project_dir = _resolve_existing_project_dir(project_dir) if project_dir is not None else None
+    refs = discover_declared_app_references(
+        _declared_app_entries(
+            resolved_project_dir,
+            include_project_apps_container=include_project_apps_container,
+        ),
+        project_dir=resolved_project_dir,
+    )
+    import_roots = resolve_import_roots_for_app_references(refs)
+    with active_project_import_root(resolved_project_dir, extra_import_roots=import_roots):
+        source_pairs = [(item, _build_settings_source(item.module_path)) for item in refs]
+    sources = _dedupe_settings_sources_by_app_id(
+        resolved_project_dir,
+        source_pairs,
+        prefer_project_apps_leaf=include_project_apps_container,
+    )
+    return tuple(sorted(sources, key=lambda item: item.module_path))
+
+
+def initialize_settings_file(
+    project_dir: str | Path,
+    *,
+    force: bool = False,
+    sources: tuple[AppSettingsSource, ...] | None = None,
+) -> SettingsWriteResult:
+    resolved_project_dir = _resolve_project_dir(project_dir)
+    with _SettingsUpdateLock(resolved_project_dir):
+        config_path = resolved_project_dir / PROJECT_JSONC_NAME
+        existed_before = config_path.exists()
+        if existed_before and not force:
+            raise PzError(
+                code="PZ_SETTINGS_FILE_EXISTS",
+                message=f"Refusing to overwrite existing settings file: {config_path}",
+                stage="cli",
+                owner=_OWNER,
+                action="init_settings",
+            )
+        current_payload = _load_existing_document(config_path) if existed_before else {}
+        if existed_before and force:
+            _create_update_backup(resolved_project_dir, current_payload)
+        selected_sources = tuple(
+            sources
+            or discover_settings_sources(
+                resolved_project_dir,
+                include_project_apps_container=force,
+            )
+        )
+        seed_payload = {} if force else current_payload
+        next_payload = _build_initialized_payload(resolved_project_dir, seed_payload, selected_sources)
+        root_env_assignments = _pop_root_env_redirects(next_payload)
+        _atomic_write_text(
+            config_path,
+            dump_jsonc_document(
+                next_payload,
+                managed_paths=_MANAGED_PATHS,
+                comments=_collect_project_jsonc_comments(selected_sources),
+            ),
+        )
+        _ensure_pz_env_settings_placeholders(resolved_project_dir)
+        _ensure_pz_env_env_templates(
+            resolved_project_dir,
+            root_env_assignments=root_env_assignments,
+            app_secret_templates=_collect_app_secret_templates(selected_sources),
+        )
+        write_project_agents_file(resolved_project_dir)
+        return SettingsWriteResult(
+            path=config_path,
+            module_paths=tuple(item.module_path for item in selected_sources),
+            created=not existed_before,
+        )
+
+
+def update_settings_file(
+    project_dir: str | Path,
+    *,
+    target: str | None = None,
+    sources: tuple[AppSettingsSource, ...] | None = None,
+    reset_middlewares_order: bool = False,
+) -> SettingsWriteResult:
+    resolved_project_dir = _resolve_project_dir(project_dir)
+    with _SettingsUpdateLock(resolved_project_dir):
+        config_path = resolved_project_dir / PROJECT_JSONC_NAME
+        if not config_path.is_file():
+            raise PzError(
+                code="PZ_SETTINGS_FILE_MISSING",
+                message=f"Settings file does not exist: {config_path}",
+                stage="cli",
+                owner=_OWNER,
+                action="update_settings",
+            )
+        dry_run = _build_settings_update_dry_run(
+            resolved_project_dir,
+            target=target,
+            sources=sources,
+            reset_middlewares_order=reset_middlewares_order,
+        )
+        _create_update_backup(resolved_project_dir, dry_run.current_payload)
+        _atomic_write_text(
+            dry_run.config_path,
+            dump_jsonc_document(
+                dry_run.next_payload,
+                managed_paths=_MANAGED_PATHS,
+                comments=_collect_project_jsonc_comments(dry_run.discovered_sources),
+            ),
+        )
+        _ensure_pz_env_settings_placeholders(resolved_project_dir)
+        _ensure_pz_env_env_templates(
+            resolved_project_dir,
+            root_env_assignments=dry_run.root_env_assignments,
+            app_secret_templates=_collect_app_secret_templates(dry_run.discovered_sources),
+        )
+        write_project_agents_file(resolved_project_dir)
+        return SettingsWriteResult(
+            path=dry_run.config_path,
+            module_paths=tuple(item.module_path for item in dry_run.selected_sources),
+            created=False,
+        )
+
+
+def inspect_settings_update_drift(
+    project_dir: str | Path,
+    *,
+    target: str | None = None,
+    sources: tuple[AppSettingsSource, ...] | None = None,
+    reset_middlewares_order: bool = False,
+) -> SettingsUpdateDriftResult:
+    resolved_project_dir = Path(project_dir).expanduser().resolve()
+    command = f"pz settings update --project-dir {resolved_project_dir}"
+    config_path = resolved_project_dir / PROJECT_JSONC_NAME
+    if not resolved_project_dir.is_dir() or not config_path.is_file():
+        return SettingsUpdateDriftResult(
+            project_dir=resolved_project_dir,
+            required=False,
+            changed_paths=(),
+            module_paths=(),
+            command=command,
+        )
+    dry_run = _build_settings_update_dry_run(
+        resolved_project_dir,
+        target=target,
+        sources=sources,
+        reset_middlewares_order=reset_middlewares_order,
+    )
+    changed_paths = _settings_update_changed_paths(dry_run)
+    return SettingsUpdateDriftResult(
+        project_dir=resolved_project_dir,
+        required=bool(changed_paths),
+        changed_paths=changed_paths,
+        module_paths=tuple(item.module_path for item in dry_run.selected_sources),
+        command=command,
+    )
+
+
+def _build_settings_update_dry_run(
+    project_dir: Path,
+    *,
+    target: str | None,
+    sources: tuple[AppSettingsSource, ...] | None,
+    reset_middlewares_order: bool,
+) -> _SettingsUpdateDryRun:
+    config_path = project_dir / PROJECT_JSONC_NAME
+    discovered_sources = tuple(sources or discover_settings_sources(project_dir))
+    selected_sources = _resolve_target_sources(target, discovered_sources)
+    current_payload = _load_existing_document(config_path)
+    next_payload = _build_updated_payload(
+        project_dir,
+        current_payload,
+        selected_sources,
+        all_sources=discovered_sources,
+        reset_middlewares_order=reset_middlewares_order,
+    )
+    root_env_assignments = _pop_root_env_redirects(next_payload)
+    return _SettingsUpdateDryRun(
+        project_dir=project_dir,
+        config_path=config_path,
+        current_payload=current_payload,
+        next_payload=next_payload,
+        discovered_sources=discovered_sources,
+        selected_sources=selected_sources,
+        root_env_assignments=root_env_assignments,
+    )
+
+
+def _settings_update_changed_paths(dry_run: _SettingsUpdateDryRun) -> tuple[Path, ...]:
+    changed_paths: list[Path] = []
+    if not _json_payload_equivalent(dry_run.next_payload, dry_run.current_payload):
+        changed_paths.append(dry_run.config_path)
+    changed_paths.extend(_project_agents_changed_paths(dry_run.project_dir))
+    changed_paths.extend(_pz_env_settings_placeholder_changed_paths(dry_run.project_dir))
+    changed_paths.extend(
+        _pz_env_template_changed_paths(
+            dry_run.project_dir,
+            root_env_assignments=dry_run.root_env_assignments,
+            app_secret_templates=_collect_app_secret_templates(dry_run.discovered_sources),
+        )
+    )
+    return tuple(dict.fromkeys(changed_paths))
+
+
+def _json_payload_equivalent(left: Any, right: Any) -> bool:
+    try:
+        return json.loads(json.dumps(left, ensure_ascii=False, sort_keys=True)) == json.loads(
+            json.dumps(right, ensure_ascii=False, sort_keys=True)
+        )
+    except TypeError:
+        return left == right
+
+
+def _pz_env_settings_placeholder_changed_paths(project_dir: Path) -> tuple[Path, ...]:
+    changed_paths: list[Path] = []
+    for file_name, template in _PZ_ENV_SETTINGS_TEMPLATES.items():
+        path = project_dir / file_name
+        if not path.exists():
+            changed_paths.append(path)
+            continue
+        current_payload = _load_existing_document(path)
+        template_payload = _load_template_jsonc_payload(template())
+        merged_payload = _migrate_root_routing_language_fields(
+            _deep_merge_payload(template_payload, current_payload)
+        )
+        if merged_payload != current_payload:
+            changed_paths.append(path)
+    return tuple(changed_paths)
+
+
+def _pz_env_template_changed_paths(
+    project_dir: Path,
+    *,
+    root_env_assignments: dict[str, str],
+    app_secret_templates: tuple[tuple[str, tuple[tuple[str, str], ...]], ...],
+) -> tuple[Path, ...]:
+    changed_paths: list[Path] = []
+    for file_name, template in _PZ_ENV_ENV_TEMPLATES.items():
+        path = project_dir / file_name
+        template_text = template() + _render_app_secret_template_block(
+            app_secret_templates,
+            commented=file_name != ".env",
+        )
+        preferred_assignments = root_env_assignments if file_name == ".env" else None
+        if not path.exists():
+            changed_paths.append(path)
+            continue
+        existing_text = path.read_text(encoding="utf-8")
+        merged_text = _merge_env_template_text(
+            template_text,
+            existing_text,
+            preferred_assignments=preferred_assignments,
+        )
+        if merged_text != existing_text:
+            changed_paths.append(path)
+    return tuple(changed_paths)
+
+
+def _resolve_project_dir(project_dir: str | Path) -> Path:
+    path = Path(project_dir).expanduser().resolve()
+    if not path.exists() or not path.is_dir():
+        raise PzError(
+            code="PZ_SETTINGS_PROJECT_DIR_INVALID",
+            message=f"project directory must exist: {path}",
+            stage="cli",
+            owner=_OWNER,
+            action="resolve_project_dir",
+        )
+    return path
+
+
+def _resolve_existing_project_dir(project_dir: str | Path | None) -> Path | None:
+    if project_dir is None:
+        return None
+    return _resolve_project_dir(project_dir)
+
+
+def _settings_update_lock_path(project_dir: Path) -> Path:
+    return project_dir / ".runtime" / "run" / "locks" / _UPDATE_LOCK_NAME
+
+
+class _SettingsUpdateLock(AbstractContextManager):
+    def __init__(self, project_dir: Path) -> None:
+        self._lock_path = _settings_update_lock_path(project_dir)
+        self._handle = None
+        self._fallback_lock_dir: Path | None = None
+
+    def __enter__(self):
+        self.acquire()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.release()
+
+    def acquire(self) -> None:
+        self._lock_path.parent.mkdir(parents=True, exist_ok=True)
+        self._handle = self._lock_path.open("a+", encoding="utf-8")
+        if fcntl is not None:
+            try:
+                fcntl.flock(self._handle.fileno(), fcntl.LOCK_EX)
+                return
+            except Exception:
+                self._handle.close()
+                self._handle = None
+                raise
+        fallback_lock_dir = self._lock_path.with_suffix(self._lock_path.suffix + ".d")
+        try:
+            while True:  # pragma: no cover
+                try:
+                    fallback_lock_dir.mkdir(parents=False, exist_ok=False)
+                    self._fallback_lock_dir = fallback_lock_dir
+                    return
+                except FileExistsError:
+                    time.sleep(0.05)
+        except Exception:
+            if self._handle is not None:
+                self._handle.close()
+                self._handle = None
+            raise
+
+    def release(self) -> None:
+        try:
+            if self._handle is not None and fcntl is not None:
+                fcntl.flock(self._handle.fileno(), fcntl.LOCK_UN)
+        finally:
+            if self._handle is not None:
+                self._handle.close()
+                self._handle = None
+            if self._fallback_lock_dir is not None:
+                try:  # pragma: no cover
+                    self._fallback_lock_dir.rmdir()
+                finally:
+                    self._fallback_lock_dir = None
+
+
+def _atomic_write_text(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_name(f".{path.name}.{uuid4().hex}.tmp")
+    try:
+        with tmp_path.open("w", encoding="utf-8") as handle:
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        if path.exists():
+            try:
+                tmp_path.chmod(path.stat().st_mode)
+            except OSError:
+                pass
+        tmp_path.replace(path)
+        _fsync_parent_directory(path)
+    except Exception:
+        try:
+            tmp_path.unlink()
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def _fsync_parent_directory(path: Path) -> None:
+    try:
+        fd = os.open(str(path.parent), os.O_RDONLY)
+    except OSError:
+        return
+    try:
+        os.fsync(fd)
+    except OSError:
+        pass
+    finally:
+        os.close(fd)
+
+
+def _ensure_pz_env_settings_placeholders(project_dir: Path) -> None:
+    for file_name, template in _PZ_ENV_SETTINGS_TEMPLATES.items():
+        path = project_dir / file_name
+        template_payload = _load_template_jsonc_payload(template())
+        if not path.exists():
+            _atomic_write_text(path, template())
+            continue
+        current_payload = _load_existing_document(path)
+        merged_payload = _migrate_root_routing_language_fields(
+            _deep_merge_payload(template_payload, current_payload)
+        )
+        if merged_payload != current_payload:
+            _atomic_write_text(path, _annotate_project_base_url_comment(dump_jsonc_document(merged_payload)))
+
+
+def _ensure_pz_env_env_templates(
+    project_dir: Path,
+    *,
+    root_env_assignments: dict[str, str] | None = None,
+    app_secret_templates: tuple[tuple[str, tuple[tuple[str, str], ...]], ...] = (),
+) -> None:
+    for file_name, template in _PZ_ENV_ENV_TEMPLATES.items():
+        path = project_dir / file_name
+        template_text = template() + _render_app_secret_template_block(
+            app_secret_templates,
+            commented=file_name != ".env",
+        )
+        preferred_assignments = root_env_assignments if file_name == ".env" else None
+        if not path.exists():
+            _atomic_write_text(
+                path,
+                _merge_env_template_text(template_text, "", preferred_assignments=preferred_assignments),
+            )
+            continue
+        existing_text = path.read_text(encoding="utf-8")
+        merged_text = _merge_env_template_text(
+            template_text,
+            existing_text,
+            preferred_assignments=preferred_assignments,
+        )
+        if merged_text != existing_text:
+            _atomic_write_text(path, merged_text)
+
+
+def _load_template_jsonc_payload(template_text: str) -> dict[str, Any]:
+    payload = load_jsonc_text(
+        template_text,
+        code="PZ_SETTINGS_TEMPLATE_INVALID",
+        owner=_OWNER,
+        action="load_template_jsonc_payload",
+        source_name="pz_env template",
+    )
+    if not isinstance(payload, dict):
+        raise PzError(
+            code="PZ_SETTINGS_TEMPLATE_INVALID",
+            message="pz_env JSONC template must define an object payload.",
+            stage="cli",
+            owner=_OWNER,
+            action="load_template_jsonc_payload",
+        )
+    return payload
+
+
+def _merge_env_template_text(
+    template_text: str,
+    existing_text: str,
+    *,
+    preferred_assignments: dict[str, str] | None = None,
+) -> str:
+    existing_values = _parse_env_assignments(existing_text)
+    for key, value in (preferred_assignments or {}).items():
+        if key not in existing_values and str(value or "").strip():
+            existing_values[key] = str(value).strip()
+    emitted_keys: set[str] = set()
+    rendered_lines: list[str] = []
+    for line in template_text.splitlines():
+        assignment = _parse_env_assignment_line(line)
+        key = assignment[0] if assignment is not None else None
+        if key is None:
+            rendered_lines.append(line)
+            continue
+        template_value = assignment[1]
+        if key in existing_values:
+            value = existing_values[key]
+            if _is_secret_generator_directive(template_value) and not str(value or "").strip():
+                value = _generate_env_secret_value(template_value)
+            rendered_lines.append(f"{key}={value}")
+        elif _is_secret_generator_directive(template_value) and not assignment[2]:
+            rendered_lines.append(f"{key}={_generate_env_secret_value(template_value)}")
+        else:
+            rendered_lines.append(line)
+        emitted_keys.add(key)
+    extra_keys = [key for key in existing_values if key not in emitted_keys]
+    if extra_keys:
+        if rendered_lines and rendered_lines[-1] != "":
+            rendered_lines.append("")
+        rendered_lines.append("# Existing custom overrides")
+        for key in extra_keys:
+            rendered_lines.append(f"{key}={existing_values[key]}")
+    return "\n".join(rendered_lines).rstrip() + "\n"
+
+
+def _parse_env_assignments(text: str) -> dict[str, str]:
+    assignments: dict[str, str] = {}
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        if key:
+            assignments[key] = value
+    return assignments
+
+
+def _parse_env_assignment_line(line: str) -> tuple[str, str, bool] | None:
+    stripped = line.strip()
+    if not stripped:
+        return None
+    commented = stripped.startswith("#")
+    candidate = stripped[1:].strip() if commented else stripped
+    if "=" not in candidate:
+        return None
+    key, value = candidate.split("=", 1)
+    key = key.strip()
+    if not key or " " in key:
+        return None
+    return key, value, commented
+
+
+def _parse_env_template_assignments(text: str) -> tuple[tuple[str, str], ...]:
+    assignments: list[tuple[str, str]] = []
+    seen: set[str] = set()
+    for raw_line in text.splitlines():
+        key = _extract_env_assignment_key(raw_line)
+        if key is None or key in seen:
+            continue
+        stripped = raw_line.strip()
+        candidate = stripped[1:].strip() if stripped.startswith("#") else stripped
+        _key, value = candidate.split("=", 1)
+        assignments.append((key, value))
+        seen.add(key)
+    return tuple(assignments)
+
+
+def _extract_env_assignment_key(line: str) -> str | None:
+    assignment = _parse_env_assignment_line(line)
+    return assignment[0] if assignment is not None else None
+
+
+def _is_secret_generator_directive(value: str) -> bool:
+    return str(value or "").strip().lower().startswith(_SECRET_GENERATOR_PREFIX)
+
+
+def _generate_env_secret_value(value: str) -> str:
+    directive = str(value or "").strip().lower()
+    if directive in {"@pz:secret", "@pz:secret:urlsafe", "@pz:secret:urlsafe64"}:
+        return secrets.token_urlsafe(48)
+    if directive in {"@pz:secret:hex", "@pz:secret:hex64"}:
+        return secrets.token_hex(32)
+    raise PzError(
+        code="PZ_APP_DEFAULT_ENV_INVALID",
+        message=f"Unsupported env secret generator directive: {value}",
+        stage="cli",
+        owner=_OWNER,
+        action="merge_env_template",
+    )
+
+
+def _collect_app_secret_templates(
+    sources: tuple[AppSettingsSource, ...],
+) -> tuple[tuple[str, tuple[tuple[str, str], ...]], ...]:
+    collected: list[tuple[str, tuple[tuple[str, str], ...]]] = []
+    seen_apps: set[str] = set()
+    for source in sorted(sources, key=lambda item: item.app_id):
+        if source.app_id in seen_apps:
+            continue
+        assignments = _parse_env_template_assignments(source.secret_template)
+        if assignments:
+            collected.append((source.app_id, assignments))
+            seen_apps.add(source.app_id)
+    return tuple(collected)
+
+
+def _render_app_secret_template_block(
+    templates: tuple[tuple[str, tuple[tuple[str, str], ...]], ...],
+    *,
+    commented: bool,
+) -> str:
+    if not templates:
+        return ""
+    lines = [
+        "",
+        "# Installed app secret placeholders",
+        "# Generated from installed apps' configs/default.env files.",
+    ]
+    prefix = "# " if commented else ""
+    for app_id, assignments in templates:
+        lines.append("")
+        lines.append(f"# {app_id}")
+        for key, value in assignments:
+            rendered_value = "" if commented and _is_secret_generator_directive(value) else value
+            lines.append(f"{prefix}{key}={rendered_value}")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _pop_root_env_redirects(payload: dict[str, Any]) -> dict[str, str]:
+    assignments: dict[str, str] = {}
+    for path, env_key in _ROOT_ENV_REDIRECTS.items():
+        current: Any = payload
+        for segment in path[:-1]:
+            if not isinstance(current, dict):
+                current = None
+                break
+            current = current.get(segment)
+        if not isinstance(current, dict):
+            continue
+        leaf_key = path[-1]
+        if leaf_key not in current:
+            continue
+        value = current.pop(leaf_key)
+        if value in (None, ""):
+            continue
+        assignments[env_key] = str(value)
+    return assignments
+
+
+def _settings_update_backup_root(project_dir: Path) -> Path:
+    return project_dir / ".runtime" / "backups" / _UPDATE_BACKUP_DIRNAME
+
+
+def _settings_backup_keep_count(payload: dict[str, Any]) -> int:
+    project = payload.get("project")
+    if isinstance(project, dict):
+        raw = project.get("settings_backup_keep_count", _UPDATE_BACKUP_DEFAULT_KEEP_COUNT)
+    else:
+        raw = _UPDATE_BACKUP_DEFAULT_KEEP_COUNT
+    try:
+        keep_count = int(raw)
+    except Exception:
+        keep_count = _UPDATE_BACKUP_DEFAULT_KEEP_COUNT
+    return keep_count if keep_count > 0 else _UPDATE_BACKUP_DEFAULT_KEEP_COUNT
+
+
+def _update_backup_candidates(project_dir: Path) -> tuple[Path, ...]:
+    candidates = (
+        "AGENTS.md",
+        PROJECT_JSONC_NAME,
+        "pz.develop.jsonc",
+        "pz.test.jsonc",
+        "pz.product.jsonc",
+        ".env",
+        ".env.develop",
+        ".env.test",
+        ".env.product",
+    )
+    return tuple(project_dir / item for item in candidates)
+
+
+def _create_update_backup(project_dir: Path, current_payload: dict[str, Any]) -> Path:
+    backup_root = _settings_update_backup_root(project_dir)
+    backup_root.mkdir(parents=True, exist_ok=True)
+    backup_dir = backup_root / datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+    backup_dir.mkdir(parents=True, exist_ok=False)
+    for source in _update_backup_candidates(project_dir):
+        if not source.exists():
+            continue
+        shutil.copy2(source, backup_dir / source.name)
+    _prune_update_backups(backup_root, keep_count=_settings_backup_keep_count(current_payload))
+    return backup_dir
+
+
+def _project_agents_changed_paths(project_dir: Path) -> tuple[Path, ...]:
+    path = project_dir / "AGENTS.md"
+    current = path.read_text(encoding="utf-8") if path.exists() else None
+    expected = render_project_agents_file_text(project_dir)
+    if current == expected:
+        return ()
+    return (path,)
+
+
+def _prune_update_backups(backup_root: Path, *, keep_count: int) -> None:
+    existing_dirs = sorted(
+        [path for path in backup_root.iterdir() if path.is_dir()],
+        key=lambda item: item.name,
+        reverse=True,
+    )
+    for stale in existing_dirs[keep_count:]:
+        shutil.rmtree(stale, ignore_errors=True)
+
+
+def _declared_app_entries(
+    project_dir: Path | None,
+    *,
+    include_project_apps_container: bool = False,
+) -> tuple[str, ...]:
+    if project_dir is None:
+        return ("apps",)
+
+    entries: list[str] = []
+    config_path = project_dir / PROJECT_JSONC_NAME
+    if config_path.is_file():
+        data = _load_existing_document(config_path)
+        raw = data.get("installed_apps")
+        if isinstance(raw, list):
+            entries.extend(
+                str(item).strip()
+                for item in raw
+                if isinstance(item, str)
+                and str(item).strip()
+                and _is_formal_app_or_container_entry(project_dir, str(item).strip())
+            )
+
+    if include_project_apps_container and (project_dir / "apps").is_dir() and "apps" not in entries:
+        entries.append("apps")
+
+    if entries:
+        return tuple(dict.fromkeys(entries))
+
+    if (project_dir / "apps").is_dir():
+        return ("apps",)
+    return ()
+
+
+def _build_settings_source(module_path: str) -> AppSettingsSource:
+    app_id = _load_app_id(module_path)
+    raw_defaults, raw_comments = _load_app_settings_defaults_with_comments(module_path)
+    defaults, root_defaults, comments, root_comments = _split_app_settings_defaults_with_comments(
+        raw_defaults,
+        raw_comments,
+        module_path=module_path,
+    )
+    normalize = _load_app_settings_normalizer(module_path)
+    secret_template = _load_app_settings_secret_template(module_path)
+    _validate_app_settings_secret_template(
+        app_id=app_id,
+        module_path=module_path,
+        defaults=defaults,
+        secret_template=secret_template,
+    )
+    return AppSettingsSource(
+        module_path=module_path,
+        app_id=app_id,
+        defaults=defaults,
+        normalize=normalize,
+        secret_template=secret_template,
+        root_defaults=root_defaults,
+        comments=comments,
+        root_comments=root_comments,
+    )
+
+
+def _dedupe_settings_sources_by_app_id(
+    project_dir: Path | None,
+    source_pairs: list[tuple[Any, AppSettingsSource]],
+    *,
+    prefer_project_apps_leaf: bool,
+) -> list[AppSettingsSource]:
+    selected: dict[str, tuple[Any, AppSettingsSource]] = {}
+    for ref, source in source_pairs:
+        existing = selected.get(source.app_id)
+        if existing is None:
+            selected[source.app_id] = (ref, source)
+            continue
+        if prefer_project_apps_leaf and _prefer_settings_source_over_existing(project_dir, ref, source, existing):
+            selected[source.app_id] = (ref, source)
+            continue
+    return [item[1] for item in selected.values()]
+
+
+def _prefer_settings_source_over_existing(
+    project_dir: Path | None,
+    ref: Any,
+    source: AppSettingsSource,
+    existing: tuple[Any, AppSettingsSource],
+) -> bool:
+    if not _is_project_apps_leaf_ref(project_dir, ref):
+        return False
+    existing_ref, existing_source = existing
+    if not _is_project_apps_leaf_ref(project_dir, existing_ref):
+        return True
+    return existing_source.module_path.startswith("apps.") and not source.module_path.startswith("apps.")
+
+
+def _is_project_apps_leaf_ref(project_dir: Path | None, ref: Any) -> bool:
+    if project_dir is None:
+        return False
+    import_root = getattr(ref, "import_root", None)
+    if import_root is None:
+        return False
+    try:
+        root = Path(import_root).resolve()
+        apps_root = (project_dir / "apps").resolve()
+        return root == apps_root or root.is_relative_to(apps_root)
+    except Exception:
+        return False
+
+
+def _load_app_id(module_path: str) -> str:
+    try:
+        return resolve_declared_app_id(module_path)
+    except PzError as exc:
+        raise PzError(
+            code="PZ_SETTINGS_APP_ID_INVALID",
+            message=f"App '{module_path}' must expose a valid app.id identifier.",
+            stage="cli",
+            owner=_OWNER,
+            action="discover_settings_sources",
+            detail=exc.detail,
+        ) from exc
+
+
+def _load_app_settings_defaults(module_path: str) -> dict[str, Any]:
+    defaults, _comments = _load_app_settings_defaults_with_comments(module_path)
+    return defaults
+
+
+def _load_app_settings_defaults_with_comments(
+    module_path: str,
+) -> tuple[dict[str, Any], dict[tuple[str, ...], tuple[str, ...]]]:
+    package_root = resolve_package_root(module_path)
+    if package_root is None:
+        return {}, {}
+    default_jsonc_path = package_root / "configs" / "default.jsonc"
+    if not default_jsonc_path.is_file():
+        return {}, {}
+    raw_text = default_jsonc_path.read_text(encoding="utf-8")
+    payload = load_jsonc_file(
+        default_jsonc_path,
+        code="PZ_APP_DEFAULTS_INVALID",
+        owner=_OWNER,
+        action="load_app_settings_defaults",
+    )
+    if not isinstance(payload, dict):
+        raise PzError(
+            code="PZ_APP_DEFAULTS_INVALID",
+            message=f"App default settings file '{default_jsonc_path}' must define an object payload.",
+            stage="cli",
+            owner=_OWNER,
+            action="load_app_settings_defaults",
+        )
+    return dict(payload), _extract_default_jsonc_comments(raw_text)
+
+
+def _split_app_settings_defaults(
+    payload: dict[str, Any],
+    *,
+    module_path: str,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    defaults, root_defaults, _comments, _root_comments = _split_app_settings_defaults_with_comments(
+        payload,
+        {},
+        module_path=module_path,
+    )
+    return defaults, root_defaults
+
+
+def _split_app_settings_defaults_with_comments(
+    payload: dict[str, Any],
+    comments: dict[tuple[str, ...], tuple[str, ...]],
+    *,
+    module_path: str,
+) -> tuple[
+    dict[str, Any],
+    dict[str, Any],
+    dict[tuple[str, ...], tuple[str, ...]],
+    dict[tuple[str, ...], tuple[str, ...]],
+]:
+    defaults = dict(payload)
+    app_comments = dict(comments)
+    root_defaults: dict[str, Any] = {}
+    root_comments: dict[tuple[str, ...], tuple[str, ...]] = {}
+    if "routing" in defaults:
+        root_defaults["routing"] = _normalize_routing_defaults(defaults.pop("routing"), module_path=module_path)
+        routing_prefix = ("routing",)
+        for path, lines in tuple(app_comments.items()):
+            if path == routing_prefix or path[:1] == routing_prefix:
+                root_comments[path] = lines
+                app_comments.pop(path, None)
+    if "commands" in defaults:
+        root_defaults["commands"] = _normalize_commands_defaults(defaults.pop("commands"), module_path=module_path)
+        commands_prefix = ("commands",)
+        for path, lines in tuple(app_comments.items()):
+            if path == commands_prefix or path[:1] == commands_prefix:
+                root_comments[path] = lines
+                app_comments.pop(path, None)
+    if "apps" in defaults:
+        root_defaults["apps"] = _normalize_apps_defaults(defaults.pop("apps"), module_path=module_path)
+        apps_prefix = ("apps",)
+        for path, lines in tuple(app_comments.items()):
+            if path == apps_prefix or path[:1] == apps_prefix:
+                root_comments[path] = lines
+                app_comments.pop(path, None)
+    return defaults, root_defaults, app_comments, root_comments
+
+
+def _normalize_routing_defaults(payload: Any, *, module_path: str) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        raise PzError(
+            code="PZ_APP_DEFAULTS_INVALID",
+            message=(
+                f"App default settings file '{module_path}/configs/default.jsonc' field "
+                "'routing' must define an object payload."
+            ),
+            stage="cli",
+            owner=_OWNER,
+            action="load_app_settings_defaults",
+        )
+    out: dict[str, Any] = {}
+    for raw_key, raw_value in payload.items():
+        key = str(raw_key or "").strip()
+        if key not in _ROUTING_DEFAULT_KEYS:
+            raise PzError(
+                code="PZ_APP_DEFAULTS_INVALID",
+                message=(
+                    f"App default settings file '{module_path}/configs/default.jsonc' field "
+                    f"'routing.{key}' is not supported."
+                ),
+                stage="cli",
+                owner=_OWNER,
+                action="load_app_settings_defaults",
+            )
+        out[key] = raw_value
+    return out
+
+
+def _normalize_commands_defaults(payload: Any, *, module_path: str) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        raise PzError(
+            code="PZ_APP_DEFAULTS_INVALID",
+            message=(
+                f"App default settings file '{module_path}/configs/default.jsonc' field "
+                "'commands' must define an object payload."
+            ),
+            stage="cli",
+            owner=_OWNER,
+            action="load_app_settings_defaults",
+        )
+    return dict(payload)
+
+
+def _normalize_apps_defaults(payload: Any, *, module_path: str) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        raise PzError(
+            code="PZ_APP_DEFAULTS_INVALID",
+            message=(
+                f"App default settings file '{module_path}/configs/default.jsonc' field "
+                "'apps' must define an object payload."
+            ),
+            stage="cli",
+            owner=_OWNER,
+            action="load_app_settings_defaults",
+        )
+    return dict(payload)
+
+
+def _should_refresh_root_default(path: tuple[str, ...]) -> bool:
+    if path and path[0] in _ROOT_DEFAULT_REFRESH_KEYS:
+        return True
+    if len(path) >= 4 and path[0] == "apps" and path[2] == "sources" and path[3] == "source_mode":
+        return True
+    return False
+
+
+def _extract_default_jsonc_comments(text: str) -> dict[tuple[str, ...], tuple[str, ...]]:
+    comments: dict[tuple[str, ...], tuple[str, ...]] = {}
+    stack: list[tuple[str, int]] = []
+    pending: list[str] = []
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line:
+            pending = []
+            continue
+        if line.startswith("//") and not line.startswith("// @pz:"):
+            pending.append(line[2:].strip())
+            continue
+        key = _jsonc_object_key_from_line(line)
+        if key is not None:
+            depth = _leading_space_count(raw_line) // 2
+            while stack and stack[-1][1] >= depth:
+                stack.pop()
+            path = tuple(item[0] for item in stack) + (key,)
+            if pending:
+                comments[path] = tuple(item for item in pending if item)
+            pending = []
+            if _line_opens_object(line):
+                stack.append((key, depth))
+            if _line_closes_object(line):
+                while stack and stack[-1][1] >= depth:
+                    stack.pop()
+            continue
+        pending = []
+        if _line_closes_object(line):
+            depth = _leading_space_count(raw_line) // 2
+            while stack and stack[-1][1] >= depth:
+                stack.pop()
+    return comments
+
+
+def _leading_space_count(value: str) -> int:
+    return len(value) - len(value.lstrip(" "))
+
+
+def _jsonc_object_key_from_line(line: str) -> str | None:
+    if not line.startswith('"'):
+        return None
+    escaped = False
+    for index in range(1, len(line)):
+        char = line[index]
+        if escaped:
+            escaped = False
+            continue
+        if char == "\\":
+            escaped = True
+            continue
+        if char != '"':
+            continue
+        rest = line[index + 1 :].lstrip()
+        if not rest.startswith(":"):
+            return None
+        try:
+            key = json.loads(line[: index + 1])
+        except Exception:
+            return None
+        return str(key)
+    return None
+
+
+def _line_opens_object(line: str) -> bool:
+    return line.rstrip().endswith("{") or line.rstrip().endswith("{,")
+
+
+def _line_closes_object(line: str) -> bool:
+    stripped = line.lstrip()
+    return stripped.startswith("}") or stripped.startswith("]")
+
+
+def _load_app_settings_secret_template(module_path: str) -> str:
+    package_root = resolve_package_root(module_path)
+    if package_root is None:
+        return ""
+    default_env_path = package_root / "configs" / "default.env"
+    if not default_env_path.is_file():
+        return ""
+    return default_env_path.read_text(encoding="utf-8")
+
+
+def _flatten_payload_paths(payload: dict[str, Any], prefix: tuple[str, ...] = ()) -> set[tuple[str, ...]]:
+    paths: set[tuple[str, ...]] = set()
+    for key, value in payload.items():
+        path = (*prefix, str(key).strip().lower())
+        paths.add(path)
+        if isinstance(value, dict):
+            paths.update(_flatten_payload_paths(value, path))
+    return paths
+
+
+def _is_secret_template_path(path: tuple[str, ...]) -> bool:
+    normalized_path = "__".join(path).lower()
+    return any(token in normalized_path for token in _SECRET_TEMPLATE_KEY_TOKENS)
+
+
+def _validate_app_settings_secret_template(
+    *,
+    app_id: str,
+    module_path: str,
+    defaults: dict[str, Any],
+    secret_template: str,
+) -> None:
+    assignments = _parse_env_template_assignments(secret_template)
+    if not assignments:
+        return
+    allowed_paths = _flatten_payload_paths(defaults)
+    prefix = app_id.replace("-", "_") + "__"
+    for key, _value in assignments:
+        if not key.startswith(prefix):
+            raise PzError(
+                code="PZ_APP_DEFAULT_ENV_INVALID",
+                message=(
+                    f"App secret template key '{key}' must start with '{prefix}' "
+                    f"for app '{app_id}'."
+                ),
+                stage="cli",
+                owner=_OWNER,
+                action="load_app_settings_secret_template",
+            )
+        nested_path = tuple(part.strip().lower() for part in key[len(prefix) :].split("__") if part.strip())
+        if not nested_path or nested_path not in allowed_paths:
+            raise PzError(
+                code="PZ_APP_DEFAULT_ENV_INVALID",
+                message=(
+                    f"App secret template key '{key}' is not backed by "
+                    f"{module_path}/configs/default.jsonc."
+                ),
+                stage="cli",
+                owner=_OWNER,
+                action="load_app_settings_secret_template",
+            )
+        if not _is_secret_template_path(nested_path):
+            raise PzError(
+                code="PZ_APP_DEFAULT_ENV_INVALID",
+                message=(
+                    f"App secret template key '{key}' must target a password, secret, token, "
+                    "key, or webhook setting declared by the app defaults."
+                ),
+                stage="cli",
+                owner=_OWNER,
+                action="load_app_settings_secret_template",
+            )
+
+
+def _load_app_settings_normalizer(module_path: str) -> SettingsPayloadNormalizer | None:
+    settings_module = import_app_settings_module(
+        module_path,
+        action="load_app_settings_normalizer",
+    )
+    if settings_module is None:
+        return None
+    normalizer = getattr(settings_module, "normalize_settings_payload", None)
+    if normalizer is None:
+        normalizer = getattr(settings_module, "_normalize_settings_payload", None)
+    if normalizer is None:
+        return None
+    if not callable(normalizer):
+        raise PzError(
+            code="PZ_APP_SETTINGS_NORMALIZER_INVALID",
+            message=(
+                f"App settings entrypoint '{module_path}.settings' must expose "
+                "'normalize_settings_payload()' or '_normalize_settings_payload()' as a callable."
+            ),
+            stage="cli",
+            owner=_OWNER,
+            action="load_app_settings_normalizer",
+        )
+    return normalizer
+
+
+def _resolve_target_sources(target: str | None, sources: tuple[AppSettingsSource, ...]) -> tuple[AppSettingsSource, ...]:
+    if target is None:
+        return sources
+    token = str(target).strip()
+    if not token:
+        raise PzError(
+            code="PZ_SETTINGS_TARGET_INVALID",
+            message="target must be a non-empty app selector when provided.",
+            stage="cli",
+            owner=_OWNER,
+            action="update_settings",
+        )
+    if token.startswith("apps."):
+        prefixed_matches = tuple(item for item in sources if item.module_path == token or item.module_path.startswith(token + "."))
+        if prefixed_matches:
+            return prefixed_matches
+    exact_matches = tuple(
+        item
+        for item in sources
+        if item.app_id == token or item.module_path == token or item.module_path.rsplit(".", 1)[-1] == token
+    )
+    if exact_matches:
+        return exact_matches
+    raise PzError(
+        code="PZ_SETTINGS_TARGET_NOT_FOUND",
+        message=f"No app settings source matched target '{token}'.",
+        stage="cli",
+        owner=_OWNER,
+        action="update_settings",
+    )
+
+
+def _load_existing_document(path: Path) -> dict[str, Any]:
+    return load_jsonc_file(
+        path,
+        code="PZ_PROJECT_CONFIG_INVALID",
+        owner=_OWNER,
+        action="read_project_jsonc",
+    )
+
+
+def _build_initialized_payload(
+    project_dir: Path,
+    current_payload: dict[str, Any],
+    sources: tuple[AppSettingsSource, ...],
+) -> dict[str, Any]:
+    next_payload = _build_project_payload_with_defaults(current_payload)
+    installed_apps = _managed_installed_app_entries(
+        project_dir,
+        current_payload,
+        sources,
+        preserve_existing=False,
+    )
+    next_payload["installed_apps"] = installed_apps
+    next_payload["apps"] = _managed_app_settings_payload(
+        project_dir,
+        current_payload,
+        sources,
+        installed_apps=installed_apps,
+    )
+    _apply_app_root_defaults(next_payload, sources, preserve_existing=False)
+    next_payload["middlewares"] = _managed_middlewares_payload(
+        project_dir,
+        current_payload,
+        next_payload,
+        preserve_existing=False,
+    )
+    return _ordered_root_payload(next_payload)
+
+
+def _build_updated_payload(
+    project_dir: Path,
+    current_payload: dict[str, Any],
+    sources: tuple[AppSettingsSource, ...],
+    all_sources: tuple[AppSettingsSource, ...],
+    *,
+    reset_middlewares_order: bool,
+) -> dict[str, Any]:
+    next_payload = _build_project_payload_with_defaults(current_payload)
+    installed_apps = _managed_installed_app_entries(
+        project_dir,
+        current_payload,
+        all_sources,
+        preserve_existing=True,
+    )
+    next_payload["installed_apps"] = installed_apps
+
+    next_payload["apps"] = _managed_app_settings_payload(
+        project_dir,
+        current_payload,
+        sources,
+        installed_apps=installed_apps,
+    )
+    _apply_app_root_defaults(next_payload, sources, preserve_existing=True)
+    next_payload["middlewares"] = _managed_middlewares_payload(
+        project_dir,
+        current_payload,
+        next_payload,
+        preserve_existing=not reset_middlewares_order,
+    )
+    return _ordered_root_payload(next_payload)
+
+
+def _apply_app_root_defaults(
+    payload: dict[str, Any],
+    sources: tuple[AppSettingsSource, ...],
+    *,
+    preserve_existing: bool,
+) -> None:
+    for source in sorted(sources, key=lambda item: (item.module_path, item.app_id)):
+        defaults = source.root_defaults if isinstance(source.root_defaults, dict) else {}
+        if not defaults:
+            continue
+        _merge_root_defaults(
+            payload,
+            defaults,
+            source=source.module_path,
+            preserve_existing=preserve_existing,
+        )
+
+
+def _merge_root_defaults(
+    payload: dict[str, Any],
+    defaults: dict[str, Any],
+    *,
+    source: str,
+    preserve_existing: bool,
+    path: tuple[str, ...] = (),
+) -> None:
+    for raw_key, raw_value in defaults.items():
+        key = str(raw_key)
+        current_path = path + (key,)
+        if isinstance(raw_value, dict):
+            existing = payload.get(key)
+            if existing is not None and not isinstance(existing, dict):
+                if preserve_existing:
+                    continue
+                raise PzError(
+                    code="PZ_APP_ROOT_DEFAULT_CONFLICT",
+                    message=(
+                        f"App root default from '{source}' cannot merge "
+                        f"'{'.'.join(current_path)}' into a non-object value."
+                    ),
+                    stage="cli",
+                    owner=_OWNER,
+                    action="merge_app_root_defaults",
+                )
+            target = existing if isinstance(existing, dict) else {}
+            payload[key] = target
+            _merge_root_defaults(
+                target,
+                raw_value,
+                source=source,
+                preserve_existing=preserve_existing,
+                path=current_path,
+            )
+            continue
+        refresh_root_default = _should_refresh_root_default(current_path)
+        if key in payload and preserve_existing and not refresh_root_default:
+            continue
+        payload[key] = raw_value
+
+
+def _build_project_payload_with_defaults(current_payload: dict[str, Any]) -> dict[str, Any]:
+    sanitized_payload = _migrate_root_routing_language_fields(dict(current_payload))
+    sanitized_payload.pop("catalog", None)
+    return _migrate_root_routing_language_fields(
+        _deep_merge_payload(load_project_default_jsonc_payload(), sanitized_payload)
+    )
+
+
+def _collect_project_jsonc_comments(sources: tuple[AppSettingsSource, ...]) -> dict[tuple[str, ...], tuple[str, ...]]:
+    comments: dict[tuple[str, ...], tuple[str, ...]] = {}
+    for source in sources:
+        for path, lines in (source.comments or {}).items():
+            comments[("apps", source.app_id, *path)] = lines
+        for path, lines in (source.root_comments or {}).items():
+            comments[path] = lines
+    return comments
+
+
+def _deep_merge_payload(base: dict[str, Any], incoming: dict[str, Any]) -> dict[str, Any]:
+    merged: dict[str, Any] = dict(base)
+    for key, value in incoming.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = _deep_merge_payload(merged[key], value)
+            continue
+        merged[key] = value
+    return merged
+
+
+def _migrate_root_routing_language_fields(payload: dict[str, Any]) -> dict[str, Any]:
+    routing = payload.get("routing")
+    if not isinstance(routing, dict) or "supported_languages" not in routing:
+        return payload
+    migrated = dict(routing)
+    legacy_value = migrated.pop("supported_languages", None)
+    if "all_supported_languages" not in migrated:
+        migrated["all_supported_languages"] = legacy_value
+    payload["routing"] = migrated
+    return payload
+
+
+def _read_installed_apps(payload: dict[str, Any]) -> list[str]:
+    raw = payload.get("installed_apps")
+    if isinstance(raw, list):
+        return [str(item).strip() for item in raw if isinstance(item, str) and str(item).strip()]
+    return []
+
+
+def _managed_installed_app_entries(
+    project_dir: Path,
+    current_payload: dict[str, Any],
+    sources: tuple[AppSettingsSource, ...],
+    *,
+    preserve_existing: bool,
+) -> list[str]:
+    seeded_entries = _seed_installed_app_entries(project_dir, current_payload, sources)
+    if not preserve_existing:
+        return list(seeded_entries)
+    existing = [
+        item
+        for item in _read_installed_apps(current_payload)
+        if _is_formal_app_or_container_entry(project_dir, item)
+    ]
+    if existing:
+        if len(existing) > 1 and any(_is_container_entry(project_dir, item) for item in existing):
+            return list(_conventional_installed_app_order(project_dir, current_payload, existing))
+        return existing
+    return list(seeded_entries)
+
+
+def _seed_installed_app_entries(
+    project_dir: Path,
+    current_payload: dict[str, Any],
+    sources: tuple[AppSettingsSource, ...],
+) -> list[str]:
+    declared = [item for item in _read_installed_apps(current_payload) if _is_discoverable_app_entry(project_dir, item)]
+    discovered = [item.module_path for item in sources if _is_discoverable_app_entry(project_dir, item.module_path)]
+    conventional = _conventional_installed_app_order(project_dir, current_payload, discovered)
+    if declared:
+        merged_entries = list(merge_explicit_app_order(tuple(declared), conventional))
+        return list(_conventional_installed_app_order(project_dir, current_payload, merged_entries))
+    if discovered:
+        return list(conventional)
+    if (project_dir / "apps").is_dir():
+        return list(_conventional_installed_app_order(project_dir, current_payload, ["apps"]))
+    return list(conventional)
+
+
+def _conventional_installed_app_order(
+    project_dir: Path,
+    current_payload: dict[str, Any],
+    discovered_entries: list[str],
+) -> tuple[str, ...]:
+    if not discovered_entries:
+        return ()
+    payload = _build_project_payload_with_defaults(current_payload)
+    payload["installed_apps"] = list(discovered_entries)
+    with active_settings_project(project_dir):
+        settings = compile_settings_snapshot_from_payload(project_dir, payload)
+        return compile_conventional_app_order(settings, project_dir=project_dir)
+
+
+def _is_discoverable_app_entry(project_dir: Path, module_path: str) -> bool:
+    return _is_formal_app_or_container_entry(project_dir, module_path)
+
+
+def _is_container_entry(project_dir: Path, module_path: str) -> bool:
+    token = str(module_path or "").strip()
+    if not token:
+        return False
+    if token == "apps":
+        return True
+    expanded = discover_leaf_app_packages(token, project_dir=project_dir)
+    return bool(expanded and expanded != (token,))
+
+
+def _is_formal_app_or_container_entry(project_dir: Path, module_path: str) -> bool:
+    token = str(module_path or "").strip()
+    if not token:
+        return False
+    if token == "apps":
+        return (project_dir / "apps").is_dir()
+    if "." not in token:
+        if (project_dir / token).is_dir() or (project_dir / "apps" / token).is_dir():
+            return True
+        refs = discover_declared_app_references((token,), project_dir=project_dir)
+        if any(item.import_root is not None for item in refs):
+            return True
+        expanded = tuple(item.module_path for item in refs)
+        if expanded and expanded != (token,):
+            return True
+    package_root = resolve_package_root(token)
+    if package_root is None:
+        return False
+    if (package_root / "apps.py").is_file():
+        return True
+    expanded = discover_leaf_app_packages(token, project_dir=project_dir)
+    return bool(expanded and expanded != (token,))
+
+
+def _managed_app_settings_payload(
+    project_dir: Path,
+    current_payload: dict[str, Any],
+    sources: tuple[AppSettingsSource, ...],
+    *,
+    installed_apps: list[str],
+) -> dict[str, Any]:
+    current_apps = dict(current_payload.get("apps") if isinstance(current_payload.get("apps"), dict) else {})
+    merged_apps: dict[str, Any] = {}
+    source_by_app_id = {item.app_id: item for item in sources}
+    ordered_app_ids = _ordered_app_settings_app_ids(
+        project_dir,
+        installed_apps=installed_apps,
+        current_apps=current_apps,
+        source_by_app_id=source_by_app_id,
+    )
+
+    for app_id in ordered_app_ids:
+        source = source_by_app_id.get(app_id)
+        if source is None:
+            payload = current_apps.get(app_id)
+            if payload is not None:
+                merged_apps[app_id] = payload
+            continue
+        existing = current_apps.get(source.app_id)
+        if isinstance(existing, dict):
+            merged_apps[source.app_id] = _merge_project_app_settings(source, existing)
+        elif existing is not None:
+            merged_apps[source.app_id] = existing
+        else:
+            merged_apps[source.app_id] = _merge_project_app_settings(source, None)
+
+    for item in sources:
+        if item.app_id in merged_apps:
+            continue
+        existing = current_apps.get(item.app_id)
+        if isinstance(existing, dict):
+            merged_apps[item.app_id] = _merge_project_app_settings(item, existing)
+        elif existing is not None:
+            merged_apps[item.app_id] = existing
+        else:
+            merged_apps[item.app_id] = _merge_project_app_settings(item, None)
+
+    for app_id, payload in current_apps.items():
+        if not isinstance(app_id, str) or app_id in merged_apps:
+            continue
+        merged_apps[app_id] = payload
+
+    return merged_apps
+
+
+def _merge_project_app_settings(source: AppSettingsSource, existing: dict[str, Any] | None) -> dict[str, Any]:
+    existing_payload = dict(existing or {})
+    if source.normalize is None:
+        return _deep_merge_payload(source.defaults, existing_payload)
+    merged_payload = _deep_merge_payload(source.defaults, existing_payload)
+    normalized = source.normalize(merged_payload)
+    if not isinstance(normalized, dict):
+        raise PzError(
+            code="PZ_APP_SETTINGS_NORMALIZER_INVALID",
+            message=f"App settings normalizer for '{source.module_path}' must return a mapping payload.",
+            stage="cli",
+            owner=_OWNER,
+            action="merge_project_app_settings",
+        )
+    return dict(normalized)
+
+
+def _ordered_app_settings_app_ids(
+    project_dir: Path,
+    *,
+    installed_apps: list[str],
+    current_apps: dict[str, Any],
+    source_by_app_id: dict[str, AppSettingsSource],
+) -> tuple[str, ...]:
+    source_by_module_path = {item.module_path: item for item in source_by_app_id.values()}
+    ordered: list[str] = []
+    seen: set[str] = set()
+
+    for ref in discover_declared_app_references(installed_apps, project_dir=project_dir):
+        source = source_by_module_path.get(ref.module_path)
+        if source is None or source.app_id in seen:
+            continue
+        seen.add(source.app_id)
+        ordered.append(source.app_id)
+
+    for app_id in current_apps:
+        if not isinstance(app_id, str) or app_id in seen:
+            continue
+        seen.add(app_id)
+        ordered.append(app_id)
+
+    for app_id in source_by_app_id:
+        if app_id in seen:
+            continue
+        seen.add(app_id)
+        ordered.append(app_id)
+
+    return tuple(ordered)
+
+
+def _managed_middlewares_payload(
+    project_dir: Path,
+    current_payload: dict[str, Any],
+    payload: dict[str, Any],
+    *,
+    preserve_existing: bool,
+) -> list[dict[str, Any]]:
+    generation_payload = _deep_merge_payload({}, payload)
+    generation_payload.pop("middlewares", None)
+    with active_settings_project(project_dir):
+        settings = compile_settings_snapshot_from_payload(project_dir, generation_payload)
+        with active_project_import_root(project_dir, extra_import_roots=settings.import_roots):
+            app_registry = compile_app_registry(settings, project_dir=project_dir, run_init_hooks=False)
+            manifest = compile_conventional_middleware_manifest(settings, app_registry)
+    if preserve_existing:
+        manifest = merge_explicit_middleware_order(_read_middleware_ids(current_payload), manifest)
+    return [_middleware_decl_payload(item) for item in manifest.middlewares]
+
+
+def _read_middleware_ids(payload: dict[str, Any]) -> tuple[str, ...]:
+    raw = payload.get("middlewares")
+    if not isinstance(raw, list):
+        return ()
+    out: list[str] = []
+    for item in raw:
+        if isinstance(item, dict):
+            middleware_id = str(item.get("id") or "").strip()
+            if middleware_id:
+                out.append(middleware_id)
+    return tuple(out)
+
+
+def _middleware_decl_payload(item: Any) -> dict[str, Any]:
+    priority = getattr(item, "priority", 100)
+    payload: dict[str, Any] = {
+        "id": str(item.id),
+        "owner": str(item.owner),
+        "factory": str(item.factory),
+        "priority": int(100 if priority is None else priority),
+    }
+    if getattr(item, "replace", None):
+        payload["replace"] = str(item.replace)
+    if getattr(item, "params_model", None):
+        payload["params_model"] = str(item.params_model)
+    if getattr(item, "params", None):
+        payload["params"] = dict(item.params)
+    return payload
+
+
+def _ordered_root_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    ordered: dict[str, Any] = {}
+    for key in (
+        "installed_apps",
+        "middlewares",
+        "catalog",
+        "project",
+        "routing",
+        "events",
+        "app_replacements",
+        "apps",
+    ):
+        if key in payload:
+            ordered[key] = payload[key]
+    for key, value in payload.items():
+        if key not in ordered:
+            ordered[key] = value
+    return ordered
+
+
+__all__ = [
+    "AppSettingsSource",
+    "SettingsUpdateDriftResult",
+    "SettingsWriteResult",
+    "discover_settings_sources",
+    "initialize_settings_file",
+    "inspect_settings_update_drift",
+    "update_settings_file",
+]