pz-cli 5.0.0__py3-none-any.whl

pz_core/assembly/apps/providers.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pz_core.assembly.apps import AppRegistry, load_app_object_from_decl
+from pz_core.assembly.project import active_project_import_root
+from pz_core.assembly.settings import SettingsSnapshot
+from pz_core.core.errors import PzError
+from pz_core.runtime.registries.providers import ProviderDecl
+
+
+def _read_required_string(
+    payload: dict[str, Any],
+    *,
+    key: str,
+    default: str | None = None,
+    code: str,
+    message: str,
+    owner: str,
+) -> str:
+    raw = payload.get(key)
+    if raw is None:
+        raw = default
+    if not isinstance(raw, str) or not raw.strip():
+        raise PzError(
+            code=code,
+            message=message,
+            stage="providers",
+            owner=owner,
+            action="compile_provider_declarations",
+        )
+    return raw.strip()
+
+
+def _read_optional_string(
+    payload: dict[str, Any],
+    *,
+    key: str,
+    code: str,
+    message: str,
+    owner: str,
+) -> str | None:
+    if key not in payload:
+        return None
+    raw = payload.get(key)
+    if not isinstance(raw, str) or not raw.strip():
+        raise PzError(
+            code=code,
+            message=message,
+            stage="providers",
+            owner=owner,
+            action="compile_provider_declarations",
+        )
+    return raw.strip()
+
+
+def _normalize_decl(payload: Any, *, owner_hint: str) -> ProviderDecl:
+    if not isinstance(payload, dict):
+        raise PzError(
+            code="PZ_PROVIDER_DECL_INVALID",
+            message=f"Provider declaration from '{owner_hint}' must be a table.",
+            stage="providers",
+            owner=owner_hint,
+            action="compile_provider_declarations",
+        )
+    binding_id = _read_required_string(
+        payload,
+        key="id",
+        code="PZ_PROVIDER_ID_INVALID",
+        message=f"Provider declaration from '{owner_hint}' must declare id as a non-empty string.",
+        owner=owner_hint,
+    )
+    capability = _read_required_string(
+        payload,
+        key="capability",
+        code="PZ_PROVIDER_CAPABILITY_INVALID",
+        message=f"Provider '{binding_id}' must declare capability as a non-empty string.",
+        owner=binding_id,
+    )
+    owner = _read_required_string(
+        payload,
+        key="owner",
+        default=owner_hint,
+        code="PZ_PROVIDER_OWNER_INVALID",
+        message=f"Provider '{binding_id}' must declare owner as a non-empty string.",
+        owner=binding_id,
+    )
+    scope = _read_required_string(
+        payload,
+        key="scope",
+        default="runtime",
+        code="PZ_PROVIDER_SCOPE_INVALID",
+        message=f"Provider '{binding_id}' scope must be 'runtime'.",
+        owner=binding_id,
+    )
+    provider_path = _read_optional_string(
+        payload,
+        key="provider_path",
+        code="PZ_PROVIDER_PATH_INVALID",
+        message=f"Provider '{binding_id}' provider_path must be a non-empty string import path when declared.",
+        owner=binding_id,
+    )
+    if scope not in {"runtime"}:
+        raise PzError(
+            code="PZ_PROVIDER_SCOPE_INVALID",
+            message=f"Provider '{binding_id}' scope must be 'runtime'.",
+            stage="providers",
+            owner=binding_id,
+            action="compile_provider_declarations",
+        )
+    return ProviderDecl(
+        binding_id=binding_id,
+        capability=capability,
+        owner=owner,
+        scope=scope,
+        provider_path=provider_path,
+    )
+
+
+def _read_project_providers(settings: SettingsSnapshot) -> tuple[ProviderDecl, ...]:
+    raw = settings.get("providers", default=())
+    if raw in (None, (), []):
+        return ()
+    if not isinstance(raw, list):
+        raise PzError(
+            code="PZ_PROVIDERS_INVALID",
+            message="providers must be an array of tables.",
+            stage="providers",
+            owner="providers",
+            action="compile_provider_declarations",
+        )
+    return tuple(_normalize_decl(item, owner_hint="project.providers") for item in raw)
+
+
+def _load_app_providers(app_registry: AppRegistry) -> tuple[ProviderDecl, ...]:
+    declarations: list[ProviderDecl] = []
+    for app in app_registry.apps:
+        app_obj = load_app_object_from_decl(app)
+        providers_factory = getattr(app_obj, "providers", None)
+        if providers_factory is None:
+            continue
+        if not callable(providers_factory):
+            raise PzError(
+                code="PZ_APP_PROVIDERS_INVALID",
+                message=f"App '{app.app_id}' exposes non-callable providers().",
+                stage="providers",
+                owner=app.app_id,
+                action="compile_provider_declarations",
+            )
+        declared = providers_factory()
+        if declared in (None, (), []):
+            continue
+        if not isinstance(declared, (list, tuple)):
+            raise PzError(
+                code="PZ_APP_PROVIDERS_INVALID",
+                message=f"App '{app.app_id}' providers() must return a list or tuple.",
+                stage="providers",
+                owner=app.app_id,
+                action="compile_provider_declarations",
+            )
+        for item in declared:
+            declarations.append(_normalize_decl(item, owner_hint=app.app_id))
+    return tuple(declarations)
+
+
+def compile_provider_declarations(
+    settings: SettingsSnapshot,
+    app_registry: AppRegistry,
+) -> tuple[ProviderDecl, ...]:
+    project_dir = getattr(settings, "project_dir", None)
+    import_roots = getattr(settings, "import_roots", ())
+    with active_project_import_root(
+        project_dir,
+        extra_import_roots=import_roots,
+    ):
+        declarations = _read_project_providers(settings) + _load_app_providers(app_registry)
+    seen: set[str] = set()
+    for declaration in declarations:
+        if declaration.binding_id in seen:
+            raise PzError(
+                code="PZ_PROVIDER_DUPLICATE_ID",
+                message=f"Duplicate provider binding id '{declaration.binding_id}'.",
+                stage="providers",
+                owner=declaration.binding_id,
+                action="compile_provider_declarations",
+            )
+        seen.add(declaration.binding_id)
+    return declarations

pz_core/assembly/cli/__init__.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from .compiler import AppCliCommand, CliManifest, compile_cli_manifest
+
+__all__ = [
+    "AppCliCommand",
+    "CliManifest",
+    "compile_cli_manifest",
+]

pz_core/assembly/cli/compiler.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+
+from pz_core.assembly.apps import AppRegistry
+from pz_core.assembly.resources import ResourceManifest
+from pz_core.core.errors import PzError
+from pz_core.core.extensions import CliToolSpec
+
+
+@dataclass(frozen=True, slots=True)
+class AppCliCommand:
+    app_id: str
+    tool_name: str
+    module_path: str
+    import_path: str
+    spec: CliToolSpec
+
+    @property
+    def summary(self) -> str:
+        return self.spec.summary
+
+
+@dataclass(frozen=True, slots=True)
+class CliManifest:
+    commands: tuple[AppCliCommand, ...]
+
+
+def _app_cli_import_root(*, entrypoint: str, owner: str) -> str:
+    module_name, _, attr_name = entrypoint.partition(":")
+    if attr_name != "app" or not module_name.endswith(".apps"):
+        raise PzError(
+            code="PZ_APP_CLI_IMPORT_ROOT_INVALID",
+            message=(
+                f"App '{owner}' entrypoint '{entrypoint}' must use "
+                "'<pkg>.apps:app' before CLI discovery."
+            ),
+            stage="cli",
+            owner=owner,
+            action="compile_cli_manifest",
+        )
+    return module_name[:-5]
+
+
+def _cli_dir(package_root: Path) -> Path | None:
+    cli_dir = package_root / "cli"
+    if cli_dir.is_dir():
+        return cli_dir
+    if cli_dir.exists():
+        raise PzError(
+            code="PZ_APP_CLI_DIR_INVALID",
+            message=f"App CLI path '{cli_dir.name}' for package '{package_root.name}' must be a directory.",
+            stage="cli",
+            owner=str(package_root),
+            action="compile_cli_manifest",
+        )
+    return None
+
+
+def _load_module(import_path: str) -> ModuleType:
+    return __import__(import_path, fromlist=["tool"])
+
+
+def _load_cli_tool_spec(module: ModuleType, *, app_id: str, tool_name: str) -> CliToolSpec:
+    raw_tool = getattr(module, "tool", None)
+    if raw_tool is None:
+        raise PzError(
+            code="PZ_APP_CLI_TOOL_MISSING",
+            message=(
+                f"App CLI module '{module.__name__}' must expose a formal "
+                "CliToolSpec named 'tool'."
+            ),
+            stage="cli",
+            owner=app_id,
+            action="compile_cli_manifest",
+        )
+    if not isinstance(raw_tool, CliToolSpec):
+        raise PzError(
+            code="PZ_APP_CLI_TOOL_INVALID",
+            message=f"App CLI module '{module.__name__}' exposes non-CliToolSpec 'tool'.",
+            stage="cli",
+            owner=app_id,
+            action="compile_cli_manifest",
+        )
+    if raw_tool.kind != "cli.tool":
+        raise PzError(
+            code="PZ_APP_CLI_TOOL_KIND_INVALID",
+            message=f"App CLI tool '{raw_tool.id}' must declare kind='cli.tool'.",
+            stage="cli",
+            owner=app_id,
+            action="compile_cli_manifest",
+        )
+    if raw_tool.owner_app != app_id:
+        raise PzError(
+            code="PZ_APP_CLI_TOOL_OWNER_INVALID",
+            message=f"App CLI tool '{raw_tool.id}' owner_app must match '{app_id}'.",
+            stage="cli",
+            owner=app_id,
+            action="compile_cli_manifest",
+        )
+    if raw_tool.command != (tool_name,):
+        raise PzError(
+            code="PZ_APP_CLI_TOOL_COMMAND_INVALID",
+            message=f"App CLI tool '{raw_tool.id}' command must be ('{tool_name}',).",
+            stage="cli",
+            owner=app_id,
+            action="compile_cli_manifest",
+        )
+    tool_obj = raw_tool.tool
+    if not callable(getattr(tool_obj, "configure", None)) or not callable(getattr(tool_obj, "run", None)):
+        raise PzError(
+            code="PZ_APP_CLI_TOOL_OBJECT_INVALID",
+            message=f"App CLI tool '{raw_tool.id}' must expose configure(parser) and run(ctx).",
+            stage="cli",
+            owner=app_id,
+            action="compile_cli_manifest",
+        )
+    return raw_tool
+
+
+def compile_cli_manifest(app_registry: AppRegistry, resource_manifest: ResourceManifest) -> CliManifest:
+    commands: list[AppCliCommand] = []
+    sources_by_app_id = {source.app_id: source for source in resource_manifest.sources}
+    for app in app_registry.apps:
+        import_root = _app_cli_import_root(entrypoint=app.entrypoint, owner=app.app_id)
+        source = sources_by_app_id.get(app.app_id)
+        if source is None:
+            raise PzError(
+                code="PZ_APP_CLI_RESOURCE_SOURCE_MISSING",
+                message=f"App '{app.app_id}' is missing a resource source entry for CLI discovery.",
+                stage="cli",
+                owner=app.app_id,
+                action="compile_cli_manifest",
+            )
+        cli_dir = _cli_dir(source.package_root)
+        if cli_dir is None:
+            continue
+        for path in sorted(cli_dir.glob("*.py")):
+            if path.name == "__init__.py" or path.name.startswith("_"):
+                continue
+            if not path.stem.isidentifier():
+                raise PzError(
+                    code="PZ_APP_CLI_TOOL_INVALID",
+                    message=(
+                        f"App '{app.app_id}' CLI module '{path.name}' must use a valid Python "
+                        "identifier filename."
+                    ),
+                    stage="cli",
+                    owner=app.app_id,
+                    action="compile_cli_manifest",
+                )
+            import_path = f"{import_root}.cli.{path.stem}"
+            module = _load_module(import_path)
+            spec = _load_cli_tool_spec(module, app_id=app.app_id, tool_name=path.stem)
+            commands.append(
+                AppCliCommand(
+                    app_id=app.app_id,
+                    tool_name=path.stem,
+                    module_path=app.module_path,
+                    import_path=import_path,
+                    spec=spec,
+                )
+            )
+    return CliManifest(commands=tuple(commands))

pz_core/assembly/diagnostics/__init__.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from .checks import (
+    CheckItem,
+    CheckReport,
+    build_check_report,
+    build_dev_source_check_items,
+    build_source_preflight_report,
+    extend_check_report,
+    has_blocking_dev_source_failures,
+)
+
+__all__ = [
+    "CheckItem",
+    "CheckReport",
+    "build_check_report",
+    "build_dev_source_check_items",
+    "build_source_preflight_report",
+    "extend_check_report",
+    "has_blocking_dev_source_failures",
+]

pz_core/assembly/diagnostics/checks.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+from typing import Any
+
+from pz_core.runtime.plan import RuntimePlan
+from pz_core.runtime.registries import CapabilityStatus
+
+if TYPE_CHECKING:
+    from pz_core.authoring.dev_git import DevGitService
+
+
+@dataclass(frozen=True, slots=True)
+class CheckItem:
+    severity: str
+    code: str
+    owner: str
+    scope: str
+    message: str
+    ok: bool
+    expected: str | None = None
+    actual: str | None = None
+    repair_command: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "severity": self.severity,
+            "code": self.code,
+            "owner": self.owner,
+            "scope": self.scope,
+            "message": self.message,
+            "ok": self.ok,
+            "expected": self.expected,
+            "actual": self.actual,
+            "repair_command": self.repair_command,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class CheckReport:
+    status: str
+    code: str
+    stage: str
+    owner: str
+    action: str
+    checks: tuple[CheckItem, ...]
+    installed_apps: tuple[str, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "status": self.status,
+            "code": self.code,
+            "stage": self.stage,
+            "owner": self.owner,
+            "action": self.action,
+            "installed_apps": list(self.installed_apps),
+            "checks": [item.to_dict() for item in self.checks],
+        }
+
+
+def extend_check_report(
+    report: CheckReport, checks: tuple[CheckItem, ...]
+) -> CheckReport:
+    if not checks:
+        return report
+    merged_checks = tuple(report.checks) + tuple(checks)
+    has_failures = any(not item.ok for item in checks)
+    return CheckReport(
+        status="degraded" if has_failures or report.status != "ok" else report.status,
+        code="PZ_CHECK_DEGRADED"
+        if has_failures or report.status != "ok"
+        else report.code,
+        stage=report.stage,
+        owner=report.owner,
+        action=report.action,
+        checks=merged_checks,
+        installed_apps=report.installed_apps,
+    )
+
+
+def build_dev_source_check_items(
+    project_dir: str | Path,
+    *,
+    git_service: DevGitService | None = None,
+) -> tuple[CheckItem, ...]:
+    from .dev_sources import build_dev_source_check_items as build_items
+
+    return build_items(project_dir, git_service=git_service)
+
+
+def has_blocking_dev_source_failures(checks: tuple[CheckItem, ...]) -> bool:
+    from .dev_sources import has_blocking_dev_source_failures as has_failures
+
+    return has_failures(checks)
+
+
+def build_source_preflight_report(checks: tuple[CheckItem, ...]) -> CheckReport:
+    return CheckReport(
+        status="degraded",
+        code="PZ_CHECK_DEGRADED",
+        stage="check",
+        owner="runtime.check",
+        action="compile_runtime_plan",
+        checks=checks,
+        installed_apps=(),
+    )
+
+
+_ALLOWED_CAPABILITY_STATUSES: tuple[CapabilityStatus, ...] = (
+    "disabled",
+    "enabled",
+    "ready",
+    "unavailable",
+)
+
+
+def build_check_report(plan: RuntimePlan) -> CheckReport:
+    capability_statuses = plan.capability_registry.statuses()
+    unavailable_names = tuple(
+        name for name, status in capability_statuses.items() if status == "unavailable"
+    )
+    invalid_status_names = tuple(
+        name
+        for name, status in capability_statuses.items()
+        if status not in _ALLOWED_CAPABILITY_STATUSES
+    )
+
+    overall_status = "degraded" if unavailable_names else "ok"
+    overall_code = "PZ_CHECK_DEGRADED" if unavailable_names else "PZ_CHECK_OK"
+
+    checks = (
+        CheckItem(
+            severity="info",
+            code="PZ_CHECK_RUNTIME_PLAN_COMPILED",
+            owner="runtime.check",
+            scope="runtime_plan",
+            message="RuntimePlan compiled successfully.",
+            ok=True,
+        ),
+        CheckItem(
+            severity="info",
+            code="PZ_CHECK_INSTALLED_APPS_EMPTY_DEFAULT",
+            owner="runtime.check",
+            scope="settings",
+            message="installed_apps defaults to empty unless explicitly configured.",
+            ok=isinstance(plan.settings.installed_apps, tuple),
+        ),
+        CheckItem(
+            severity="info",
+            code="PZ_CHECK_CAPABILITY_REGISTRY_PRESENT",
+            owner="runtime.check",
+            scope="capabilities",
+            message="CapabilityRegistry is attached to RuntimePlan.",
+            ok=bool(plan.capability_registry.capabilities),
+        ),
+        CheckItem(
+            severity="info",
+            code="PZ_CHECK_CAPABILITY_STATUS_SEMANTICS",
+            owner="runtime.check",
+            scope="capabilities",
+            message="Capability status semantics use disabled/enabled/ready/unavailable.",
+            ok=not invalid_status_names,
+        ),
+        CheckItem(
+            severity="info",
+            code="PZ_CHECK_APP_REGISTRY_UNIQUE",
+            owner="runtime.check",
+            scope="apps",
+            message="AppRegistry keeps a unique app_id mapping.",
+            ok=len(plan.app_registry.apps) == len(plan.app_registry.by_id()),
+        ),
+        CheckItem(
+            severity="info",
+            code="PZ_CHECK_APP_INIT_EXECUTED",
+            owner="runtime.check",
+            scope="apps",
+            message="App init hooks completed during declared -> compiled.",
+            ok=plan.app_registry.initialized_app_ids
+            == tuple(app.app_id for app in plan.app_registry.apps),
+        ),
+        CheckItem(
+            severity="info",
+            code="PZ_CHECK_EVENT_REGISTRY_PRESENT",
+            owner="runtime.check",
+            scope="events",
+            message="EventRegistry was compiled before execution.",
+            ok=isinstance(plan.event_registry.events, tuple)
+            and isinstance(plan.event_registry.handlers, tuple),
+        ),
+        CheckItem(
+            severity="info",
+            code="PZ_CHECK_EXTENSION_REGISTRY_PRESENT",
+            owner="runtime.check",
+            scope="extensions",
+            message="ExtensionRegistry was compiled before execution.",
+            ok=isinstance(plan.extension_registry.extensions, tuple),
+        ),
+        CheckItem(
+            severity="info",
+            code="PZ_CHECK_PROVIDER_DECLARATIONS_PRESENT",
+            owner="runtime.check",
+            scope="providers",
+            message="Provider declarations were compiled before execution.",
+            ok=isinstance(plan.provider_declarations, tuple),
+        ),
+        CheckItem(
+            severity="info",
+            code="PZ_CHECK_RESOURCE_MANIFEST_LOCATION",
+            owner="runtime.check",
+            scope="resources",
+            message="ResourceManifest outputs stay under ProjectContext cache/runtime directories.",
+            ok=plan.resource_manifest.output_root == plan.infra.resources.output_dir
+            and plan.resource_manifest.lock_path == plan.infra.resources.lock_path
+            and plan.resource_manifest.manifest_path
+            == plan.infra.resources.manifest_path
+            and plan.resource_manifest.staging_root == plan.infra.resources.staging_dir,
+        ),
+        CheckItem(
+            severity="info",
+            code="PZ_CHECK_ROUTE_MANIFEST_PRESENT",
+            owner="runtime.check",
+            scope="routes",
+            message="RouteManifest was compiled before execution.",
+            ok=isinstance(plan.route_manifest.routes, tuple),
+        ),
+        CheckItem(
+            severity="info",
+            code="PZ_CHECK_MIDDLEWARE_MANIFEST_PRESENT",
+            owner="runtime.check",
+            scope="middlewares",
+            message="MiddlewareManifest was compiled before execution.",
+            ok=isinstance(plan.middleware_manifest.middlewares, tuple),
+        ),
+        CheckItem(
+            severity="warning" if unavailable_names else "info",
+            code="PZ_CHECK_CAPABILITY_AVAILABILITY",
+            owner="runtime.check",
+            scope="capabilities",
+            message=(
+                "Unavailable capabilities: " + ", ".join(unavailable_names)
+                if unavailable_names
+                else "No unavailable capabilities detected in current RuntimePlan."
+            ),
+            ok=not unavailable_names,
+        ),
+    )
+    return CheckReport(
+        status=overall_status,
+        code=overall_code,
+        stage="check",
+        owner="runtime.check",
+        action="compile_runtime_plan",
+        checks=checks,
+        installed_apps=plan.settings.installed_apps,
+    )