pz-cli 5.0.0__py3-none-any.whl

pz_core/authoring/orchestration_service.py

@@ -0,0 +1,558 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from contextlib import contextmanager
+from dataclasses import dataclass, replace
+from importlib import invalidate_caches
+import json
+from pathlib import Path
+import site
+import subprocess
+import sys
+from typing import Any
+
+from pz_core.runtime.errors import PzError, as_pz_error
+
+from .app_init_service import (
+    AppInitSourcePlan,
+    AppInitSourcesResult,
+    SourcePackageInstallResult,
+    build_app_init_source_plan,
+    init_project_source_apps,
+)
+from .app_versions import (
+    declare_app_version,
+    query_app_versions,
+    reconcile_project_environment,
+    resolve_app_version,
+)
+from .dev_git import BaseBranch
+from .dev_import import cache_git_source, import_cached_apps
+from .dev_sources import (
+    DevTransactionResult,
+    InitDevSourcesRequest,
+    initialize_dev_sources,
+)
+from .project_settings_service import update_settings_file
+from .ide_projection import sync_ide_projections
+from .project_metadata_service import update_project_uv_sources
+from .project_state import ensure_business_app_identity, ensure_project_state
+from pz_core.project_sources import load_official_source_catalog
+from .release import PublishResult, publish_app
+from .scaffold_service import ensure_default_local_app, ensure_project_scaffold
+from .sync_service import sync_project_targets
+from .venv_service import (
+    ProjectVirtualenvResult,
+    ensure_project_virtualenv,
+    resolve_virtualenv_python,
+)
+
+
+ProgressReporter = Callable[[str], None]
+
+
+@contextmanager
+def _source_plan_import_paths(
+    plan: AppInitSourcePlan,
+    *,
+    project_venv: Path | None,
+    action: str,
+):
+    original = tuple(sys.path)
+    try:
+        if project_venv is not None:
+            for site_packages in _project_venv_site_packages(
+                project_venv,
+                action=action,
+            ):
+                site.addsitedir(str(site_packages))
+        if project_venv is None:
+            source_roots: list[str] = []
+            for package in plan.packages:
+                root = str(package.package_root)
+                if root not in source_roots:
+                    source_roots.append(root)
+            for root in reversed(source_roots):
+                while root in sys.path:
+                    sys.path.remove(root)
+                sys.path.insert(0, root)
+        invalidate_caches()
+        yield
+    finally:
+        sys.path[:] = original
+        invalidate_caches()
+
+
+def _project_venv_site_packages(
+    project_venv: Path,
+    *,
+    action: str,
+) -> tuple[Path, ...]:
+    python = resolve_virtualenv_python(project_venv, action=action)
+    completed = subprocess.run(
+        (
+            str(python),
+            "-c",
+            "import json, site; print(json.dumps(site.getsitepackages()))",
+        ),
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    if completed.returncode != 0:
+        raise PzError(
+            code="PZ_APP_INIT_VENV_INSPECTION_FAILED",
+            message="failed to inspect project virtualenv import paths.",
+            stage="app_init",
+            owner="pz_core.authoring.orchestration_service",
+            action=action,
+            detail=(completed.stderr or completed.stdout or "site inspection failed").strip(),
+        )
+    try:
+        payload = json.loads(completed.stdout)
+    except json.JSONDecodeError as exc:
+        raise PzError(
+            code="PZ_APP_INIT_VENV_INSPECTION_FAILED",
+            message="project virtualenv returned invalid import path metadata.",
+            stage="app_init",
+            owner="pz_core.authoring.orchestration_service",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    if not isinstance(payload, list) or not all(
+        isinstance(item, str) and item.strip() for item in payload
+    ):
+        raise PzError(
+            code="PZ_APP_INIT_VENV_INSPECTION_FAILED",
+            message="project virtualenv returned invalid import path metadata.",
+            stage="app_init",
+            owner="pz_core.authoring.orchestration_service",
+            action=action,
+        )
+    return tuple(Path(item).resolve() for item in payload)
+
+
+@dataclass(frozen=True, slots=True)
+class DevInitPreparationResult:
+    business_app_id: str
+    scaffold_created: bool
+    default_app_id: str | None
+    default_app_created: bool
+    project_venv: ProjectVirtualenvResult | None
+
+
+@dataclass(frozen=True, slots=True)
+class EnvInstallExecutionResult:
+    project_venv: ProjectVirtualenvResult
+    synced_targets: tuple[Any, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class EnvInitExecutionResult:
+    initialized_project: bool
+    project_venv: ProjectVirtualenvResult | None
+    synced_targets: tuple[Any, ...]
+    settings_path: Path
+
+
+@dataclass(frozen=True, slots=True)
+class EnvSyncExecutionResult:
+    synced_targets: tuple[Any, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class AppInitExecutionResult:
+    source_apps: AppInitSourcesResult
+    project_venv: ProjectVirtualenvResult | None
+    source_install: SourcePackageInstallResult
+    synced_targets: tuple[Any, ...]
+    settings_path: Path | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class PublishBatchExecutionResult:
+    results: tuple[PublishResult, ...]
+    summary_message: str
+
+
+def prepare_dev_init_project(
+    project_dir: Path,
+    *,
+    app_name: str | None,
+    action: str,
+) -> DevInitPreparationResult:
+    identity = ensure_business_app_identity(
+        project_dir,
+        app_name=app_name,
+        action=action,
+    )
+    scaffold_result = ensure_project_scaffold(project_dir)
+    ensure_project_state(project_dir, action=action)
+    default_app_result = ensure_default_local_app(
+        project_dir,
+        app_name=identity.business_app_id,
+        scaffold_created=scaffold_result.created,
+        action=action,
+    )
+    return DevInitPreparationResult(
+        business_app_id=identity.business_app_id,
+        scaffold_created=scaffold_result.created,
+        default_app_id=default_app_result.app_id,
+        default_app_created=default_app_result.created,
+        project_venv=None,
+    )
+
+
+def execute_env_install(
+    project_dir: Path,
+    *,
+    action: str,
+    groups: Sequence[str] = (),
+    extras: Sequence[str] = (),
+    reinstall_packages: Sequence[str] = (),
+    project_only: bool = False,
+    existing_project_venv: ProjectVirtualenvResult | None = None,
+    sync_targets: Callable[..., tuple[Any, ...]] | None = None,
+) -> EnvInstallExecutionResult:
+    project_venv = existing_project_venv or ensure_project_virtualenv(
+        project_dir, action=action
+    )
+    synced_targets = (
+        sync_targets
+        if sync_targets is not None
+        else lambda path, **kwargs: sync_project_targets(path, action=action, **kwargs)
+    )(
+        project_dir,
+        groups=tuple(groups),
+        extras=tuple(extras),
+        reinstall_packages=tuple(reinstall_packages),
+        project_only=project_only,
+    )
+    return EnvInstallExecutionResult(
+        project_venv=project_venv,
+        synced_targets=synced_targets,
+    )
+
+
+def execute_dev_init(
+    project_dir: Path,
+    *,
+    app_name: str | None,
+    base_branch: BaseBranch,
+    clone_sources: bool,
+    link: bool = False,
+    source_dir: str | None = None,
+    no_sync: bool,
+    action: str,
+    progress_reporter: ProgressReporter | None = None,
+) -> tuple[DevInitPreparationResult, DevTransactionResult]:
+    if progress_reporter is not None:
+        progress_reporter(f"Preparing project scaffold in {project_dir}.")
+    preparation = prepare_dev_init_project(
+        project_dir, app_name=app_name, action=action
+    )
+    if progress_reporter is not None:
+        if preparation.scaffold_created:
+            progress_reporter("Project scaffold is ready.")
+        if preparation.default_app_created and preparation.default_app_id is not None:
+            progress_reporter(
+                f"Default local app `{preparation.default_app_id}` is ready."
+            )
+    if link and clone_sources == (source_dir is not None):
+        raise PzError(
+            code="PZ_DEV_INIT_SOURCE_SELECTOR_INVALID",
+            message="pz dev init --link 必须且只能指定 --clone-sources 或 --source-dir。",
+            stage="dev",
+            owner="pz_core.authoring.orchestration_service",
+            action=action,
+        )
+    if not link and (clone_sources or source_dir is not None):
+        raise PzError(
+            code="PZ_DEV_INIT_SOURCE_SELECTOR_INVALID",
+            message="--clone-sources 和 --source-dir 只能与 --link 一起使用。",
+            stage="dev",
+            owner="pz_core.authoring.orchestration_service",
+            action=action,
+        )
+    if link:
+        if progress_reporter is not None:
+            progress_reporter("Binding the official pz bootstrap repository.")
+        shared_entry: Path | None = None
+        shared_entry_created = False
+        if source_dir is not None:
+            external = Path(source_dir).expanduser().resolve(strict=True)
+            if not external.is_dir() or not (external / ".git").exists():
+                raise PzError(
+                    code="PZ_DEV_INIT_SOURCE_DIR_INVALID",
+                    message="--source-dir 必须指向本地 pz Git checkout。",
+                    stage="dev",
+                    owner="pz_core.authoring.orchestration_service",
+                    action=action,
+                )
+            shared_entry = project_dir / "apps" / ".sources" / "pz"
+            shared_entry.parent.mkdir(parents=True, exist_ok=True)
+            if shared_entry.is_symlink():
+                if shared_entry.resolve(strict=True) != external:
+                    raise PzError(
+                        code="PZ_DEV_SOURCE_CONFLICT",
+                        message="apps/.sources/pz 已指向另一个共享 checkout。",
+                        stage="dev",
+                        owner="pz_core.authoring.orchestration_service",
+                        action=action,
+                    )
+            elif shared_entry.exists():
+                raise PzError(
+                    code="PZ_DEV_SOURCE_CONFLICT",
+                    message="apps/.sources/pz 已被现有路径占用。",
+                    stage="dev",
+                    owner="pz_core.authoring.orchestration_service",
+                    action=action,
+                )
+            else:
+                shared_entry.symlink_to(external, target_is_directory=True)
+                shared_entry_created = True
+        try:
+            dev_sources = initialize_dev_sources(
+                InitDevSourcesRequest(
+                    project_dir=project_dir,
+                    app_name=preparation.business_app_id,
+                    locators=("pz", "pz_settings_center", "pz_foundation"),
+                    base_branch=base_branch,
+                )
+            )
+        except Exception:
+            if shared_entry_created and shared_entry is not None:
+                shared_entry.unlink(missing_ok=True)
+            raise
+        metadata = update_project_uv_sources(project_dir, action=action)
+        init_project_source_apps(project_dir, action=action, plan=metadata.plan)
+    else:
+        if progress_reporter is not None:
+            progress_reporter("Caching and importing official pz_apps source.")
+        root = load_official_source_catalog()["pz_apps"]
+        cache = cache_git_source(
+            repo_key=root.repo_key,
+            source=root.source,
+            branch="develop",
+            action=action,
+        )
+        app_specs = tuple(
+            (child.expected_app_id, child.subpath)
+            for child in root.children.values()
+            if child.kind == "app" and child.expected_app_id is not None
+        )
+        imported = import_cached_apps(
+            cache,
+            project_dir=project_dir,
+            apps=app_specs,
+            action=action,
+        )
+        dev_sources = DevTransactionResult(
+            operation="init",
+            project_dir=project_dir,
+            business_branch=preparation.business_app_id,
+            base_branch=base_branch,
+            repo_keys=(),
+            checkouts=(),
+            bindings=tuple(item.app_id for item in imported),
+            links=tuple(item.destination for item in imported),
+        )
+    settings_result = update_settings_file(project_dir)
+    if not no_sync:
+        if progress_reporter is not None:
+            progress_reporter("Running initial environment install.")
+        install_result = execute_env_install(
+            project_dir,
+            action=action,
+            existing_project_venv=preparation.project_venv,
+        )
+        preparation = replace(preparation, project_venv=install_result.project_venv)
+        if progress_reporter is not None:
+            progress_reporter(
+                f"Initial environment install finished for {len(install_result.synced_targets)} target(s)."
+            )
+    if progress_reporter is not None:
+        progress_reporter(f"Managed settings are ready at {settings_result.path}.")
+    sync_ide_projections(project_dir)
+    return preparation, dev_sources
+
+
+def execute_env_init(
+    project_dir: Path,
+    *,
+    action: str,
+    no_sync: bool,
+) -> EnvInitExecutionResult:
+    scaffold_result = ensure_project_scaffold(project_dir)
+    settings_result = update_settings_file(project_dir)
+    install_result: EnvInstallExecutionResult | None = None
+    if not no_sync:
+        install_result = execute_env_install(project_dir, action=action)
+    return EnvInitExecutionResult(
+        initialized_project=scaffold_result.created,
+        project_venv=None if install_result is None else install_result.project_venv,
+        synced_targets=() if install_result is None else install_result.synced_targets,
+        settings_path=settings_result.path,
+    )
+
+
+def execute_env_sync(
+    project_dir: Path,
+    *,
+    groups: Sequence[str],
+    extras: Sequence[str],
+    reinstall_packages: Sequence[str],
+    project_only: bool,
+    sync_targets: Callable[..., tuple[Any, ...]],
+) -> EnvSyncExecutionResult:
+    synced_targets = sync_targets(
+        project_dir,
+        groups=tuple(groups),
+        extras=tuple(extras),
+        reinstall_packages=tuple(reinstall_packages),
+        project_only=project_only,
+    )
+    return EnvSyncExecutionResult(synced_targets=synced_targets)
+
+
+def execute_app_init(
+    project_dir: Path,
+    *,
+    no_sync: bool,
+    action: str,
+) -> AppInitExecutionResult:
+    ensure_project_scaffold(project_dir)
+    ensure_project_state(project_dir, action=action)
+    plan = build_app_init_source_plan(project_dir, action=action)
+    exact_versions: dict[str, str] = {}
+    for package in plan.app_packages:
+        state = query_app_versions(
+            package.app_id,
+            project_dir=project_dir,
+            action=action,
+        )
+        exact_versions[package.app_id] = resolve_app_version(
+            state,
+            None,
+            project_dir=project_dir,
+            action=action,
+        )
+    source_apps = init_project_source_apps(
+        project_dir,
+        action=action,
+        plan=plan,
+    )
+    for package in plan.app_packages:
+        declare_app_version(
+            package.app_id,
+            exact_versions[package.app_id],
+            project_dir=project_dir,
+            action=action,
+        )
+    project_venv: ProjectVirtualenvResult | None = None
+    source_install = SourcePackageInstallResult(
+        distributions=(),
+        install_target=None,
+        install_targets=(),
+        python=None,
+        command=(),
+    )
+    synced_targets: tuple[Any, ...] = ()
+    if not no_sync:
+        project_venv = ensure_project_virtualenv(project_dir, action=action)
+        if plan.app_packages:
+            first = plan.app_packages[0]
+            reconcile_project_environment(
+                first.app_id,
+                project_dir=project_dir,
+                action=action,
+            )
+        for package in plan.app_packages:
+            expected = exact_versions[package.app_id]
+            state = query_app_versions(
+                package.app_id,
+                project_dir=project_dir,
+                action=action,
+            )
+            if state.locked != expected or state.installed != expected:
+                raise PzError(
+                    code="PZ_APP_VERSION_STATE_MISMATCH",
+                    message=f"{package.distribution} did not converge to {expected}.",
+                    stage="app_init",
+                    owner="pz_core.authoring.orchestration_service",
+                    action=action,
+                    detail=f"locked={state.locked!r}; installed={state.installed!r}",
+                )
+        source_install = SourcePackageInstallResult(
+            distributions=tuple(
+                f"{package.distribution}=={exact_versions[package.app_id]}"
+                for package in plan.app_packages
+            ),
+            install_target=None,
+            install_targets=(),
+            python=resolve_virtualenv_python(project_venv.path, action=action),
+            command=("uv", "sync", "--active"),
+        )
+    with _source_plan_import_paths(
+        plan,
+        project_venv=None if project_venv is None else project_venv.path,
+        action=action,
+    ):
+        settings_path = update_settings_file(project_dir).path
+    return AppInitExecutionResult(
+        source_apps=source_apps,
+        project_venv=project_venv,
+        source_install=source_install,
+        synced_targets=synced_targets,
+        settings_path=settings_path,
+    )
+
+
+def execute_publish_batch(
+    app_ids: Sequence[str],
+    *,
+    project_dir: Path,
+    target_name: str | None,
+    dry_run: bool,
+    action: str,
+) -> PublishBatchExecutionResult:
+    results: list[PublishResult] = []
+    for raw_app_id in app_ids:
+        try:
+            result = publish_app(
+                raw_app_id,
+                project_dir=project_dir,
+                target_name=target_name,
+                dry_run=dry_run,
+                action=action,
+            )
+        except Exception as exc:
+            if not results:
+                raise
+            root_error = as_pz_error(
+                exc, owner="pz_core.authoring", action=action, stage="cli"
+            )
+            completed = ", ".join(result.app_id for result in results)
+            raise PzError(
+                code="PZ_SCAFFOLD_PUBLISH_BATCH_FAILED",
+                message=(
+                    f"batch publish stopped at `{raw_app_id}` after "
+                    f"{len(results)} successful publish(es)."
+                ),
+                stage="cli",
+                owner="pz_core.authoring",
+                action=action,
+                detail=(
+                    f"completed: {completed}; "
+                    f"failed: {root_error.code}: {root_error.message}"
+                ),
+            ) from exc
+        results.append(result)
+    summary_message = (
+        f"Completed batch publish for {len(results)} package(s) using target "
+        f"{results[0].target.name if results else (target_name or 'default')}: "
+        f"{', '.join(result.app_id for result in results)}."
+    )
+    return PublishBatchExecutionResult(
+        results=tuple(results), summary_message=summary_message
+    )

pz_core/authoring/project_default.jsonc

@@ -0,0 +1,53 @@
+{
+  "installed_apps": [],
+  "commands": {
+    // npm-like project root command extension point.
+    // string -> shell command
+    // array -> argv execution
+    // object -> {"command": "..."} or {"argv": ["..."], "description": "..."}
+  },
+  "project": {
+    "name": "PZ Project",
+    "default_module": "base",
+    "site_theme": "default",
+    // Single service base URL. Local/IP URLs may be adjusted by explicit
+    // APP_HOST or APP_PORT runtime overrides; domain URLs stay canonical.
+    "base_url": "http://127.0.0.1:8000",
+    "app_host": "0.0.0.0",
+    "api_v1_str": "/api/v1",
+    "static_version": 1,
+    "settings_backup_keep_count": 15,
+    "app_port": 8000,
+    "app_workers": 1,
+    "app_reload": false,
+    "static_target_path": "",
+    "static_target_owner": "",
+    "asset_dir": ".assets"
+  },
+  "resources": {
+    // Formal resource items that pz will discover inside each app package
+    // and merge in installed_apps order during startup compilation.
+    "items": [
+      { "name": "templates" },
+      { "name": "static" },
+      { "name": "locales" },
+      { "name": "pages" },
+      { "name": "template_config" },
+      { "name": "migrations" }
+    ],
+    // Root directory under cache_dir that stores merged resource artifacts.
+    "output_root": "resources",
+    // Manifest file name written under output_root.
+    "manifest_name": "manifest.json",
+    // Temporary staging directory name under output_root used before atomic swap/publish.
+    "staging_dir": "staging",
+    // Lock file name written under runtime_dir/locks for resource compilation.
+    "lock_name": "resources.lock"
+  },
+  "routing": {},
+  "events": {
+    "declared": {}
+  },
+  "app_replacements": {},
+  "apps": {}
+}

pz_core/authoring/project_defaults.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pz_core.utils.project_jsonc import load_jsonc_file
+
+
+PROJECT_DEFAULT_JSONC_NAME = "project_default.jsonc"
+_MANAGED_ROOT_KEYS = frozenset({"installed_apps", "middlewares"})
+_OMIT = object()
+
+
+def project_default_jsonc_path() -> Path:
+    return Path(__file__).resolve().with_name(PROJECT_DEFAULT_JSONC_NAME)
+
+
+def load_project_default_jsonc_payload() -> dict[str, Any]:
+    payload = load_jsonc_file(
+        project_default_jsonc_path(),
+        code="PZ_PROJECT_DEFAULTS_INVALID",
+        owner="pz_core.authoring",
+        action="load_project_defaults",
+    )
+    if not isinstance(payload, dict):
+        return {}
+    return dict(payload)
+
+
+def build_project_scaffold_payload(*, installed_apps: list[str] | None = None) -> dict[str, Any]:
+    return {
+        "installed_apps": list(installed_apps or []),
+        "commands": {},
+        "project": {
+            "static_version": 1,
+        },
+    }
+
+
+def compact_project_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    defaults = load_project_default_jsonc_payload()
+    compacted = _compact_value(payload, defaults, at_root=True)
+    if not isinstance(compacted, dict):
+        return {}
+    return dict(compacted)
+
+
+def _compact_value(value: Any, default: Any, *, at_root: bool = False) -> Any:
+    if at_root and isinstance(value, dict):
+        compacted_root: dict[str, Any] = {}
+        default_mapping = default if isinstance(default, dict) else {}
+        for key, item in value.items():
+            if key in _MANAGED_ROOT_KEYS:
+                compacted_root[key] = item
+                continue
+            compacted = _compact_value(item, default_mapping.get(key, _OMIT))
+            if compacted is _OMIT:
+                continue
+            compacted_root[key] = compacted
+        return compacted_root
+
+    if isinstance(value, dict):
+        default_mapping = default if isinstance(default, dict) else None
+        compacted_mapping: dict[str, Any] = {}
+        for key, item in value.items():
+            next_default = default_mapping.get(key, _OMIT) if isinstance(default_mapping, dict) else _OMIT
+            compacted = _compact_value(item, next_default)
+            if compacted is _OMIT:
+                continue
+            compacted_mapping[key] = compacted
+        if compacted_mapping:
+            return compacted_mapping
+        if isinstance(default_mapping, dict):
+            return _OMIT
+        return value
+
+    if default is not _OMIT and value == default:
+        return _OMIT
+    return value
+
+
+__all__ = [
+    "PROJECT_DEFAULT_JSONC_NAME",
+    "build_project_scaffold_payload",
+    "compact_project_payload",
+    "load_project_default_jsonc_payload",
+    "project_default_jsonc_path",
+]