pz-cli 5.0.0__py3-none-any.whl

pz_core/project_root_commands.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+import os
+import re
+import shlex
+import subprocess
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from pz_core.authoring.project_defaults import load_project_default_jsonc_payload
+from pz_core.project_runtime_cli import resolve_cli_project_dir
+from pz_core.root_cli import CommandPath, RootCommandHandler
+from pz_core.utils.project_jsonc import PROJECT_JSONC_NAME, load_jsonc_file
+
+
+_OWNER = "pz_core.project_root_commands"
+_COMMAND_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9:_-]*$")
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectRootCommandBinding:
+    name: str
+    source_kind: str
+    target: str
+    description: str | None
+    handler: RootCommandHandler
+
+
+@dataclass(frozen=True, slots=True)
+class ConfiguredProjectCommand:
+    name: str
+    description: str | None
+    argv: tuple[str, ...] | None
+    shell_command: str | None
+
+
+def discover_project_root_command_bindings(
+    *,
+    reserved_paths: Sequence[CommandPath] = (),
+    project_dir: Path | None = None,
+) -> tuple[ProjectRootCommandBinding, ...]:
+    resolved_project_dir = project_dir if project_dir is not None else resolve_cli_project_dir()
+    if resolved_project_dir is None:
+        return ()
+    project_dir = resolved_project_dir.resolve()
+    reserved_tokens = {path[0] for path in reserved_paths if path}
+
+    bindings: list[ProjectRootCommandBinding] = []
+    for command in _discover_configured_project_commands(project_dir):
+        if command.name in reserved_tokens:
+            continue
+        bindings.append(
+            ProjectRootCommandBinding(
+                name=command.name,
+                source_kind="project_command",
+                target=command.shell_command or shlex.join(command.argv or ()),
+                description=command.description,
+                handler=RootCommandHandler(
+                    command_path=(command.name,),
+                    handler=lambda argv, command=command, project_dir=project_dir: _run_project_command(
+                        command,
+                        project_dir=project_dir,
+                        argv=_strip_root_project_dir_args(argv),
+                    ),
+                ),
+            )
+        )
+        reserved_tokens.add(command.name)
+
+    return tuple(bindings)
+
+
+def discover_project_root_command_handlers(
+    *,
+    reserved_paths: Sequence[CommandPath] = (),
+    project_dir: Path | None = None,
+) -> dict[CommandPath, RootCommandHandler]:
+    return {
+        binding.handler.command_path: binding.handler
+        for binding in discover_project_root_command_bindings(
+            reserved_paths=reserved_paths,
+            project_dir=project_dir,
+        )
+    }
+
+
+def render_project_root_command_help(
+    *,
+    reserved_paths: Sequence[CommandPath] = (),
+    project_dir: Path | None = None,
+) -> str:
+    bindings = discover_project_root_command_bindings(
+        reserved_paths=reserved_paths,
+        project_dir=project_dir,
+    )
+    if not bindings:
+        return ""
+    lines = ["", "Extensions:"]
+    for binding in bindings:
+        description = binding.description
+        if not description:
+            description = f"Project command -> {binding.target}"
+        lines.append(f"  {binding.name}")
+        lines.append(f"    {description}")
+    return "\n".join(lines) + "\n"
+
+
+def _discover_configured_project_commands(project_dir: Path) -> tuple[ConfiguredProjectCommand, ...]:
+    defaults = load_project_default_jsonc_payload()
+    commands_payload = _merge_command_payloads(
+        defaults.get("commands"),
+        _read_project_config(project_dir).get("commands"),
+    )
+    commands: list[ConfiguredProjectCommand] = []
+    for raw_name, raw_spec in sorted(commands_payload.items()):
+        name = _normalize_command_name(raw_name)
+        if name is None:
+            continue
+        commands.append(_coerce_project_command(name=name, payload=raw_spec))
+    return tuple(commands)
+
+
+def _read_project_config(project_dir: Path) -> dict[str, Any]:
+    project_path = project_dir / PROJECT_JSONC_NAME
+    if not project_path.is_file():
+        return {}
+    payload = load_jsonc_file(
+        project_path,
+        code="PZ_PROJECT_CONFIG_INVALID",
+        owner=_OWNER,
+        action="load_project_root_commands",
+    )
+    if not isinstance(payload, dict):
+        return {}
+    return dict(payload)
+
+
+def _merge_command_payloads(defaults: object, project_payload: object) -> dict[str, Any]:
+    merged: dict[str, Any] = {}
+    for candidate in (defaults, project_payload):
+        if not isinstance(candidate, Mapping):
+            continue
+        for key, value in candidate.items():
+            if isinstance(value, Mapping) and isinstance(merged.get(key), dict):
+                merged[key] = _deep_merge_mappings(merged[key], value)
+            else:
+                merged[str(key)] = value
+    return merged
+
+
+def _deep_merge_mappings(base: Mapping[str, Any], incoming: Mapping[str, Any]) -> dict[str, Any]:
+    merged = dict(base)
+    for key, value in incoming.items():
+        existing = merged.get(key)
+        if isinstance(existing, Mapping) and isinstance(value, Mapping):
+            merged[str(key)] = _deep_merge_mappings(existing, value)
+            continue
+        merged[str(key)] = value
+    return merged
+
+
+def _normalize_command_name(raw_name: object) -> str | None:
+    if not isinstance(raw_name, str):
+        return None
+    name = raw_name.strip().lower()
+    if not name or not _COMMAND_NAME_RE.match(name):
+        return None
+    return name
+
+
+def _coerce_project_command(*, name: str, payload: object) -> ConfiguredProjectCommand:
+    if isinstance(payload, str) and payload.strip():
+        return ConfiguredProjectCommand(
+            name=name,
+            description=None,
+            argv=None,
+            shell_command=payload.strip(),
+        )
+    if isinstance(payload, Sequence) and not isinstance(payload, (str, bytes)):
+        argv = tuple(str(item).strip() for item in payload if str(item).strip())
+        if argv:
+            return ConfiguredProjectCommand(
+                name=name,
+                description=None,
+                argv=argv,
+                shell_command=None,
+            )
+    if isinstance(payload, Mapping):
+        description = str(payload.get("description") or "").strip() or None
+        raw_command = payload.get("command")
+        if isinstance(raw_command, str) and raw_command.strip():
+            return ConfiguredProjectCommand(
+                name=name,
+                description=description,
+                argv=None,
+                shell_command=raw_command.strip(),
+            )
+        raw_argv = payload.get("argv")
+        if isinstance(raw_argv, Sequence) and not isinstance(raw_argv, (str, bytes)):
+            argv = tuple(str(item).strip() for item in raw_argv if str(item).strip())
+            if argv:
+                return ConfiguredProjectCommand(
+                    name=name,
+                    description=description,
+                    argv=argv,
+                    shell_command=None,
+                )
+    raise ValueError(f"Invalid project root command configuration for `{name}`")
+
+
+def _run_project_command(command: ConfiguredProjectCommand, *, project_dir: Path, argv: Sequence[str]) -> int:
+    env = _build_project_command_env(project_dir, command.name)
+    if command.shell_command is not None:
+        extra = shlex.join([str(item) for item in argv if str(item).strip()])
+        shell_command = command.shell_command if not extra else f"{command.shell_command} {extra}"
+        completed = subprocess.run(
+            shell_command,
+            cwd=str(project_dir),
+            env=env,
+            shell=True,
+            check=False,
+        )
+        return int(completed.returncode)
+    execution_argv = [*(command.argv or ()), *[str(item) for item in argv]]
+    completed = subprocess.run(
+        execution_argv,
+        cwd=str(project_dir),
+        env=env,
+        shell=False,
+        check=False,
+    )
+    return int(completed.returncode)
+
+
+def _build_project_command_env(project_dir: Path, command_name: str) -> dict[str, str]:
+    env = dict(os.environ)
+    project_dir = project_dir.resolve()
+    env["PZ_PROJECT_DIR"] = str(project_dir)
+    env["PZ_PROJECT_COMMAND"] = command_name
+    env["PZ_PROJECT_COMMAND_DEPTH"] = str(int(env.get("PZ_PROJECT_COMMAND_DEPTH", "0")) + 1)
+    path_entries = [str(path) for path in _project_bin_dirs(project_dir)]
+    existing_path = env.get("PATH", "")
+    env["PATH"] = os.pathsep.join([*path_entries, existing_path]) if existing_path else os.pathsep.join(path_entries)
+    return env
+
+
+def _project_bin_dirs(project_dir: Path) -> tuple[Path, ...]:
+    candidates = (
+        project_dir / ".venv" / "bin",
+        project_dir / ".venv" / "Scripts",
+    )
+    return tuple(path.resolve() for path in candidates if path.is_dir())
+
+
+def _strip_root_project_dir_args(argv: Sequence[str]) -> list[str]:
+    cleaned: list[str] = []
+    skip_next = False
+    for index, raw in enumerate(argv):
+        if skip_next:
+            skip_next = False
+            continue
+        item = str(raw)
+        if item in {"--project-dir", "-d"}:
+            skip_next = True
+            continue
+        if item.startswith("--project-dir="):
+            continue
+        if item.startswith("-d="):
+            continue
+        cleaned.append(item)
+    return cleaned
+
+
+__all__ = [
+    "ConfiguredProjectCommand",
+    "ProjectRootCommandBinding",
+    "discover_project_root_command_bindings",
+    "discover_project_root_command_handlers",
+    "render_project_root_command_help",
+]

pz_core/project_runtime_cli.py

@@ -0,0 +1,344 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+from pz_core.project_sources import (
+    resolve_contrib_source_root,
+    resolve_runtime_checkout_root,
+    resolve_sources_manifest_path,
+)
+from pz_core.runtime.errors import PzError
+from pz_core.utils.project_jsonc import PROJECT_JSONC_NAME
+
+PROVIDER_LOCK_ENV_NAME = "PZ_CLI_PROVIDER_LOCK"
+
+
+def resolve_cli_project_dir(argv: Sequence[str] | None = None) -> Path | None:
+    args = list(argv or sys.argv[1:])
+    explicit = _parse_project_dir_arg(args)
+    if explicit is not None:
+        return explicit
+    env_project_dir = _read_project_dir_env()
+    if env_project_dir is not None:
+        return env_project_dir
+    return _discover_project_dir_from_cwd()
+
+
+def resolve_project_runtime_package_root(project_dir: Path) -> Path | None:
+    manifest_path = resolve_sources_manifest_path(project_dir)
+    if manifest_path.is_file():
+        try:
+            payload = json.loads(manifest_path.read_text(encoding="utf-8"))
+        except Exception:
+            payload = {}
+        runtime = payload.get("runtime")
+        if isinstance(runtime, dict):
+            runtime_meta = runtime.get("pz")
+            if isinstance(runtime_meta, dict):
+                raw_path = str(runtime_meta.get("path") or "").strip()
+                if raw_path:
+                    resolved = _resolve_runtime_package_root_candidate(project_dir, raw_path)
+                    if resolved is not None:
+                        return resolved
+    return _resolve_runtime_package_root_candidate(
+        project_dir,
+        "apps/.sources/pz/pz_core/pz_core",
+    )
+
+
+def handoff_to_project_runtime(
+    argv: Sequence[str] | None = None,
+    *,
+    current_package_root: Path,
+) -> bool:
+    project_dir = resolve_cli_project_dir(argv)
+    if project_dir is None:
+        return False
+    runtime_package_root = resolve_project_runtime_package_root(project_dir)
+    if runtime_package_root is None:
+        return False
+    resolved_current = current_package_root.expanduser().resolve()
+    project_python = _resolve_project_python(project_dir, runtime_package_root=runtime_package_root)
+    if runtime_package_root.resolve() == resolved_current and _same_python_executable(project_python, sys.executable):
+        return False
+    env = _build_project_runtime_env(project_dir, runtime_package_root)
+    os.execvpe(
+        project_python,
+        [project_python, "-m", "pz_core", *list(argv or sys.argv[1:])],
+        env,
+    )
+    return True
+
+
+def run_project_runtime_json_command(
+    project_dir: Path,
+    argv: Sequence[str],
+    *,
+    action: str,
+    error_code: str,
+    error_message: str,
+) -> dict[str, object]:
+    runtime_package_root = resolve_project_runtime_package_root(project_dir)
+    if runtime_package_root is None:
+        raise PzError(
+            code=error_code,
+            message=error_message,
+            stage="cli",
+            owner="pz_core.project_runtime",
+            action=action,
+            detail=f"missing runtime binding for {project_dir}",
+        )
+    project_python = _resolve_project_python(project_dir, runtime_package_root=runtime_package_root)
+    completed = subprocess.run(
+        [project_python, "-m", "pz_core", *argv],
+        check=False,
+        capture_output=True,
+        text=True,
+        env=_build_project_runtime_env(project_dir, runtime_package_root),
+    )
+    if completed.returncode != 0:
+        detail = (completed.stderr or completed.stdout or "project runtime command failed").strip()
+        raise PzError(
+            code=error_code,
+            message=error_message,
+            stage="cli",
+            owner="pz_core.project_runtime",
+            action=action,
+            detail=detail,
+        )
+    output = (completed.stdout or "").strip()
+    try:
+        payload = json.loads(output)
+    except Exception as exc:
+        raise PzError(
+            code=error_code,
+            message=error_message,
+            stage="cli",
+            owner="pz_core.project_runtime",
+            action=action,
+            detail=output or str(exc),
+        ) from exc
+    if not isinstance(payload, dict):
+        raise PzError(
+            code=error_code,
+            message=error_message,
+            stage="cli",
+            owner="pz_core.project_runtime",
+            action=action,
+            detail="project runtime command did not return a JSON object.",
+        )
+    return payload
+
+
+def resolve_project_pz_executable(project_dir: Path) -> str:
+    venv_root = project_dir / ".venv"
+    pz_command = _resolve_venv_pz_command(venv_root)
+    if pz_command is not None:
+        return str(pz_command)
+    resolved = shutil.which("pz")
+    if resolved:
+        return resolved
+    raise PzError(
+        code="PZ_PROJECT_RUNTIME_PZ_MISSING",
+        message="Formal `pz` launcher is required for project runtime handoff, but no `pz` command was found.",
+        stage="cli",
+        owner="pz_core.project_runtime",
+        action="resolve_project_pz_executable",
+    )
+
+
+def build_project_pz_child_env(
+    project_dir: Path,
+    *,
+    pz_env: str | None = None,
+    env_overrides: Mapping[str, str | int | None] | None = None,
+) -> dict[str, str]:
+    env = dict(os.environ)
+    env["PZ_PROJECT_DIR"] = str(project_dir.resolve())
+    inherited_pz_env = str(env.get("PZ_ENV") or "").strip()
+    resolved_pz_env = inherited_pz_env or str(pz_env or "").strip()
+    if resolved_pz_env:
+        env["PZ_ENV"] = resolved_pz_env
+    if env_overrides:
+        for raw_key, raw_value in env_overrides.items():
+            key = str(raw_key or "").strip()
+            if not key:
+                continue
+            if raw_value is None:
+                env.pop(key, None)
+                continue
+            env[key] = str(raw_value)
+    return env
+
+
+def _parse_project_dir_arg(args: list[str]) -> Path | None:
+    for index, raw in enumerate(args):
+        item = str(raw).strip()
+        if not item:
+            continue
+        if item in {"--project-dir", "-d"} and index + 1 < len(args):
+            value = str(args[index + 1]).strip()
+            if value:
+                return Path(value).expanduser().resolve()
+            return None
+        prefix = "--project-dir="
+        if item.startswith(prefix):
+            value = item[len(prefix) :].strip()
+            if value:
+                return Path(value).expanduser().resolve()
+            return None
+        short_prefix = "-d="
+        if item.startswith(short_prefix):
+            value = item[len(short_prefix) :].strip()
+            if value:
+                return Path(value).expanduser().resolve()
+            return None
+    return None
+
+
+def _read_project_dir_env() -> Path | None:
+    raw = os.getenv("PZ_PROJECT_DIR")
+    if not isinstance(raw, str) or not raw.strip():
+        return None
+    return Path(raw.strip()).expanduser().resolve()
+
+
+def _discover_project_dir_from_cwd() -> Path | None:
+    current = Path.cwd().resolve()
+    for candidate in (current, *current.parents):
+        if (candidate / PROJECT_JSONC_NAME).is_file():
+            return candidate
+    return None
+
+
+def _is_runtime_package_root(path: Path) -> bool:
+    return (
+        path.is_dir()
+        and (path / "__init__.py").is_file()
+        and (path / "__main__.py").is_file()
+    )
+
+
+def provider_resolution_locked() -> bool:
+    raw = os.getenv(PROVIDER_LOCK_ENV_NAME)
+    return isinstance(raw, str) and bool(raw.strip())
+
+
+def _resolve_runtime_package_root_candidate(project_dir: Path, raw_path: str) -> Path | None:
+    candidate = Path(raw_path).expanduser()
+    if not candidate.is_absolute():
+        candidate = project_dir / candidate
+    if _is_runtime_package_root(candidate):
+        return candidate.absolute()
+    nested = candidate / "pz"
+    if _is_runtime_package_root(nested):
+        return nested.absolute()
+    return None
+
+
+def _build_project_runtime_env(project_dir: Path, runtime_package_root: Path) -> dict[str, str]:
+    env = dict(os.environ)
+    existing_pythonpath = env.get("PYTHONPATH", "").strip()
+    pythonpath_entries = [entry for entry in existing_pythonpath.split(os.pathsep) if entry]
+    prepend_entries = [str(project_dir.resolve()), *[str(path) for path in _runtime_import_roots(runtime_package_root)]]
+    pythonpath_entries = [entry for entry in pythonpath_entries if entry not in prepend_entries]
+    env["PYTHONPATH"] = os.pathsep.join([*prepend_entries, *pythonpath_entries])
+    env["PZ_PROJECT_DIR"] = str(project_dir.resolve())
+    env["PYTHONNOUSERSITE"] = "1"
+    program_name = os.path.basename(str(sys.argv[0] or "")).strip().lower()
+    if program_name in {"pz", "pz"}:
+        env["PZ_PROGRAM_NAME"] = program_name
+    elif not env.get("PZ_PROGRAM_NAME"):
+        env["PZ_PROGRAM_NAME"] = "pz"
+    return env
+
+
+def _runtime_import_roots(runtime_package_root: Path) -> tuple[Path, ...]:
+    roots: list[Path] = [runtime_package_root.parent.resolve()]
+    checkout_root = resolve_runtime_checkout_root(runtime_package_root)
+    contrib_root = resolve_contrib_source_root(checkout_root)
+    if contrib_root.is_dir():
+        for package_root in sorted(contrib_root.iterdir()):
+            if not package_root.is_dir():
+                continue
+            if not (package_root / "pyproject.toml").is_file():
+                continue
+            roots.append(package_root.resolve())
+    return tuple(roots)
+
+
+def _source_project_root(path: Path) -> Path | None:
+    absolute = path.expanduser().absolute()
+    for candidate in (absolute, *absolute.parents):
+        if candidate.name == ".sources" and candidate.parent.name == "apps":
+            return candidate.parent.parent.absolute()
+    return None
+
+
+def _target_virtualenv_path(path: Path) -> Path:
+    absolute = path.expanduser().absolute()
+    project_root = _source_project_root(absolute)
+    if project_root is None:
+        return absolute.resolve() / ".venv"
+    try:
+        relative = absolute.relative_to(project_root)
+    except ValueError:
+        return absolute.resolve() / ".venv"
+    return project_root / ".runtime" / "source-venvs" / relative / ".venv"
+
+
+def _resolve_project_python(project_dir: Path, *, runtime_package_root: Path | None = None) -> str:
+    candidates: list[Path] = [
+        project_dir / ".venv" / "bin" / "python",
+        project_dir / ".venv" / "Scripts" / "python.exe",
+    ]
+    if runtime_package_root is not None:
+        runtime_roots = [runtime_package_root.parent.absolute(), runtime_package_root.absolute()]
+        for root in runtime_roots:
+            candidates.extend(
+                (
+                    _target_virtualenv_path(root) / "bin" / "python",
+                    _target_virtualenv_path(root) / "Scripts" / "python.exe",
+                )
+            )
+    for candidate in candidates:
+        if candidate.is_file():
+            return str(candidate.expanduser().absolute())
+    return sys.executable
+
+
+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.expanduser().absolute()
+    return None
+
+
+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__ = [
+    "build_project_pz_child_env",
+    "PROVIDER_LOCK_ENV_NAME",
+    "handoff_to_project_runtime",
+    "provider_resolution_locked",
+    "resolve_cli_project_dir",
+    "resolve_project_pz_executable",
+    "resolve_project_runtime_package_root",
+    "run_project_runtime_json_command",
+]