pz-cli 5.0.0__py3-none-any.whl

pz_core/authoring/project_state.py

@@ -0,0 +1,399 @@
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import cast
+
+from .project_defaults import build_project_scaffold_payload, compact_project_payload
+from pz_core.project_sources import (
+    resolve_known_sources_roots,
+    resolve_sources_manifest_path,
+    resolve_sources_repo_checkout_root,
+    resolve_sources_root,
+)
+from pz_core.runtime.errors import PzError
+from pz_core.utils import PROJECT_JSONC_NAME, dump_jsonc_document, load_jsonc_file
+
+from .naming import derive_default_local_app_slug, normalize_app_slug
+from .dev_manifest import (
+    DevBinding,
+    DevManifest,
+    DevRepo,
+    load_dev_manifest,
+    manifest_bytes,
+    save_dev_manifest,
+    validate_dev_manifest,
+)
+
+
+BUSINESS_APP_ID_ERROR_CODE = "PZ_DEV_BUSINESS_APP_ID_INVALID"
+_RESERVED_BUSINESS_APP_IDS = frozenset({"apps", "pz", "pz_apps"})
+GitRefRunner = Callable[[tuple[str, ...]], int]
+
+
+@dataclass(frozen=True, slots=True)
+class BusinessAppIdentity:
+    business_app_id: str
+    manifest: DevManifest
+    created: bool
+
+
+def _business_app_id_invalid(message: str, *, action: str) -> PzError:
+    return PzError(
+        code=BUSINESS_APP_ID_ERROR_CODE,
+        message=message,
+        stage="dev",
+        owner="pz_core.authoring.project_state",
+        action=action,
+    )
+
+
+def _run_git_ref_check(argv: tuple[str, ...]) -> int:
+    return subprocess.run(
+        argv,
+        check=False,
+        capture_output=True,
+        text=True,
+    ).returncode
+
+
+def _default_project_payload() -> dict[str, object]:
+    return build_project_scaffold_payload(installed_apps=["apps"])
+
+
+def _deep_merge_payload(
+    base: dict[str, object], incoming: dict[str, object]
+) -> dict[str, object]:
+    merged: dict[str, object] = dict(base)
+    for key, value in incoming.items():
+        if isinstance(value, dict):
+            previous = merged.get(key)
+            if isinstance(previous, dict):
+                merged[key] = _deep_merge_payload(
+                    cast(dict[str, object], previous),
+                    cast(dict[str, object], value),
+                )
+                continue
+        merged[key] = value
+    return merged
+
+
+def resolve_project_config_path(project_dir: Path) -> Path:
+    return project_dir / PROJECT_JSONC_NAME
+
+
+def ensure_project_state(project_dir: Path, *, action: str) -> None:
+    if not project_dir.exists() or not project_dir.is_dir():
+        raise PzError(
+            code="PZ_SCAFFOLD_PROJECT_DIR_INVALID",
+            message=f"project directory must exist: {project_dir}",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    apps_root = project_dir / "apps"
+    if not apps_root.exists() or not apps_root.is_dir():
+        raise PzError(
+            code="PZ_SCAFFOLD_APPS_DIR_MISSING",
+            message=f"apps container does not exist: {apps_root}",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    config_path = resolve_project_config_path(project_dir)
+    if not config_path.exists():
+        config_path.write_text(
+            dump_jsonc_document(
+                _default_project_payload(), managed_paths=("installed_apps",)
+            ),
+            encoding="utf-8",
+        )
+
+
+def normalize_formal_app_id(value: object, *, action: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise PzError(
+            code="PZ_SCAFFOLD_NAME_INVALID",
+            message="app id must be a non-empty string.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    normalized = value.strip().replace("-", "_")
+    return normalize_app_slug(normalized, action=action)
+
+
+def _normalize_business_app_id(value: object, *, action: str) -> str:
+    if isinstance(value, str) and "__" in value.strip().replace("-", "_"):
+        raise _business_app_id_invalid(
+            "business app id cannot contain repeated separators.",
+            action=action,
+        )
+    try:
+        business_app_id = normalize_formal_app_id(value, action=action)
+    except PzError as exc:
+        raise _business_app_id_invalid(
+            "business app id must satisfy the formal app-id contract.",
+            action=action,
+        ) from exc
+    if business_app_id in _RESERVED_BUSINESS_APP_IDS:
+        raise _business_app_id_invalid(
+            f"business app id is reserved: {business_app_id}",
+            action=action,
+        )
+    return business_app_id
+
+
+def _validate_business_app_git_ref(
+    business_app_id: str,
+    *,
+    action: str,
+    git_ref_runner: GitRefRunner,
+) -> None:
+    argv = ("git", "check-ref-format", "--branch", business_app_id)
+    try:
+        returncode = git_ref_runner(argv)
+    except (OSError, ValueError) as exc:
+        raise _business_app_id_invalid(
+            f"cannot validate business app id as a Git branch: {business_app_id}",
+            action=action,
+        ) from exc
+    if returncode != 0:
+        raise _business_app_id_invalid(
+            f"business app id is not a valid Git branch: {business_app_id}",
+            action=action,
+        )
+
+
+def ensure_business_app_identity(
+    project_dir: Path,
+    *,
+    app_name: str | None,
+    action: str,
+    git_ref_runner: GitRefRunner | None = None,
+) -> BusinessAppIdentity:
+    runner = _run_git_ref_check if git_ref_runner is None else git_ref_runner
+    existing_manifest = load_dev_manifest(project_dir)
+    if existing_manifest is not None:
+        business_app_id = _normalize_business_app_id(
+            existing_manifest.business_app_id,
+            action=action,
+        )
+        if app_name is not None:
+            requested_app_id = _normalize_business_app_id(app_name, action=action)
+            if requested_app_id != business_app_id:
+                raise _business_app_id_invalid(
+                    "business app id is already persisted and cannot be changed.",
+                    action=action,
+                )
+        _validate_business_app_git_ref(
+            business_app_id,
+            action=action,
+            git_ref_runner=runner,
+        )
+        return BusinessAppIdentity(
+            business_app_id=business_app_id,
+            manifest=existing_manifest,
+            created=False,
+        )
+
+    candidate = (
+        app_name
+        if app_name is not None
+        else derive_default_local_app_slug(project_dir)
+    )
+    business_app_id = _normalize_business_app_id(candidate, action=action)
+    _validate_business_app_git_ref(
+        business_app_id,
+        action=action,
+        git_ref_runner=runner,
+    )
+    manifest = DevManifest(
+        schema_version=5,
+        business_app_id=business_app_id,
+        repos={},
+        bindings={},
+    )
+    save_dev_manifest(project_dir, manifest)
+    return BusinessAppIdentity(
+        business_app_id=business_app_id,
+        manifest=manifest,
+        created=True,
+    )
+
+
+def load_project_payload(project_dir: Path, *, action: str) -> dict[str, object]:
+    ensure_project_state(project_dir, action=action)
+    payload = load_jsonc_file(
+        resolve_project_config_path(project_dir),
+        code="PZ_SCAFFOLD_PROJECT_CONFIG_INVALID",
+        owner="pz_core.authoring",
+        action=action,
+    )
+    if not payload:
+        return _default_project_payload()
+    sanitized_payload = dict(payload)
+    sanitized_payload.pop("catalog", None)
+    return _deep_merge_payload(_default_project_payload(), sanitized_payload)
+
+
+def save_project_payload(
+    project_dir: Path, payload: dict[str, object], *, action: str
+) -> None:
+    ensure_project_state(project_dir, action=action)
+    sanitized_payload = dict(payload)
+    sanitized_payload.pop("catalog", None)
+    config = _deep_merge_payload(_default_project_payload(), sanitized_payload)
+    config.setdefault("installed_apps", ["apps"])
+    compacted = compact_project_payload(config)
+    resolve_project_config_path(project_dir).write_text(
+        dump_jsonc_document(compacted, managed_paths=("installed_apps",)),
+        encoding="utf-8",
+    )
+
+
+def load_installed_apps(project_dir: Path, *, action: str) -> list[str]:
+    payload = load_project_payload(project_dir, action=action)
+    raw_apps = payload.get("installed_apps", ["apps"])
+    if not isinstance(raw_apps, list):
+        raise PzError(
+            code="PZ_SCAFFOLD_PROJECT_CONFIG_INVALID",
+            message="project installed_apps must be an array.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    installed_apps: list[str] = []
+    for item in raw_apps:
+        if not isinstance(item, str) or not item.strip():
+            raise PzError(
+                code="PZ_SCAFFOLD_PROJECT_CONFIG_INVALID",
+                message="project installed_apps entries must be non-empty strings.",
+                stage="cli",
+                owner="pz_core.authoring",
+                action=action,
+            )
+        installed_apps.append(item.strip())
+    return installed_apps
+
+
+def save_installed_apps(
+    project_dir: Path, installed_apps: list[str], *, action: str
+) -> None:
+    ensure_project_state(project_dir, action=action)
+    unique: list[str] = []
+    seen: set[str] = set()
+    for item in installed_apps:
+        normalized = item.strip()
+        if not normalized or normalized in seen:
+            continue
+        seen.add(normalized)
+        unique.append(normalized)
+    if "apps" in unique:
+        unique = ["apps", *[item for item in unique if item != "apps"]]
+    if not unique:
+        unique = ["apps"]
+    payload = load_project_payload(project_dir, action=action)
+    payload["installed_apps"] = unique
+    save_project_payload(project_dir, payload, action=action)
+
+
+def add_declared_app(project_dir: Path, app_id: str, *, action: str) -> list[str]:
+    installed_apps = load_installed_apps(project_dir, action=action)
+    if app_id not in installed_apps:
+        installed_apps.append(app_id)
+        save_installed_apps(project_dir, installed_apps, action=action)
+    return load_installed_apps(project_dir, action=action)
+
+
+def remove_declared_app(project_dir: Path, app_id: str, *, action: str) -> list[str]:
+    installed_apps = [
+        item
+        for item in load_installed_apps(project_dir, action=action)
+        if item != app_id
+    ]
+    save_installed_apps(project_dir, installed_apps, action=action)
+    return load_installed_apps(project_dir, action=action)
+
+
+def dev_manifest_path(project_dir: Path) -> Path:
+    return resolve_sources_manifest_path(project_dir)
+
+
+def resolve_manifest_bound_path(project_dir: Path, raw_path: object) -> Path | None:
+    if not isinstance(raw_path, str) or not raw_path.strip():
+        return None
+    candidate = Path(raw_path.strip()).expanduser()
+    if not candidate.is_absolute():
+        candidate = project_dir / candidate
+    return candidate.resolve()
+
+
+def serialize_manifest_bound_path(project_dir: Path, path: Path) -> str:
+    resolved = path.expanduser().resolve()
+    project_root = project_dir.resolve()
+    try:
+        return resolved.relative_to(project_root).as_posix()
+    except ValueError:
+        return str(resolved)
+
+
+def resolve_runtime_source_path(project_dir: Path, runtime_id: str) -> Path | None:
+    manifest = load_dev_manifest(project_dir)
+    if manifest is None:
+        return None
+    binding = manifest.bindings.get(runtime_id)
+    if binding is None:
+        if runtime_id != "pz":
+            return None
+        repo = manifest.repos.get("pz")
+        if repo is None:
+            return None
+        checkout = project_dir / Path(*repo.checkout.parts)
+        core_root = checkout / "pz_core"
+        return (core_root if core_root.exists() else checkout).resolve()
+    if binding.source_kind == "link":
+        base = Path(binding.source)
+    else:
+        if binding.repo_key is None:
+            return None
+        repo = manifest.repos.get(binding.repo_key)
+        if repo is None:
+            return None
+        base = project_dir / Path(*repo.checkout.parts)
+    if binding.subpath.as_posix() == ".":
+        return base.resolve()
+    return (base / Path(*binding.subpath.parts)).resolve()
+
+
+__all__ = [
+    "add_declared_app",
+    "BUSINESS_APP_ID_ERROR_CODE",
+    "BusinessAppIdentity",
+    "DevBinding",
+    "DevManifest",
+    "DevRepo",
+    "dev_manifest_path",
+    "ensure_project_state",
+    "ensure_business_app_identity",
+    "load_dev_manifest",
+    "load_installed_apps",
+    "load_project_payload",
+    "manifest_bytes",
+    "normalize_formal_app_id",
+    "resolve_known_sources_roots",
+    "resolve_manifest_bound_path",
+    "remove_declared_app",
+    "resolve_sources_manifest_path",
+    "resolve_sources_repo_checkout_root",
+    "resolve_sources_root",
+    "resolve_runtime_source_path",
+    "resolve_project_config_path",
+    "save_dev_manifest",
+    "serialize_manifest_bound_path",
+    "save_installed_apps",
+    "save_project_payload",
+    "validate_dev_manifest",
+]