pz-cli 5.0.0__py3-none-any.whl

pz_core/assembly/app_discovery.py

@@ -0,0 +1,1240 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from functools import lru_cache
+import importlib.util
+from importlib.util import find_spec
+from pathlib import Path, PurePosixPath
+import re
+import sys
+import tomllib
+import types
+from typing import TYPE_CHECKING, Any, Iterable
+
+from pz_core.core.errors import PzError
+from pz_core.project_sources import load_official_source_catalog
+
+if TYPE_CHECKING:
+    from pz_core.authoring.dev_manifest import DevBinding, DevManifest
+
+
+_SKIP_DISCOVERY_PARTS = {
+    ".git",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "docs",
+    "test",
+    "tests",
+}
+_DEPENDENCY_NAME_RE = re.compile(r"^\s*([A-Za-z0-9_.-]+)")
+_FORMAL_APP_ID_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+
+
+@dataclass(frozen=True, slots=True)
+class DiscoveredAppReference:
+    module_path: str
+    import_root: Path | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class VisibleAppProjection:
+    app_id: str
+    module_path: str
+    visible_root: Path
+    source_root: Path
+    import_root: Path
+    binding_key: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class StaticAppDeclaration:
+    module_path: str
+    app_id: str
+    name: str
+    version: str
+    required_pz: str
+    priority: object | None = None
+    requires_apps: object | None = None
+    required_protocols: object | None = None
+    method_names: frozenset[str] = frozenset()
+
+
+_MISSING_MODULE = object()
+
+
+def _prefer_minimal_package_root(candidate: Path) -> Path:
+    """Prefer the inner package root for formal minimal-package containers."""
+    nested_package_root = candidate / candidate.name
+    if (nested_package_root / "__init__.py").is_file():
+        return nested_package_root.resolve()
+    return candidate.resolve()
+
+
+def resolve_package_root(module_path: str) -> Path | None:
+    package_name = _validate_declared_app_token(
+        str(module_path or "").strip(),
+        action="resolve_package_root",
+    )
+    if not package_name:
+        return None
+    located = _resolve_package_root_cached(package_name, _sys_path_fingerprint())
+    if located is not None:
+        return Path(located)
+    try:
+        spec = find_spec(package_name)
+    except Exception:
+        return None
+    if spec is None:
+        return None
+    if spec.submodule_search_locations:
+        return Path(next(iter(spec.submodule_search_locations))).resolve()
+    if spec.origin:
+        return Path(spec.origin).resolve().parent
+    return None
+
+
+@lru_cache(maxsize=512)
+def _resolve_package_root_cached(
+    package_name: str,
+    sys_path_fingerprint: tuple[str, ...],
+) -> str | None:
+    normalized = str(package_name or "").strip()
+    if not normalized:
+        return None
+    relative_path = Path(*normalized.split("."))
+    for entry in sys_path_fingerprint:
+        base = str(entry or "").strip()
+        if not base:
+            continue
+        candidate = Path(base).expanduser().resolve() / relative_path
+        if candidate.is_dir():
+            return str(_prefer_minimal_package_root(candidate))
+        package_file = candidate.with_suffix(".py")
+        if package_file.is_file():
+            return str(package_file.resolve().parent)
+    return None
+
+
+def resolve_declared_app_id(module_path: str) -> str:
+    package_name = _validate_declared_app_token(
+        str(module_path or "").strip(),
+        action="resolve_app_id",
+    )
+    if not package_name:
+        return ""
+    try:
+        return read_static_app_declaration(package_name, action="resolve_app_id").app_id
+    except PzError as exc:
+        if exc.code == "PZ_APP_DECLARATION_NOT_FOUND":
+            raise PzError(
+                code="PZ_APP_IMPORT_FAILED",
+                message=f"Failed to locate app module '{package_name}.apps'.",
+                stage="apps",
+                owner=package_name,
+                action="resolve_app_id",
+                detail=exc.detail,
+            ) from exc
+        raise
+
+
+def read_static_app_declaration(
+    module_path: str,
+    *,
+    action: str = "read_static_app_declaration",
+) -> StaticAppDeclaration:
+    package_name = _validate_declared_app_token(
+        str(module_path or "").strip(),
+        action=action,
+    )
+    if not package_name:
+        raise PzError(
+            code="PZ_APP_INVALID_PATH",
+            message="App path must declare a directory/package name.",
+            stage="apps",
+            owner="apps",
+            action=action,
+        )
+    return _read_static_app_declaration_cached(
+        package_name,
+        _sys_path_fingerprint(),
+        action,
+    )
+
+
+@lru_cache(maxsize=1024)
+def _read_static_app_declaration_cached(
+    package_name: str,
+    sys_path_fingerprint: tuple[str, ...],
+    action: str,
+) -> StaticAppDeclaration:
+    app_module_name = f"{package_name}.apps"
+    origin_path = _locate_apps_module_path(app_module_name, sys_path_fingerprint)
+    if origin_path is None:
+        raise PzError(
+            code="PZ_APP_DECLARATION_NOT_FOUND",
+            message=f"App module '{app_module_name}' was not found.",
+            stage="apps",
+            owner=package_name,
+            action=action,
+        )
+    if not origin_path.is_file():
+        raise PzError(
+            code="PZ_APP_ENTRY_MISSING",
+            message=f"App module '{app_module_name}' does not expose 'app'.",
+            stage="apps",
+            owner=package_name,
+            action=action,
+        )
+    try:
+        source = origin_path.read_text(encoding="utf-8")
+        tree = ast.parse(source, filename=str(origin_path))
+    except Exception as exc:
+        raise PzError(
+            code="PZ_APP_DECLARATION_INVALID",
+            message=f"Failed to parse app module '{app_module_name}': {exc}",
+            stage="apps",
+            owner=package_name,
+            action=action,
+        ) from exc
+
+    classes = {node.name: node for node in tree.body if isinstance(node, ast.ClassDef)}
+    app_class_name = _read_module_app_class_name(tree)
+    if not app_class_name:
+        raise PzError(
+            code="PZ_APP_ENTRY_MISSING",
+            message=f"App module '{app_module_name}' does not expose 'app = <AppClass>()'.",
+            stage="apps",
+            owner=package_name,
+            action=action,
+        )
+    class_node = classes.get(app_class_name)
+    if class_node is None:
+        raise PzError(
+            code="PZ_APP_ENTRY_MISSING",
+            message=f"App module '{app_module_name}' declares app from unknown class '{app_class_name}'.",
+            stage="apps",
+            owner=package_name,
+            action=action,
+        )
+
+    fields = _read_static_class_fields(class_node)
+    app_id = _read_static_required_string_field(
+        fields,
+        "id",
+        package_name=package_name,
+        code="PZ_APP_ID_MISSING",
+        invalid_code="PZ_APP_ID_INVALID",
+        action=action,
+    )
+    if not app_id.isidentifier():
+        raise PzError(
+            code="PZ_APP_ID_INVALID",
+            message=f"App '{package_name}' must declare a valid app.id identifier.",
+            stage="apps",
+            owner=package_name,
+            action=action,
+        )
+    return StaticAppDeclaration(
+        module_path=package_name,
+        app_id=app_id,
+        name=_read_static_required_string_field(
+            fields,
+            "name",
+            package_name=app_id,
+            code="PZ_APP_NAME_MISSING",
+            invalid_code="PZ_APP_NAME_MISSING",
+            action=action,
+        ),
+        version=_read_static_required_string_field(
+            fields,
+            "version",
+            package_name=app_id,
+            code="PZ_APP_VERSION_MISSING",
+            invalid_code="PZ_APP_VERSION_MISSING",
+            action=action,
+        ),
+        required_pz=_read_static_required_string_field(
+            fields,
+            "required_pz",
+            package_name=app_id,
+            code="PZ_APP_REQUIRED_PZ_MISSING",
+            invalid_code="PZ_APP_REQUIRED_PZ_MISSING",
+            action=action,
+        ),
+        priority=_read_static_optional_field(fields, "priority"),
+        requires_apps=_read_static_optional_field(fields, "requires_apps"),
+        required_protocols=_read_static_optional_field(fields, "required_protocols"),
+        method_names=frozenset(
+            statement.name
+            for statement in class_node.body
+            if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef))
+        ),
+    )
+
+
+def _sys_path_fingerprint() -> tuple[str, ...]:
+    return tuple(str(entry or "") for entry in sys.path)
+
+
+def import_app_settings_module(module_path: str, *, action: str) -> Any | None:
+    module_name = f"{module_path}.settings"
+    module_file = _locate_declared_app_sibling_module_file(module_path, "settings.py")
+    if module_file is None:
+        return None
+    return _import_entrypoint_module_from_file(module_name, module_file, action=action)
+
+
+def import_app_entrypoint_module_from_decl(module_path: str, *, action: str) -> Any:
+    module_name = f"{module_path}.apps"
+    module_file = _locate_declared_app_sibling_module_file(module_path, "apps.py")
+    if module_file is None:
+        raise PzError(
+            code="PZ_APP_IMPORT_FAILED",
+            message=f"Failed to locate app module '{module_name}'.",
+            stage="apps",
+            owner=module_path,
+            action=action,
+        )
+    return _import_entrypoint_module_from_file(module_name, module_file, action=action)
+
+
+def _import_entrypoint_module_from_file(
+    module_name: str, module_file: Path, *, action: str
+) -> Any:
+    package_name, _, leaf_name = module_name.rpartition(".")
+    package_root = module_file.parent
+    restore_names = [module_name]
+    package_parts = package_name.split(".") if package_name else []
+    package_dirs = (
+        [
+            *(
+                package_root.parents[len(package_parts) - index - 2]
+                for index in range(len(package_parts) - 1)
+            ),
+            package_root,
+        ]
+        if package_parts
+        else []
+    )
+    for index in range(1, len(package_parts) + 1):
+        restore_names.append(".".join(package_parts[:index]))
+    saved_modules = {
+        name: sys.modules.get(name, _MISSING_MODULE) for name in restore_names
+    }
+    try:
+        for index in range(1, len(package_parts) + 1):
+            current_name = ".".join(package_parts[:index])
+            current_dir = package_dirs[index - 1]
+            package_module = types.ModuleType(current_name)
+            package_module.__file__ = str(current_dir / "__init__.py")
+            package_module.__path__ = [str(current_dir)]
+            package_module.__package__ = current_name
+            package_module.__spec__ = importlib.util.spec_from_loader(
+                current_name, loader=None, is_package=True
+            )
+            sys.modules[current_name] = package_module
+        spec = importlib.util.spec_from_file_location(
+            module_name,
+            module_file,
+            submodule_search_locations=[str(package_root)]
+            if leaf_name == "__init__"
+            else None,
+        )
+        if spec is None or spec.loader is None:
+            raise ImportError(f"cannot load module from {module_file}")
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        spec.loader.exec_module(module)
+        return module
+    except PzError:
+        raise
+    except Exception as exc:
+        raise PzError(
+            code="PZ_APP_IMPORT_FAILED",
+            message=f"Failed to import app module '{module_name}': {exc}",
+            stage="apps",
+            owner=module_name,
+            action=action,
+        ) from exc
+    finally:
+        for name, saved in saved_modules.items():
+            if saved is _MISSING_MODULE:
+                sys.modules.pop(name, None)
+            else:
+                sys.modules[name] = saved
+
+
+def _locate_declared_app_sibling_module_file(
+    module_path: str,
+    file_name: str,
+) -> Path | None:
+    apps_module_path = _locate_apps_module_path(
+        f"{module_path}.apps", _sys_path_fingerprint()
+    )
+    if apps_module_path is None:
+        return None
+    candidate = apps_module_path.with_name(file_name)
+    return candidate if candidate.is_file() else None
+
+
+def _locate_apps_module_path(
+    app_module_name: str,
+    sys_path_fingerprint: tuple[str, ...],
+) -> Path | None:
+    origin = _locate_apps_module_file_cached(app_module_name, sys_path_fingerprint)
+    if origin is not None:
+        return Path(origin)
+    original_sys_path = sys.path
+    sys.path = list(sys_path_fingerprint)
+    try:
+        spec = find_spec(app_module_name)
+    except Exception:
+        return None
+    finally:
+        sys.path = original_sys_path
+    if spec is None or not spec.origin:
+        return None
+    return Path(spec.origin)
+
+
+def _locate_apps_module_file(app_module_name: str) -> Path | None:
+    located = _locate_apps_module_file_cached(app_module_name, _sys_path_fingerprint())
+    return Path(located) if located is not None else None
+
+
+@lru_cache(maxsize=512)
+def _locate_apps_module_file_cached(
+    app_module_name: str,
+    sys_path_fingerprint: tuple[str, ...],
+) -> str | None:
+    module_name = str(app_module_name or "").strip()
+    if not module_name:
+        return None
+    parts = module_name.split(".")
+    relative_path = Path(*parts).with_suffix(".py")
+    for entry in sys_path_fingerprint:
+        base = str(entry or "").strip()
+        if not base:
+            continue
+        candidate = Path(base).expanduser().resolve() / relative_path
+        if candidate.is_file():
+            return str(candidate)
+        if len(parts) == 2 and parts[-1] == "apps":
+            nested_apps = (
+                Path(base).expanduser().resolve() / parts[0] / parts[0] / "apps.py"
+            )
+            if nested_apps.is_file():
+                return str(nested_apps.resolve())
+    return None
+
+
+def _read_static_class_app_id(node: ast.ClassDef) -> str:
+    fields = _read_static_class_fields(node)
+    value = fields.get("id")
+    if isinstance(value, str) and value.strip().isidentifier():
+        return value.strip()
+    return ""
+
+
+def _read_module_app_class_name(tree: ast.Module) -> str:
+    for node in tree.body:
+        value: ast.AST | None
+        if isinstance(node, ast.Assign):
+            value = node.value
+            targets = node.targets
+        elif isinstance(node, ast.AnnAssign):
+            value = node.value
+            targets = (node.target,)
+        else:
+            continue
+        if value is None:
+            continue
+        for target in targets:
+            if isinstance(target, ast.Name) and target.id == "app":
+                return _read_static_app_instance_class_name(value)
+    return ""
+
+
+def _read_static_app_instance_class_name(node: ast.AST) -> str:
+    if isinstance(node, ast.Call):
+        return _read_static_app_instance_class_name(node.func)
+    if isinstance(node, ast.Name):
+        return node.id
+    return ""
+
+
+def _read_static_class_fields(node: ast.ClassDef) -> dict[str, object]:
+    fields: dict[str, object] = {}
+    for statement in node.body:
+        value: ast.AST | None
+        targets: Iterable[ast.AST]
+        if isinstance(statement, ast.Assign):
+            value = statement.value
+            targets = statement.targets
+        elif isinstance(statement, ast.AnnAssign):
+            value = statement.value
+            targets = (statement.target,)
+        else:
+            continue
+        if value is None:
+            continue
+        for target in targets:
+            if isinstance(target, ast.Name):
+                fields[target.id] = _read_static_literal(value)
+    return fields
+
+
+def _read_static_literal(node: ast.AST) -> object:
+    try:
+        return ast.literal_eval(node)
+    except Exception:
+        return _MISSING_MODULE
+
+
+def _read_static_required_string_field(
+    fields: dict[str, object],
+    field_name: str,
+    *,
+    package_name: str,
+    code: str,
+    invalid_code: str,
+    action: str,
+) -> str:
+    value = fields.get(field_name, _MISSING_MODULE)
+    if value is _MISSING_MODULE:
+        raise PzError(
+            code=code,
+            message=f"App '{package_name}' must declare static string field '{field_name}'.",
+            stage="apps",
+            owner=package_name,
+            action=action,
+        )
+    if not isinstance(value, str) or not value.strip():
+        raise PzError(
+            code=invalid_code,
+            message=f"App '{package_name}' must declare non-empty static string field '{field_name}'.",
+            stage="apps",
+            owner=package_name,
+            action=action,
+        )
+    return value.strip()
+
+
+def _read_static_optional_field(
+    fields: dict[str, object], field_name: str
+) -> object | None:
+    value = fields.get(field_name, _MISSING_MODULE)
+    if value is _MISSING_MODULE:
+        return None
+    return value
+
+
+def _normalize_package_name(module_path: str) -> str:
+    return str(module_path or "").strip()
+
+
+def _validate_declared_app_token(module_path: str, *, action: str) -> str:
+    normalized = str(module_path or "").strip()
+    if not normalized:
+        return ""
+    if ":" in normalized or normalized.endswith(".apps"):
+        raise PzError(
+            code="PZ_APP_INVALID_PATH",
+            message=(
+                f"App path '{normalized}' must declare a directory/package name only; "
+                "installed_apps does not accept '<pkg>.apps' or '<pkg>.apps:app'."
+            ),
+            stage="apps",
+            owner=normalized,
+            action=action,
+        )
+    return normalized
+
+
+def _read_project_dir(project_dir: str | Path | None) -> Path | None:
+    if project_dir is None:
+        return None
+    return Path(project_dir).expanduser().resolve()
+
+
+def _normalize_distribution_name(value: str) -> str:
+    return re.sub(r"[-_.]+", "-", str(value or "").strip().lower()).strip("-")
+
+
+def _is_skipped_discovery_dir(path: Path) -> bool:
+    name = path.name
+    if name.startswith("."):
+        return True
+    return name in _SKIP_DISCOVERY_PARTS
+
+
+def _read_standard_apps_py_app_id(apps_py: Path) -> str:
+    if not apps_py.is_file():
+        return ""
+    try:
+        source = apps_py.read_text(encoding="utf-8")
+        tree = ast.parse(source, filename=str(apps_py))
+    except Exception:
+        return ""
+
+    class_ids: dict[str, str] = {}
+    for node in tree.body:
+        if not isinstance(node, ast.ClassDef):
+            continue
+        class_id = _read_static_class_app_id(node)
+        if class_id:
+            class_ids[node.name] = class_id
+
+    for node in tree.body:
+        if not isinstance(node, ast.Assign):
+            continue
+        for target in node.targets:
+            if isinstance(target, ast.Name) and target.id == "app":
+                class_name = _read_static_app_instance_class_name(node.value)
+                if class_name and class_name in class_ids:
+                    return class_ids[class_name]
+    return ""
+
+
+def _has_standard_apps_py(apps_py: Path) -> bool:
+    return bool(_read_standard_apps_py_app_id(apps_py))
+
+
+def _visible_app_error(
+    code: str,
+    message: str,
+    *,
+    owner: str,
+) -> PzError:
+    return PzError(
+        code=code,
+        message=message,
+        stage="apps",
+        owner=owner,
+        action="iter_visible_app_projections",
+    )
+
+
+def _read_visible_leaf_app_id(leaf_root: Path) -> str:
+    pyproject_path = leaf_root / "pyproject.toml"
+    if not pyproject_path.is_file():
+        return _read_bundled_visible_leaf_app_id(leaf_root)
+    try:
+        payload = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, tomllib.TOMLDecodeError):
+        return ""
+    project = payload.get("project")
+    if not isinstance(project, dict):
+        return ""
+    distribution = project.get("name")
+    if not isinstance(distribution, str) or distribution != distribution.strip():
+        return ""
+    app_id = distribution.replace("-", "_")
+    if not _FORMAL_APP_ID_RE.fullmatch(app_id) or leaf_root.name != app_id:
+        return ""
+    module_root = leaf_root / app_id
+    if not (module_root / "__init__.py").is_file():
+        return ""
+    if _read_standard_apps_py_app_id(module_root / "apps.py") != app_id:
+        return ""
+    return app_id
+
+
+def _read_project_distribution(project_root: Path) -> str:
+    pyproject_path = project_root / "pyproject.toml"
+    if not pyproject_path.is_file():
+        return ""
+    try:
+        payload = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, tomllib.TOMLDecodeError):
+        return ""
+    project = payload.get("project")
+    if not isinstance(project, dict):
+        return ""
+    distribution = project.get("name")
+    return distribution if isinstance(distribution, str) else ""
+
+
+def _read_bundled_visible_leaf_app_id(leaf_root: Path) -> str:
+    try:
+        resolved_leaf = leaf_root.resolve(strict=True)
+    except (OSError, RuntimeError):
+        return ""
+    for source in load_official_source_catalog().values():
+        if not source.bootstrap:
+            continue
+        project_distributions = {
+            distribution
+            for distribution, child in source.children.items()
+            if child.kind == "project" and child.subpath == PurePosixPath(".")
+        }
+        for child in source.children.values():
+            app_id = child.expected_app_id
+            if child.kind != "app" or app_id is None or app_id != leaf_root.name:
+                continue
+            project_root = resolved_leaf
+            for _part in child.subpath.parts:
+                project_root = project_root.parent
+            if project_root.joinpath(*child.subpath.parts) != resolved_leaf:
+                continue
+            if _read_project_distribution(project_root) not in project_distributions:
+                continue
+            module_root = resolved_leaf / app_id
+            if not (module_root / "__init__.py").is_file():
+                continue
+            if _read_standard_apps_py_app_id(module_root / "apps.py") == app_id:
+                return app_id
+    return ""
+
+
+def _build_visible_projection(
+    leaf_root: Path,
+    *,
+    binding_key: str | None,
+) -> VisibleAppProjection | None:
+    app_id = _read_visible_leaf_app_id(leaf_root)
+    if not app_id:
+        return None
+    try:
+        source_root = leaf_root.resolve(strict=True)
+    except (OSError, RuntimeError):
+        return None
+    return VisibleAppProjection(
+        app_id=app_id,
+        module_path=app_id,
+        visible_root=leaf_root,
+        source_root=source_root,
+        import_root=source_root,
+        binding_key=binding_key,
+    )
+
+
+def _binding_source_root(
+    project_dir: Path,
+    manifest: DevManifest,
+    binding: DevBinding,
+) -> Path:
+    if binding.source_kind == "link":
+        root = Path(binding.source)
+    else:
+        assert binding.repo_key is not None
+        root = project_dir / Path(*manifest.repos[binding.repo_key].checkout.parts)
+    if binding.subpath == PurePosixPath("."):
+        return root
+    return root / Path(*binding.subpath.parts)
+
+
+def _resolve_managed_link_target(
+    project_dir: Path,
+    manifest: DevManifest,
+    *,
+    binding_key: str,
+    binding: DevBinding,
+) -> tuple[Path, Path]:
+    if len(binding.link.parts) != 2 or binding.link.parts[0] != "apps":
+        raise _visible_app_error(
+            "PZ_VISIBLE_APP_BINDING_INVALID",
+            f"managed binding {binding_key!r} must project directly below apps/.",
+            owner=binding_key,
+        )
+    link_name = binding.link.parts[-1]
+    if link_name.startswith(".") or link_name in _SKIP_DISCOVERY_PARTS:
+        raise _visible_app_error(
+            "PZ_VISIBLE_APP_BINDING_INVALID",
+            f"managed binding {binding_key!r} uses a hidden projection path.",
+            owner=binding_key,
+        )
+    link = project_dir / Path(*binding.link.parts)
+    if not link.is_symlink():
+        raise _visible_app_error(
+            "PZ_VISIBLE_APP_BINDING_INVALID",
+            f"managed binding {binding_key!r} is missing its symbolic link.",
+            owner=binding_key,
+        )
+    expected = _binding_source_root(project_dir, manifest, binding)
+    try:
+        actual_root = link.resolve(strict=True)
+        expected_root = expected.resolve(strict=True)
+    except (OSError, RuntimeError) as exc:
+        raise _visible_app_error(
+            "PZ_VISIBLE_APP_BINDING_INVALID",
+            f"managed binding {binding_key!r} has a broken or looping target.",
+            owner=binding_key,
+        ) from exc
+    if actual_root != expected_root:
+        raise _visible_app_error(
+            "PZ_VISIBLE_APP_BINDING_INVALID",
+            f"managed binding {binding_key!r} does not match its manifest target.",
+            owner=binding_key,
+        )
+    return link, actual_root
+
+
+def _managed_binding_projections(
+    project_dir: Path,
+    manifest: DevManifest,
+) -> tuple[VisibleAppProjection, ...]:
+    projections: list[VisibleAppProjection] = []
+    for binding_key, binding in sorted(
+        manifest.bindings.items(),
+        key=lambda item: item[1].link.as_posix(),
+    ):
+        link, _actual_root = _resolve_managed_link_target(
+            project_dir,
+            manifest,
+            binding_key=binding_key,
+            binding=binding,
+        )
+        if link.name != binding_key:
+            raise _visible_app_error(
+                "PZ_VISIBLE_APP_BINDING_INVALID",
+                f"managed binding {binding_key!r} must use the same link name.",
+                owner=binding_key,
+            )
+        if binding.kind == "app":
+            projection = _build_visible_projection(link, binding_key=binding_key)
+            if projection is None or projection.app_id != binding_key:
+                raise _visible_app_error(
+                    "PZ_VISIBLE_APP_BINDING_INVALID",
+                    f"managed app binding {binding_key!r} does not expose its declared leaf.",
+                    owner=binding_key,
+                )
+            projections.append(projection)
+            continue
+        directory_projections: list[VisibleAppProjection] = []
+        try:
+            children = sorted(link.iterdir(), key=lambda item: item.name)
+        except OSError as exc:
+            raise _visible_app_error(
+                "PZ_VISIBLE_APP_BINDING_INVALID",
+                f"managed directory binding {binding_key!r} cannot be read.",
+                owner=binding_key,
+            ) from exc
+        for child in children:
+            if _is_skipped_discovery_dir(child) or child.is_symlink():
+                continue
+            if not child.is_dir():
+                continue
+            projection = _build_visible_projection(child, binding_key=binding_key)
+            if projection is not None:
+                directory_projections.append(projection)
+        if not directory_projections:
+            raise _visible_app_error(
+                "PZ_VISIBLE_APP_BINDING_INVALID",
+                f"managed directory binding {binding_key!r} exposes no formal top-level leaf.",
+                owner=binding_key,
+            )
+        projections.extend(directory_projections)
+    return tuple(projections)
+
+
+def _is_safe_unmanaged_link(project_dir: Path, source_root: Path) -> bool:
+    try:
+        relative = source_root.relative_to(project_dir)
+    except ValueError:
+        return False
+    return not any(part.startswith(".") for part in relative.parts)
+
+
+def _unmanaged_local_projections(
+    project_dir: Path,
+    managed_links: frozenset[Path],
+) -> tuple[VisibleAppProjection, ...]:
+    apps_root = project_dir / "apps"
+    if not apps_root.is_dir():
+        return ()
+    projections: list[VisibleAppProjection] = []
+    try:
+        entries = sorted(apps_root.iterdir(), key=lambda item: item.name)
+    except OSError:
+        return ()
+    for entry in entries:
+        if _is_skipped_discovery_dir(entry) or entry in managed_links:
+            continue
+        if entry.is_symlink():
+            try:
+                source_root = entry.resolve(strict=True)
+            except (OSError, RuntimeError):
+                continue
+            if not _is_safe_unmanaged_link(project_dir, source_root):
+                continue
+        elif entry.is_dir():
+            source_root = entry.resolve()
+        else:
+            continue
+        projection = _build_visible_projection(entry, binding_key=None)
+        if projection is None or projection.app_id != entry.name:
+            continue
+        if entry.is_symlink() and projection.source_root != source_root:
+            continue
+        projections.append(projection)
+    return tuple(projections)
+
+
+def iter_visible_app_projections(
+    project_dir: str | Path,
+) -> tuple[VisibleAppProjection, ...]:
+    from pz_core.authoring.dev_manifest import load_dev_manifest
+
+    resolved_project_dir = Path(project_dir).expanduser().resolve()
+    manifest = load_dev_manifest(resolved_project_dir)
+    managed = (
+        ()
+        if manifest is None
+        else _managed_binding_projections(
+            resolved_project_dir,
+            manifest,
+        )
+    )
+    managed_links = (
+        frozenset()
+        if manifest is None
+        else frozenset(
+            resolved_project_dir / Path(*binding.link.parts)
+            for binding in manifest.bindings.values()
+        )
+    )
+    unmanaged = _unmanaged_local_projections(resolved_project_dir, managed_links)
+    ordered = sorted(
+        (*managed, *unmanaged),
+        key=lambda item: (item.visible_root.as_posix(), item.app_id),
+    )
+    by_id: dict[str, VisibleAppProjection] = {}
+    for projection in ordered:
+        existing = by_id.get(projection.app_id)
+        if existing is not None:
+            raise _visible_app_error(
+                "PZ_VISIBLE_APP_DUPLICATE",
+                (
+                    f"visible app {projection.app_id!r} is exposed by both "
+                    f"{existing.visible_root} and {projection.visible_root}."
+                ),
+                owner=projection.app_id,
+            )
+        by_id[projection.app_id] = projection
+    return tuple(ordered)
+
+
+def _discover_project_local_app_references(
+    project_dir: Path,
+    module_path: str,
+    projections: tuple[VisibleAppProjection, ...],
+) -> tuple[DiscoveredAppReference, ...]:
+    if module_path == "apps":
+        return tuple(
+            DiscoveredAppReference(
+                module_path=item.module_path,
+                import_root=item.import_root,
+            )
+            for item in projections
+        )
+    return tuple(
+        DiscoveredAppReference(
+            module_path=item.module_path,
+            import_root=item.import_root,
+        )
+        for item in projections
+        if module_path in {item.app_id, item.module_path}
+    )
+
+
+def _has_project_local_app_candidate(
+    project_dir: Path,
+    module_path: str,
+    projections: tuple[VisibleAppProjection, ...],
+) -> bool:
+    if module_path == "apps":
+        return (project_dir / "apps").is_dir()
+    return any(module_path in {item.app_id, item.module_path} for item in projections)
+
+
+def _discover_leaf_apps_from_import_root(
+    module_path: str,
+    package_root: Path,
+    *,
+    import_root: Path | None = None,
+) -> tuple[DiscoveredAppReference, ...]:
+    if _has_standard_apps_py(package_root / "apps.py"):
+        return (
+            DiscoveredAppReference(module_path=module_path, import_root=import_root),
+        )
+
+    discovered: list[DiscoveredAppReference] = []
+    for child in sorted(package_root.iterdir(), key=lambda item: item.name):
+        if not child.is_dir():
+            continue
+        if child.name.startswith(".") or child.name in _SKIP_DISCOVERY_PARTS:
+            continue
+        if not (child / "__init__.py").is_file():
+            continue
+        child_module_path = f"{module_path}.{child.name}"
+        if _has_standard_apps_py(child / "apps.py"):
+            discovered.append(
+                DiscoveredAppReference(
+                    module_path=child_module_path, import_root=import_root
+                )
+            )
+            continue
+        discovered.extend(
+            _discover_leaf_apps_from_import_root(
+                child_module_path, child, import_root=import_root
+            )
+        )
+    return tuple(discovered)
+
+
+def _derive_import_root(package_root: Path, module_path: str) -> Path | None:
+    parts = [
+        segment for segment in str(module_path or "").strip().split(".") if segment
+    ]
+    if not parts:
+        return None
+    try:
+        return package_root.parents[len(parts) - 1].resolve()
+    except IndexError:
+        return None
+
+
+def _is_physical_project_source_path(project_dir: Path, package_root: Path) -> bool:
+    try:
+        relative = package_root.resolve().relative_to(project_dir.resolve())
+    except (OSError, ValueError):
+        return False
+    return ".sources" in relative.parts
+
+
+def discover_declared_app_references(
+    declared_apps: Iterable[str],
+    *,
+    project_dir: str | Path | None = None,
+) -> tuple[DiscoveredAppReference, ...]:
+    resolved_project_dir = _read_project_dir(project_dir)
+    visible_projections = (
+        ()
+        if resolved_project_dir is None
+        else iter_visible_app_projections(resolved_project_dir)
+    )
+    discovered: list[DiscoveredAppReference] = []
+    seen_paths: set[str] = set()
+
+    for raw_item in declared_apps:
+        normalized = _validate_declared_app_token(
+            str(raw_item or "").strip(),
+            action="discover_declared_app_references",
+        )
+        if not normalized:
+            continue
+
+        refs: tuple[DiscoveredAppReference, ...] = ()
+        project_local_candidate_exists = False
+        if resolved_project_dir is not None:
+            project_local_candidate_exists = _has_project_local_app_candidate(
+                resolved_project_dir,
+                normalized,
+                visible_projections,
+            )
+            refs = _discover_project_local_app_references(
+                resolved_project_dir,
+                normalized,
+                visible_projections,
+            )
+        if not refs and not project_local_candidate_exists:
+            package_root = resolve_package_root(normalized)
+            if (
+                package_root is not None
+                and resolved_project_dir is not None
+                and _is_physical_project_source_path(
+                    resolved_project_dir,
+                    package_root,
+                )
+            ):
+                project_local_candidate_exists = True
+            elif package_root is not None:
+                refs = _discover_leaf_apps_from_import_root(
+                    normalized,
+                    package_root,
+                    import_root=_derive_import_root(package_root, normalized),
+                )
+
+        if not refs and not project_local_candidate_exists:
+            refs = (DiscoveredAppReference(module_path=normalized),)
+
+        for ref in refs:
+            if ref.module_path in seen_paths:
+                continue
+            seen_paths.add(ref.module_path)
+            discovered.append(ref)
+
+    return tuple(discovered)
+
+
+def resolve_import_roots_for_app_references(
+    references: Iterable[DiscoveredAppReference],
+) -> tuple[Path, ...]:
+    seen_roots: set[Path] = set()
+    import_roots: list[Path] = []
+    for ref in references:
+        if ref.import_root is None:
+            continue
+        _append_import_root(
+            ref.import_root, import_roots=import_roots, seen_roots=seen_roots
+        )
+        for dependency_root in _resolve_local_path_dependency_import_roots(
+            ref.import_root
+        ):
+            _append_import_root(
+                dependency_root, import_roots=import_roots, seen_roots=seen_roots
+            )
+    return tuple(import_roots)
+
+
+def resolve_declared_app_import_roots(
+    declared_apps: Iterable[str],
+    *,
+    project_dir: str | Path | None = None,
+) -> tuple[Path, ...]:
+    return resolve_import_roots_for_app_references(
+        discover_declared_app_references(declared_apps, project_dir=project_dir)
+    )
+
+
+def _append_import_root(
+    root: Path, *, import_roots: list[Path], seen_roots: set[Path]
+) -> None:
+    resolved = root.resolve()
+    if resolved in seen_roots:
+        return
+    seen_roots.add(resolved)
+    import_roots.append(resolved)
+
+
+def _resolve_local_path_dependency_import_roots(import_root: Path) -> tuple[Path, ...]:
+    roots: list[Path] = []
+    seen_roots: set[Path] = {import_root.resolve()}
+
+    def visit(package_root: Path) -> None:
+        source_paths = _local_uv_source_paths(package_root)
+        if not source_paths:
+            return
+        for dependency_name in _declared_dependency_names(package_root):
+            dependency_root = source_paths.get(dependency_name)
+            if dependency_root is None:
+                continue
+            resolved = dependency_root.resolve()
+            if resolved in seen_roots:
+                continue
+            seen_roots.add(resolved)
+            roots.append(resolved)
+            visit(resolved)
+
+    visit(import_root.resolve())
+    return tuple(roots)
+
+
+def _declared_dependency_names(package_root: Path) -> tuple[str, ...]:
+    payload = _read_pyproject_payload(package_root / "pyproject.toml")
+    project = payload.get("project")
+    if not isinstance(project, dict):
+        return ()
+    dependencies = project.get("dependencies")
+    if not isinstance(dependencies, list):
+        return ()
+    names: list[str] = []
+    for raw_dependency in dependencies:
+        if not isinstance(raw_dependency, str):
+            continue
+        name = _dependency_distribution_name(raw_dependency)
+        if name and name not in names:
+            names.append(name)
+    return tuple(names)
+
+
+def _dependency_distribution_name(value: str) -> str:
+    match = _DEPENDENCY_NAME_RE.match(value)
+    if match is None:
+        return ""
+    return _normalize_distribution_name(match.group(1))
+
+
+def _local_uv_source_paths(package_root: Path) -> dict[str, Path]:
+    mapped: dict[str, Path] = {}
+    for candidate in (package_root, *package_root.parents):
+        pyproject_path = candidate / "pyproject.toml"
+        payload = _read_pyproject_payload(pyproject_path)
+        if not payload:
+            continue
+        tool = payload.get("tool")
+        if not isinstance(tool, dict):
+            continue
+        uv = tool.get("uv")
+        if not isinstance(uv, dict):
+            continue
+        sources = uv.get("sources")
+        if not isinstance(sources, dict):
+            continue
+        for raw_name, raw_meta in sources.items():
+            name = _normalize_distribution_name(str(raw_name))
+            if not name or name in mapped:
+                continue
+            raw_path = ""
+            if isinstance(raw_meta, dict):
+                raw_path = str(raw_meta.get("path") or "").strip()
+            elif isinstance(raw_meta, str):
+                raw_path = raw_meta.strip()
+            if not raw_path:
+                continue
+            source_path = Path(raw_path).expanduser()
+            if not source_path.is_absolute():
+                source_path = pyproject_path.parent / source_path
+            if source_path.is_dir():
+                mapped[name] = source_path.resolve()
+    return mapped
+
+
+def _read_pyproject_payload(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    try:
+        payload = tomllib.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def discover_leaf_app_packages(
+    module_path: str,
+    *,
+    project_dir: str | Path | None = None,
+) -> tuple[str, ...]:
+    normalized = _validate_declared_app_token(
+        str(module_path or "").strip(),
+        action="discover_leaf_app_packages",
+    )
+    if not normalized:
+        return ()
+    return tuple(
+        ref.module_path
+        for ref in discover_declared_app_references(
+            (normalized,), project_dir=project_dir
+        )
+    )
+
+
+__all__ = [
+    "DiscoveredAppReference",
+    "StaticAppDeclaration",
+    "VisibleAppProjection",
+    "discover_declared_app_references",
+    "discover_leaf_app_packages",
+    "import_app_entrypoint_module_from_decl",
+    "import_app_settings_module",
+    "iter_visible_app_projections",
+    "read_static_app_declaration",
+    "resolve_declared_app_import_roots",
+    "resolve_declared_app_id",
+    "resolve_import_roots_for_app_references",
+    "resolve_package_root",
+]