pz-cli 5.0.0__py3-none-any.whl

pz_core/project_sources.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from functools import lru_cache
+from importlib.resources import files
+import json
+from pathlib import Path, PurePosixPath
+from types import MappingProxyType
+from typing import Literal, cast
+
+from pz_core.runtime.errors import PzError
+
+
+_SOURCES_DIR = ".sources"
+_SOURCES_ROOT = Path("apps") / _SOURCES_DIR
+_MANIFEST_PATH = _SOURCES_ROOT / "manifest.json"
+OFFICIAL_CONTRIB_SOURCE_ROOT = "pz_contrib"
+
+
+@dataclass(frozen=True, slots=True)
+class OfficialDevSourceSpec:
+    name: str
+    remote_url: str
+    workspace_identifier: str
+    default_branch: str
+    runtime_id: str | None = None
+    declared_app: str | None = None
+
+
+OFFICIAL_RUNTIME_SOURCE = OfficialDevSourceSpec(
+    name="pz",
+    remote_url="git@github.com:JiXiangTools/pyzza.git",
+    workspace_identifier="pz",
+    default_branch="develop",
+    runtime_id="pz",
+)
+OFFICIAL_SOURCE_ROOTS = (
+    OfficialDevSourceSpec(
+        name="pz_apps",
+        remote_url="git@github.com:JiXiangTools/pyzza_platform.git",
+        workspace_identifier="pz-apps-source-root",
+        default_branch="develop",
+        declared_app="pz_apps",
+    ),
+)
+OFFICIAL_TRUTH_SOURCE_REPO_NAMES = (
+    OFFICIAL_RUNTIME_SOURCE.name,
+    *(item.name for item in OFFICIAL_SOURCE_ROOTS),
+)
+
+
+@dataclass(frozen=True, slots=True)
+class OfficialSourceChild:
+    kind: Literal["project", "app"]
+    subpath: PurePosixPath
+    expected_app_id: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class OfficialSourceRoot:
+    repo_key: str
+    source: str
+    kind: Literal["directory"]
+    bootstrap: bool
+    children: Mapping[str, OfficialSourceChild]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "children", MappingProxyType(dict(self.children)))
+
+
+def _catalog_invalid(path: str, reason: str) -> PzError:
+    return PzError(
+        code="PZ_DEV_OFFICIAL_SOURCE_CATALOG_INVALID",
+        message=f"{path}: {reason}",
+        stage="dev",
+        owner="pz_core.project_sources",
+        action="load_official_source_catalog",
+    )
+
+
+def _require_catalog_object(value: object, path: str) -> dict[str, object]:
+    if not isinstance(value, dict) or not all(isinstance(key, str) for key in value):
+        raise _catalog_invalid(path, "expected an object")
+    return cast(dict[str, object], value)
+
+
+def _require_exact_fields(
+    value: object,
+    path: str,
+    expected: frozenset[str],
+) -> dict[str, object]:
+    payload = _require_catalog_object(value, path)
+    fields = set(payload)
+    if fields != expected:
+        missing = sorted(expected - fields)
+        unknown = sorted(fields - expected)
+        reason = (
+            f"missing field {missing[0]!r}"
+            if missing
+            else f"unknown field {unknown[0]!r}"
+        )
+        raise _catalog_invalid(path, reason)
+    return payload
+
+
+def _parse_catalog_subpath(value: object, path: str) -> PurePosixPath:
+    if not isinstance(value, str) or not value or value != value.strip():
+        raise _catalog_invalid(path, "expected a normalized relative POSIX path")
+    subpath = PurePosixPath(value)
+    if (
+        subpath.is_absolute()
+        or ".." in subpath.parts
+        or subpath.as_posix() != value
+    ):
+        raise _catalog_invalid(path, "expected a normalized relative POSIX path")
+    return subpath
+
+
+def _parse_official_child(key: str, value: object, path: str) -> OfficialSourceChild:
+    payload = _require_exact_fields(
+        value,
+        path,
+        frozenset({"kind", "subpath", "expected_app_id"}),
+    )
+    kind = payload["kind"]
+    if kind not in {"project", "app"}:
+        raise _catalog_invalid(f"{path}.kind", "expected 'project' or 'app'")
+    expected_app_id = payload["expected_app_id"]
+    if kind == "project":
+        if expected_app_id is not None:
+            raise _catalog_invalid(
+                f"{path}.expected_app_id",
+                "project metadata cannot expose an app id",
+            )
+    elif expected_app_id != key.replace("-", "_"):
+        raise _catalog_invalid(
+            f"{path}.expected_app_id",
+            "app metadata must match the normalized child key",
+        )
+    subpath = _parse_catalog_subpath(payload["subpath"], f"{path}.subpath")
+    if kind == "app" and subpath == PurePosixPath("."):
+        raise _catalog_invalid(
+            f"{path}.subpath",
+            "app metadata must resolve below its source root",
+        )
+    return OfficialSourceChild(
+        kind=cast(Literal["project", "app"], kind),
+        subpath=subpath,
+        expected_app_id=cast(str | None, expected_app_id),
+    )
+
+
+def _parse_official_root(
+    repo_key: str,
+    value: object,
+    path: str,
+) -> OfficialSourceRoot:
+    payload = _require_exact_fields(
+        value,
+        path,
+        frozenset({"source", "kind", "bootstrap", "children"}),
+    )
+    source = payload["source"]
+    if not isinstance(source, str) or not source.strip() or source != source.strip():
+        raise _catalog_invalid(f"{path}.source", "expected a normalized source URL")
+    if payload["kind"] != "directory":
+        raise _catalog_invalid(f"{path}.kind", "expected 'directory'")
+    bootstrap = payload["bootstrap"]
+    if type(bootstrap) is not bool:
+        raise _catalog_invalid(f"{path}.bootstrap", "expected a boolean")
+    raw_children = _require_catalog_object(payload["children"], f"{path}.children")
+    children = {
+        key: _parse_official_child(key, child, f"{path}.children.{key}")
+        for key, child in raw_children.items()
+    }
+    return OfficialSourceRoot(
+        repo_key=repo_key,
+        source=source,
+        kind="directory",
+        bootstrap=bootstrap,
+        children=children,
+    )
+
+
+@lru_cache(maxsize=1)
+def load_official_source_catalog() -> Mapping[str, OfficialSourceRoot]:
+    resource = files("pz_core.authoring").joinpath("official_sources.json")
+    try:
+        raw = json.loads(resource.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise _catalog_invalid("$", f"cannot read catalog JSON: {exc}") from exc
+    payload = _require_catalog_object(raw, "$")
+    if set(payload) != {"pz", "pz_apps"}:
+        raise _catalog_invalid("$", "expected exactly the pz and pz_apps roots")
+    catalog = {
+        key: _parse_official_root(key, value, f"$.{key}")
+        for key, value in payload.items()
+    }
+    if catalog["pz"].bootstrap is not True:
+        raise _catalog_invalid("$.pz.bootstrap", "pz must be the bootstrap root")
+    if catalog["pz_apps"].bootstrap is not False:
+        raise _catalog_invalid(
+            "$.pz_apps.bootstrap",
+            "pz_apps cannot be a bootstrap root",
+        )
+    return MappingProxyType(catalog)
+
+
+def resolve_sources_root(project_dir: Path) -> Path:
+    return project_dir / _SOURCES_ROOT
+
+
+def resolve_sources_manifest_path(project_dir: Path) -> Path:
+    return project_dir / _MANIFEST_PATH
+
+
+def resolve_sources_repo_checkout_root(project_dir: Path, repo_key: str) -> Path:
+    return resolve_sources_root(project_dir) / repo_key
+
+
+def resolve_known_sources_roots(project_dir: Path) -> tuple[Path, ...]:
+    return (resolve_sources_root(project_dir),)
+
+
+def resolve_runtime_checkout_root(runtime_package_root: Path) -> Path:
+    distribution_root = runtime_package_root.expanduser().resolve().parent
+    for candidate in (distribution_root, distribution_root.parent.resolve()):
+        if resolve_contrib_source_root(candidate).is_dir():
+            return candidate
+    return distribution_root
+
+
+def resolve_contrib_source_root(checkout_root: Path) -> Path:
+    return checkout_root.expanduser().resolve() / OFFICIAL_CONTRIB_SOURCE_ROOT
+
+
+__all__ = [
+    "OFFICIAL_CONTRIB_SOURCE_ROOT",
+    "OFFICIAL_RUNTIME_SOURCE",
+    "OFFICIAL_SOURCE_ROOTS",
+    "OFFICIAL_TRUTH_SOURCE_REPO_NAMES",
+    "OfficialDevSourceSpec",
+    "OfficialSourceChild",
+    "OfficialSourceRoot",
+    "load_official_source_catalog",
+    "resolve_contrib_source_root",
+    "resolve_known_sources_roots",
+    "resolve_runtime_checkout_root",
+    "resolve_sources_manifest_path",
+    "resolve_sources_repo_checkout_root",
+    "resolve_sources_root",
+]

pz_core/pz_launcher.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from pz_core.project_runtime_cli import (
+    PROVIDER_LOCK_ENV_NAME,
+    _build_project_runtime_env,
+    _target_virtualenv_path,
+    provider_resolution_locked,
+    resolve_cli_project_dir,
+    resolve_project_runtime_package_root,
+)
+from pz_core.runtime.environment_integrity import validate_current_environment
+from pz_core.runtime.errors import PzError
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    try:
+        validate_current_environment(os.environ)
+    except PzError as exc:
+        sys.stderr.write(f"{exc}\n")
+        return 2
+    args = list(argv or sys.argv[1:])
+    if not provider_resolution_locked():
+        if handoff_to_preferred_pz_provider(args, current_package_root=Path(__file__).resolve().parent):
+            return 0
+    return _run_current_cli(args)
+
+
+def handoff_to_preferred_pz_provider(
+    argv: Sequence[str] | None = None,
+    *,
+    current_package_root: Path,
+) -> bool:
+    project_dir = resolve_cli_project_dir(argv)
+    if project_dir is None:
+        return False
+    if _handoff_to_project_venv(argv, project_dir=project_dir, current_package_root=current_package_root):
+        return True
+    if _handoff_to_project_source(argv, project_dir=project_dir, current_package_root=current_package_root):
+        return True
+    return False
+
+
+def _run_current_cli(argv: Sequence[str]) -> int:
+    try:
+        from pz_core.cli import main as cli_main
+    except Exception:
+        if not provider_resolution_locked() and _handoff_to_uv_tool(argv):
+            return 0
+        raise
+    return cli_main(list(argv))
+
+
+def _handoff_to_project_venv(
+    argv: Sequence[str] | None,
+    *,
+    project_dir: Path,
+    current_package_root: Path,
+) -> bool:
+    venv_root = project_dir / ".venv"
+    if not venv_root.is_dir():
+        return False
+    venv_python = _resolve_venv_python(venv_root)
+    if venv_python is None:
+        return False
+    current_in_project_venv = _same_python_executable(str(venv_python), sys.executable) and any(
+        _path_is_relative_to(current_package_root, site_packages_root)
+        for site_packages_root in _site_packages_roots(venv_root)
+    )
+    if current_in_project_venv:
+        return False
+    env = dict(os.environ)
+    env[PROVIDER_LOCK_ENV_NAME] = "project-venv"
+    env["PZ_PROJECT_DIR"] = str(project_dir.resolve())
+    pz_command = _resolve_venv_pz_command(venv_root)
+    if pz_command is not None:
+        os.execvpe(str(pz_command), [str(pz_command), *list(argv or sys.argv[1:])], env)
+        return True
+    if not _venv_contains_pz(venv_root):
+        return False
+    os.execvpe(
+        str(venv_python),
+        [str(venv_python), "-m", "pz_core", *list(argv or sys.argv[1:])],
+        env,
+    )
+    return True
+
+
+def _handoff_to_project_source(
+    argv: Sequence[str] | None,
+    *,
+    project_dir: Path,
+    current_package_root: Path,
+) -> bool:
+    runtime_package_root = resolve_project_runtime_package_root(project_dir)
+    if runtime_package_root is None:
+        return False
+    project_python = _resolve_source_python(runtime_package_root)
+    if runtime_package_root.resolve() == current_package_root.expanduser().resolve() and _same_python_executable(
+        project_python,
+        sys.executable,
+    ):
+        return False
+    env = _build_project_runtime_env(project_dir, runtime_package_root)
+    env[PROVIDER_LOCK_ENV_NAME] = "project-source"
+    os.execvpe(
+        project_python,
+        [project_python, "-m", "pz_core", *list(argv or sys.argv[1:])],
+        env,
+    )
+    return True
+
+
+def _handoff_to_uv_tool(argv: Sequence[str]) -> bool:
+    uv_binary = shutil.which("uv")
+    if not uv_binary:
+        return False
+    env = dict(os.environ)
+    env[PROVIDER_LOCK_ENV_NAME] = "uv-tool"
+    os.execvpe(
+        uv_binary,
+        [uv_binary, "tool", "run", "--from", "pz-cli", "pz", *list(argv)],
+        env,
+    )
+    return True
+
+
+def _resolve_venv_pz_command(venv_root: Path) -> Path | None:
+    candidates = (
+        venv_root / "bin" / "pz",
+        venv_root / "Scripts" / "pz.exe",
+        venv_root / "Scripts" / "pz",
+    )
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate.absolute()
+    return None
+
+
+def _resolve_venv_python(venv_root: Path) -> Path | None:
+    candidates = (
+        venv_root / "bin" / "python",
+        venv_root / "Scripts" / "python.exe",
+    )
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate.absolute()
+    return None
+
+
+def _site_packages_roots(venv_root: Path) -> tuple[Path, ...]:
+    roots: list[Path] = []
+    lib_root = venv_root / "lib"
+    if lib_root.is_dir():
+        for candidate in sorted(lib_root.glob("python*/site-packages")):
+            if candidate.is_dir():
+                roots.append(candidate.resolve())
+    windows_root = venv_root / "Lib" / "site-packages"
+    if windows_root.is_dir():
+        roots.append(windows_root.resolve())
+    return tuple(roots)
+
+
+def _venv_contains_pz(venv_root: Path) -> bool:
+    for site_packages_root in _site_packages_roots(venv_root):
+        if (site_packages_root / "pz" / "__init__.py").is_file():
+            return True
+        if any(site_packages_root.glob("pz-*.dist-info")):
+            return True
+        if any(site_packages_root.glob("__editable__.pz*.pth")):
+            return True
+        if any(site_packages_root.glob("__editable___pz*.py")):
+            return True
+    return False
+
+
+def _path_is_relative_to(path: Path, parent: Path) -> bool:
+    try:
+        path.expanduser().resolve().relative_to(parent.expanduser().resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def _resolve_source_python(runtime_package_root: Path) -> str:
+    for source_root in (runtime_package_root.parent.absolute(), runtime_package_root.absolute()):
+        source_venv = _target_virtualenv_path(source_root)
+        source_python = source_venv / "bin" / "python"
+        if source_python.is_file():
+            return str(source_python.absolute())
+        source_python_windows = source_venv / "Scripts" / "python.exe"
+        if source_python_windows.is_file():
+            return str(source_python_windows.absolute())
+    return sys.executable
+
+
+def _same_python_executable(left: str, right: str) -> bool:
+    try:
+        return os.path.abspath(os.path.expanduser(left)) == os.path.abspath(os.path.expanduser(right))
+    except Exception:
+        return left == right
+
+
+__all__ = ["handoff_to_preferred_pz_provider", "main"]

pz_core/root_cli.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
+from importlib.metadata import entry_points
+
+
+ROOT_CLI_PROVIDER_GROUP = "pz.root_cli"
+CommandPath = tuple[str, ...]
+RootCommandCallable = Callable[[Sequence[str]], int]
+
+
+@dataclass(frozen=True)
+class RootCommandHandler:
+    command_path: CommandPath
+    handler: RootCommandCallable
+
+
+def normalize_command_path(parts: Sequence[str]) -> CommandPath:
+    normalized = tuple(str(part).strip().lower() for part in parts if str(part).strip())
+    if not normalized:
+        raise ValueError("root CLI command path must not be empty")
+    return normalized
+
+
+def coerce_root_command_handlers(payload: object) -> tuple[RootCommandHandler, ...]:
+    if isinstance(payload, RootCommandHandler):
+        handlers = (payload,)
+    elif isinstance(payload, Iterable) and not isinstance(payload, (str, bytes)):
+        handlers = tuple(payload)
+    else:
+        raise TypeError("root CLI provider must return RootCommandHandler or iterable[RootCommandHandler]")
+    if not handlers:
+        raise ValueError("root CLI provider returned no handlers")
+    normalized_handlers: list[RootCommandHandler] = []
+    for item in handlers:
+        if not isinstance(item, RootCommandHandler):
+            raise TypeError("root CLI provider returned a non-RootCommandHandler item")
+        normalized_handlers.append(
+            RootCommandHandler(command_path=normalize_command_path(item.command_path), handler=item.handler)
+        )
+    return tuple(normalized_handlers)
+
+
+def discover_root_command_handlers() -> dict[CommandPath, RootCommandHandler]:
+    discovered: dict[CommandPath, RootCommandHandler] = {}
+    for registered in entry_points(group=ROOT_CLI_PROVIDER_GROUP):
+        provider = registered.load()
+        handlers = coerce_root_command_handlers(provider())
+        for handler in handlers:
+            existing = discovered.get(handler.command_path)
+            if existing is not None:
+                command_text = " ".join(handler.command_path)
+                raise RuntimeError(
+                    f"Duplicate root CLI provider for `{command_text}`: "
+                    f"`{registered.value}` conflicts with an already-registered provider."
+                )
+            discovered[handler.command_path] = handler
+    return discovered
+
+
+__all__ = [
+    "CommandPath",
+    "ROOT_CLI_PROVIDER_GROUP",
+    "RootCommandCallable",
+    "RootCommandHandler",
+    "coerce_root_command_handlers",
+    "discover_root_command_handlers",
+    "normalize_command_path",
+]