pz-cli 5.0.0__py3-none-any.whl

pz_core/assembly/project/discovery.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+import importlib
+import os
+from pathlib import Path
+import sys
+from typing import Iterable
+
+from pz_core.assembly.app_discovery import iter_visible_app_projections
+from pz_core.assembly.project.context import ProjectContext
+from pz_core.core.errors import PzError
+from pz_core.runtime.environment_integrity import (
+    validate_current_environment,
+    validate_project_config_identity,
+)
+from pz_core.utils.project_jsonc import PROJECT_JSONC_NAME
+
+
+def _is_project_root(candidate: Path) -> bool:
+    return (candidate / PROJECT_JSONC_NAME).is_file()
+
+
+def _is_under_source_root(candidate: Path) -> bool:
+    return ".sources" in candidate.parts
+
+
+def _resolve_project_root(candidate: Path) -> Path:
+    expanded = candidate.expanduser()
+    search_roots: list[Path] = []
+    if expanded.is_absolute():
+        search_roots.append(expanded)
+    else:
+        search_roots.append((Path.cwd() / expanded).absolute())
+    resolved = expanded.resolve()
+    if resolved not in search_roots:
+        search_roots.append(resolved)
+    for search_root in search_roots:
+        for current in (search_root, *search_root.parents):
+            validate_project_config_identity(current)
+            if _is_project_root(current):
+                return current.resolve()
+    if any(_is_under_source_root(root) for root in search_roots):
+        raise PzError(
+            code="PZ_PROJECT_DIR_REQUIRED_FOR_SOURCE_ROOT",
+            message=(
+                "Cannot infer project_dir from a package source root. "
+                f"Set PZ_PROJECT_DIR or pass an explicit project_dir that resolves to a project with {PROJECT_JSONC_NAME}."
+            ),
+            stage="project",
+            owner="assembly.project",
+            action="resolve_project_context",
+        )
+    return resolved
+
+
+def _discover_project_dir_from_cwd() -> Path:
+    return _resolve_project_root(Path.cwd())
+
+
+def _read_project_dir_source(project_dir: str | os.PathLike[str]) -> str:
+    if not isinstance(project_dir, (str, os.PathLike)):
+        raise PzError(
+            code="PZ_PROJECT_DIR_INVALID",
+            message="project_dir must be a non-empty path when provided.",
+            stage="project",
+            owner="assembly.project",
+            action="resolve_project_context",
+        )
+    value = os.fspath(project_dir)
+    if not isinstance(value, str) or not value.strip():
+        raise PzError(
+            code="PZ_PROJECT_DIR_INVALID",
+            message="project_dir must be a non-empty path when provided.",
+            stage="project",
+            owner="assembly.project",
+            action="resolve_project_context",
+        )
+    return value
+
+
+def _read_project_dir_env(name: str) -> str | None:
+    raw = os.getenv(name)
+    if raw is None:
+        return None
+    if not raw.strip():
+        raise PzError(
+            code="PZ_PROJECT_DIR_INVALID",
+            message=f"{name} must be a non-empty path when configured.",
+            stage="project",
+            owner="assembly.project",
+            action="resolve_project_context",
+        )
+    return raw.strip()
+
+
+def resolve_project_context(
+    project_dir: str | os.PathLike[str] | None = None,
+) -> ProjectContext:
+    validate_current_environment(os.environ)
+    env_project_dir = _read_project_dir_env("PZ_PROJECT_DIR")
+    source = (
+        _read_project_dir_source(project_dir)
+        if project_dir is not None
+        else env_project_dir or _discover_project_dir_from_cwd()
+    )
+    try:
+        root = _resolve_project_root(Path(source))
+    except PzError as exc:
+        if (
+            project_dir is None
+            or env_project_dir is None
+            or exc.code != "PZ_PROJECT_DIR_REQUIRED_FOR_SOURCE_ROOT"
+        ):
+            raise
+        root = _resolve_project_root(Path(env_project_dir))
+    runtime_root = root / ".runtime"
+    project_config_path = root / PROJECT_JSONC_NAME
+    return ProjectContext(
+        project_dir=root,
+        project_config_path=project_config_path,
+        env_file_path=root / ".env",
+        cache_dir=runtime_root / "cache",
+        runtime_dir=runtime_root / "run",
+        asset_dir=root / ".assets",
+    )
+
+
+def _module_belongs_to_roots(module: object, roots: set[str]) -> bool:
+    module_file = getattr(module, "__file__", None)
+    if isinstance(module_file, str) and module_file:
+        resolved_file = str(Path(module_file).resolve())
+        for root in roots:
+            if resolved_file == root or resolved_file.startswith(root + os.sep):
+                return True
+
+    search_locations = getattr(module, "__path__", None)
+    if search_locations is None:
+        return False
+    for raw_location in search_locations:
+        resolved_location = str(Path(raw_location).resolve())
+        for root in roots:
+            if resolved_location == root or resolved_location.startswith(root + os.sep):
+                return True
+    return False
+
+
+def _managed_top_level_modules(
+    project_root: Path, import_roots: Iterable[Path]
+) -> set[str]:
+    module_names: set[str] = set()
+    if (project_root / "apps" / "__init__.py").is_file():
+        module_names.add("apps")
+    module_names.update(
+        projection.module_path.split(".", 1)[0]
+        for projection in iter_visible_app_projections(project_root)
+    )
+    for import_root in import_roots:
+        resolved_import_root = import_root.resolve()
+        if (
+            not resolved_import_root.is_dir()
+            or resolved_import_root == project_root
+            or resolved_import_root.is_relative_to(project_root)
+        ):
+            continue
+        for child in resolved_import_root.iterdir():
+            if child.is_dir() and (child / "__init__.py").is_file():
+                module_names.add(child.name)
+    return module_names
+
+
+@contextmanager
+def active_project_import_root(
+    project_dir: str | os.PathLike[str] | None,
+    *,
+    extra_import_roots: Iterable[str | os.PathLike[str]] = (),
+    preserve_loaded_modules: bool = False,
+):
+    if project_dir is None:
+        yield
+        return
+    root = Path(project_dir).expanduser().resolve()
+    normalized_roots = [root]
+    seen_roots = {str(root)}
+    for raw_root in extra_import_roots:
+        candidate = Path(raw_root).expanduser().resolve()
+        candidate_key = str(candidate)
+        if candidate_key in seen_roots:
+            continue
+        seen_roots.add(candidate_key)
+        normalized_roots.append(candidate)
+    original_path = list(sys.path)
+    managed_modules = _managed_top_level_modules(root, normalized_roots[1:])
+    saved_modules = {
+        name: module
+        for name, module in sys.modules.items()
+        if any(
+            name == target or name.startswith(target + ".")
+            for target in managed_modules
+        )
+    }
+    try:
+        root_strings = {str(item) for item in normalized_roots}
+        sys.path[:] = [entry for entry in original_path if entry not in root_strings]
+        for candidate in reversed(normalized_roots):
+            sys.path.insert(0, str(candidate))
+        for name, module in saved_modules.items():
+            if not _module_belongs_to_roots(module, root_strings):
+                sys.modules.pop(name, None)
+        importlib.invalidate_caches()
+        yield
+    finally:
+        sys.path[:] = original_path
+        if preserve_loaded_modules:
+            importlib.invalidate_caches()
+        else:
+            for name in list(sys.modules):
+                if any(
+                    name == target or name.startswith(target + ".")
+                    for target in managed_modules
+                ):
+                    sys.modules.pop(name, None)
+            sys.modules.update(saved_modules)
+        importlib.invalidate_caches()
+
+
+__all__ = ["ProjectContext", "active_project_import_root", "resolve_project_context"]

pz_core/assembly/resources/__init__.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from .compiler import (
+    ResourceManifest,
+    ResourceItem,
+    ResourceSource,
+    build_resource_source,
+    compile_resource_manifest,
+    discover_resource_sources,
+)
+
+__all__ = [
+    "ResourceManifest",
+    "ResourceItem",
+    "ResourceSource",
+    "build_resource_source",
+    "compile_resource_manifest",
+    "discover_resource_sources",
+]

pz_core/assembly/resources/compiler.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib.util import find_spec
+import os
+from pathlib import Path
+from typing import Iterable
+
+from pz_core.assembly.apps import AppRegistry
+from pz_core.assembly.resources.settings import DEFAULT_RESOURCE_ITEMS, read_resource_settings
+from pz_core.assembly.settings import SettingsSnapshot
+from pz_core.core.errors import PzError
+from pz_core.core.extensions import ExtensionRegistry, ResourceContributionSpec
+from pz_core.assembly.project import ProjectContext
+from pz_core.infra.settings import ResourceItemContract
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceItem:
+    name: str
+    source_dirs: tuple[Path, ...]
+    output_dir: Path
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceSource:
+    app_id: str
+    module_path: str
+    package_root: Path
+    items: tuple[ResourceItem, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceManifest:
+    app_order: tuple[str, ...]
+    manifest_path: Path
+    output_root: Path
+    items: tuple[ResourceItem, ...]
+    staging_root: Path
+    lock_path: Path
+    sources: tuple[ResourceSource, ...]
+    resource_contributions: tuple[ResourceContributionSpec, ...] = ()
+
+
+def _resource_import_root(module_path: str, *, entrypoint: str, owner: str) -> str:
+    module_name, _, attr_name = entrypoint.partition(":")
+    if attr_name == "app" and module_name.endswith(".apps"):
+        return module_name[:-5]
+    raise PzError(
+        code="PZ_RESOURCE_APP_ENTRYPOINT_INVALID",
+        message=(
+            f"App '{owner}' entrypoint '{entrypoint}' must use '<pkg>.apps:app' "
+            "before compiling resource manifests."
+        ),
+        stage="resources",
+        owner=owner,
+        action="compile_resource_manifest",
+    )
+
+
+def _package_root(module_path: str, *, entrypoint: str, owner: str) -> Path:
+    module_name, _, attr_name = entrypoint.partition(":")
+    if attr_name != "app" or not module_name.endswith(".apps"):
+        _resource_import_root(module_path, entrypoint=entrypoint, owner=owner)
+        raise PzError(
+            code="PZ_RESOURCE_APP_ENTRYPOINT_INVALID",
+            message=(
+                f"App '{owner}' entrypoint '{entrypoint}' must use '<pkg>.apps:app' "
+                "before compiling resource manifests."
+            ),
+            stage="resources",
+            owner=owner,
+            action="compile_resource_manifest",
+        )
+    spec = find_spec(module_name)
+    if spec is None:
+        raise PzError(
+            code="PZ_RESOURCE_APP_NOT_FOUND",
+            message=f"Cannot resolve resource package for app '{module_path}'.",
+            stage="resources",
+            owner=module_path,
+            action="compile_resource_manifest",
+        )
+    if spec.origin:
+        return Path(spec.origin).resolve().parent
+    if spec.submodule_search_locations:
+        return Path(next(iter(spec.submodule_search_locations))).resolve()
+    import_root = _resource_import_root(module_path, entrypoint=entrypoint, owner=owner)
+    spec = find_spec(import_root)
+    if spec is None:
+        raise PzError(
+            code="PZ_RESOURCE_APP_NOT_FOUND",
+            message=f"Cannot resolve package root for app '{module_path}'.",
+            stage="resources",
+            owner=module_path,
+            action="compile_resource_manifest",
+        )
+    if spec.origin:
+        return Path(spec.origin).resolve().parent
+    if spec.submodule_search_locations:
+        return Path(next(iter(spec.submodule_search_locations))).resolve()
+    raise PzError(
+        code="PZ_RESOURCE_APP_NOT_FOUND",
+        message=f"Cannot resolve package root for app '{module_path}'.",
+        stage="resources",
+        owner=module_path,
+        action="compile_resource_manifest",
+    )
+
+
+def _optional_dir(package_root: Path, name: str) -> Path | None:
+    path = package_root / name
+    if path.is_dir():
+        return path
+    if path.exists():
+        raise PzError(
+            code="PZ_RESOURCE_DIR_INVALID",
+            message=f"Resource path '{path.name}' for package '{package_root.name}' must be a directory.",
+            stage="resources",
+            owner=str(package_root),
+            action="compile_resource_manifest",
+        )
+    return None
+
+
+_IGNORED_RESOURCE_PARTS = {"tests", "test", "docs", "__pycache__"}
+
+def _default_resource_items() -> tuple[ResourceItemContract, ...]:
+    return tuple(
+        ResourceItemContract(
+            name=item["name"],
+            output_dir=Path("."),
+        )
+        for item in DEFAULT_RESOURCE_ITEMS
+    )
+
+
+def _discover_resource_dirs(
+    package_root: Path,
+    *,
+    resource_items: tuple[ResourceItemContract, ...],
+) -> dict[str, tuple[Path, ...]]:
+    resource_item_names = tuple(item.name for item in resource_items)
+    collected: dict[str, list[Path]] = {name: [] for name in resource_item_names}
+    root_resolved: dict[str, Path | None] = {}
+
+    for name in resource_item_names:
+        root_dir = _optional_dir(package_root, name)
+        if root_dir is not None:
+            resolved = root_dir.resolve()
+            collected[name].append(resolved)
+            root_resolved[name] = resolved
+        else:
+            root_resolved[name] = None
+
+    for current_root, dirnames, filenames in os.walk(package_root):
+        current_path = Path(current_root)
+        if current_path.name in resource_item_names:
+            dirnames[:] = []
+            continue
+        dirnames[:] = sorted(
+            name
+            for name in dirnames
+            if name not in _IGNORED_RESOURCE_PARTS
+        )
+        for file_name in filenames:
+            if file_name in resource_item_names:
+                raise PzError(
+                    code="PZ_RESOURCE_DIR_INVALID",
+                    message=f"Resource path '{file_name}' for package '{package_root.name}' must be a directory.",
+                    stage="resources",
+                    owner=str(package_root),
+                    action="compile_resource_manifest",
+                )
+        for dir_name in dirnames:
+            if dir_name not in resource_item_names:
+                continue
+            candidate = (current_path / dir_name).resolve()
+            if root_resolved[dir_name] is not None and candidate == root_resolved[dir_name]:
+                continue
+            collected[dir_name].append(candidate)
+
+    return {name: tuple(paths) for name, paths in collected.items()}
+
+
+def build_resource_source(
+    *,
+    app_id: str,
+    module_path: str,
+    package_root: Path,
+    resource_items: tuple[ResourceItemContract, ...],
+    output_root: Path | None = None,
+) -> ResourceSource:
+    discovered = _discover_resource_dirs(package_root, resource_items=resource_items)
+    resolved_output_root = output_root if output_root is not None else Path(".")
+    return ResourceSource(
+        app_id=app_id,
+        module_path=module_path,
+        package_root=package_root,
+        items=tuple(
+            ResourceItem(
+                name=item.name,
+                source_dirs=discovered.get(item.name, ()),
+                output_dir=resolved_output_root / item.name,
+            )
+            for item in resource_items
+        ),
+    )
+
+
+def discover_resource_sources(
+    module_paths: Iterable[str],
+    *,
+    resource_items: tuple[ResourceItemContract, ...] | None = None,
+) -> tuple[ResourceSource, ...]:
+    resolved_resource_items = resource_items or _default_resource_items()
+    sources: list[ResourceSource] = []
+    for raw_module_path in module_paths:
+        module_path = str(raw_module_path).split(":", 1)[0].strip()
+        if not module_path:
+            continue
+        try:
+            spec = find_spec(module_path)
+        except ModuleNotFoundError:
+            continue
+        if spec is None:
+            continue
+        if spec.submodule_search_locations:
+            package_root = Path(next(iter(spec.submodule_search_locations))).resolve()
+        elif spec.origin:
+            package_root = Path(spec.origin).resolve().parent
+        else:
+            continue
+        sources.append(
+            build_resource_source(
+                app_id=module_path.split(".")[-1],
+                module_path=module_path,
+                package_root=package_root,
+                resource_items=resolved_resource_items,
+                output_root=Path("."),
+            )
+        )
+    return tuple(sources)
+
+def _compile_resource_contribution_specs(
+    extension_registry: ExtensionRegistry | None,
+) -> tuple[ResourceContributionSpec, ...]:
+    if extension_registry is None:
+        return ()
+    return tuple(
+        item
+        for item in extension_registry.by_kind("resource.contribution")
+        if isinstance(item, ResourceContributionSpec)
+    )
+
+
+def compile_resource_manifest(
+    project: ProjectContext,
+    settings: SettingsSnapshot,
+    app_registry: AppRegistry,
+    extension_registry: ExtensionRegistry | None = None,
+) -> ResourceManifest:
+    resource_settings = read_resource_settings(
+        settings,
+        project,
+        stage="resources",
+        owner="resources",
+        action="compile_resource_manifest",
+    )
+    output_root = resource_settings.output_dir
+    manifest_path = resource_settings.manifest_path
+    staging_root = resource_settings.staging_dir
+    lock_path = resource_settings.lock_path
+    items = tuple(
+        ResourceItem(
+            name=item.name,
+            source_dirs=(),
+            output_dir=item.output_dir,
+        )
+        for item in resource_settings.items
+    )
+
+    sources: list[ResourceSource] = []
+    for app in app_registry.apps:
+        package_root = _package_root(
+            app.module_path,
+            entrypoint=app.entrypoint,
+            owner=app.app_id,
+        )
+        sources.append(
+            build_resource_source(
+                app_id=app.app_id,
+                module_path=app.module_path,
+                package_root=package_root,
+                resource_items=resource_settings.items,
+                output_root=output_root,
+            )
+        )
+
+    resource_contributions = _compile_resource_contribution_specs(extension_registry)
+    return ResourceManifest(
+        app_order=tuple(app.app_id for app in app_registry.apps),
+        manifest_path=manifest_path,
+        output_root=output_root,
+        items=items,
+        staging_root=staging_root,
+        lock_path=lock_path,
+        sources=tuple(sources),
+        resource_contributions=resource_contributions,
+    )

pz_core/assembly/resources/settings.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pz_core.assembly.project import ProjectContext
+from pz_core.assembly.settings import SettingsSnapshot
+from pz_core.core.errors import PzError
+from pz_core.infra.settings import ResourceItemContract, ResourceSettings
+
+DEFAULT_RESOURCE_ITEMS = (
+    {"name": "templates"},
+    {"name": "static"},
+    {"name": "locales"},
+    {"name": "pages"},
+    {"name": "template_config"},
+    {"name": "migrations"},
+)
+
+
+def _resource_environment(settings: SettingsSnapshot) -> str:
+    raw = settings.get("project", "pz_env", default="develop")
+    value = str(raw or "").strip().lower()
+    return value or "develop"
+
+
+def read_resource_settings(
+    settings: SettingsSnapshot,
+    project: ProjectContext,
+    *,
+    stage: str,
+    owner: str,
+    action: str,
+) -> ResourceSettings:
+    raw_resources = settings.get("resources", default={})
+    if not isinstance(raw_resources, dict):
+        raise PzError(
+            code="PZ_RESOURCE_SETTINGS_INVALID",
+            message="resources must be declared as a table.",
+            stage=stage,
+            owner=owner,
+            action=action,
+        )
+
+    raw_items = raw_resources.get("items", DEFAULT_RESOURCE_ITEMS)
+    if not isinstance(raw_items, (list, tuple)):
+        raise PzError(
+            code="PZ_RESOURCE_SETTINGS_INVALID",
+            message="resources.items must be declared as an array of objects with non-empty name fields.",
+            stage=stage,
+            owner=owner,
+            action=action,
+        )
+    item_names: list[str] = []
+    parsed_items: list[ResourceItemContract] = []
+    for item in raw_items:
+        if not isinstance(item, dict):
+            raise PzError(
+                code="PZ_RESOURCE_SETTINGS_INVALID",
+                message="resources.items must be declared as an array of objects with non-empty name fields.",
+                stage=stage,
+                owner=owner,
+                action=action,
+            )
+        raw_name = item.get("name")
+        if not isinstance(raw_name, str) or not raw_name.strip():
+            raise PzError(
+                code="PZ_RESOURCE_SETTINGS_INVALID",
+                message="resources.items must be declared as an array of objects with non-empty name fields.",
+                stage=stage,
+                owner=owner,
+                action=action,
+            )
+        normalized = raw_name.strip()
+        if normalized in item_names:
+            continue
+        item_names.append(normalized)
+        parsed_items.append(
+            ResourceItemContract(
+                name=normalized,
+                output_dir=Path("."),
+            )
+        )
+    if not parsed_items:
+        raise PzError(
+            code="PZ_RESOURCE_SETTINGS_INVALID",
+            message="resources.items must declare at least one resource item.",
+            stage=stage,
+            owner=owner,
+            action=action,
+        )
+
+    output_root_name = str(raw_resources.get("output_root", "resources") or "resources").strip()
+    manifest_name = str(raw_resources.get("manifest_name", "manifest.json") or "manifest.json").strip()
+    staging_name = str(raw_resources.get("staging_dir", "staging") or "staging").strip()
+    lock_name = str(raw_resources.get("lock_name", "resources.lock") or "resources.lock").strip()
+    if not output_root_name or not manifest_name or not staging_name or not lock_name:
+        raise PzError(
+            code="PZ_RESOURCE_SETTINGS_INVALID",
+            message=(
+                "resources.output_root, resources.manifest_name, "
+                "resources.staging_dir, and resources.lock_name must be non-empty strings."
+            ),
+            stage=stage,
+            owner=owner,
+            action=action,
+        )
+    env_name = _resource_environment(settings)
+    output_dir = project.cache_dir / env_name / output_root_name
+    return ResourceSettings(
+        items=tuple(
+            ResourceItemContract(
+                name=item.name,
+                output_dir=output_dir / item.name,
+            )
+            for item in parsed_items
+        ),
+        output_dir=output_dir,
+        lock_path=project.runtime_dir / env_name / "locks" / lock_name,
+        manifest_path=output_dir / manifest_name,
+        staging_dir=output_dir / staging_name,
+        manifest_name=manifest_name,
+        lock_name=lock_name,
+    )
+
+
+__all__ = [
+    "DEFAULT_RESOURCE_ITEMS",
+    "read_resource_settings",
+]

pz_core/assembly/routes/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from pz_core.core.routing import RouteDecl, RouteManifest
+
+from .compiler import compile_route_manifest
+
+__all__ = ["RouteDecl", "RouteManifest", "compile_route_manifest"]