pz-cli 5.0.0__py3-none-any.whl

pz_core/authoring/naming.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from pathlib import Path
+import re
+
+from pz_core.runtime.errors import PzError
+
+_SLUG_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+
+
+def resolve_project_dir(raw: str | None) -> Path:
+    return Path(raw or ".").expanduser().resolve()
+
+
+def normalize_app_slug(name: object, *, action: str) -> str:
+    if not isinstance(name, str) or not name.strip():
+        raise PzError(
+            code="PZ_SCAFFOLD_NAME_INVALID",
+            message="app name must be a non-empty string.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    value = name.strip().replace("-", "_")
+    if not _SLUG_RE.fullmatch(value):
+        raise PzError(
+            code="PZ_SCAFFOLD_NAME_INVALID",
+            message="app name must be a lowercase snake_case identifier.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    return value
+
+
+def build_app_id(slug: str) -> str:
+    return slug
+
+
+def derive_default_local_app_slug(project_dir: Path) -> str:
+    candidate = str(project_dir.name or "").strip()
+    candidate = re.sub(r"(.)([A-Z][a-z]+)", r"\1_\2", candidate)
+    candidate = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", candidate)
+    slug = re.sub(r"[^a-zA-Z0-9]+", "_", candidate).lower()
+    slug = re.sub(r"_+", "_", slug).strip("_")
+    if not slug:
+        slug = "app"
+    if not slug[0].isalpha():
+        slug = f"app_{slug}"
+    return slug
+
+
+__all__ = [
+    "build_app_id",
+    "derive_default_local_app_slug",
+    "normalize_app_slug",
+    "resolve_project_dir",
+]

pz_core/authoring/official_dev_sources.py

@@ -0,0 +1,432 @@
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Literal
+from urllib.parse import urlparse
+
+from pz_core.project_sources import (
+    OfficialSourceRoot,
+    load_official_source_catalog,
+)
+from pz_core.runtime.errors import PzError
+
+from .dev_manifest import DevBinding, DevManifest
+from .project_state import load_dev_manifest, normalize_formal_app_id
+from .repo_keys import build_repo_key
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedSource:
+    locator: str
+    source_kind: Literal["git", "link"]
+    repo_key: str | None
+    clone_source: str
+    binding_kind: Literal["directory", "app"] | None
+    subpath: PurePosixPath
+    link_name: str
+    expected_app_id: str | None
+    pending_layout: bool = False
+    bootstrap: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class _LocatorLeaf:
+    app_id: str
+    package_root: Path
+
+
+def _source_unresolved(locator: object, reason: str, *, action: str) -> PzError:
+    return PzError(
+        code="PZ_DEV_SOURCE_UNRESOLVED",
+        message=f"could not resolve dev source locator {locator!r}: {reason}",
+        stage="dev",
+        owner="pz_core.authoring.official_dev_sources",
+        action=action,
+    )
+
+
+def _normalize_source_locator(locator: object, *, action: str) -> str:
+    if not isinstance(locator, str) or not locator.strip():
+        raise _source_unresolved(locator, "expected a non-empty string", action=action)
+    return locator.strip()
+
+
+def _resolved_official_root(locator: str, root: OfficialSourceRoot) -> ResolvedSource:
+    return ResolvedSource(
+        locator=locator,
+        source_kind="git",
+        repo_key=root.repo_key,
+        clone_source=root.source,
+        binding_kind="directory",
+        subpath=PurePosixPath("."),
+        link_name=root.repo_key,
+        expected_app_id=None,
+        pending_layout=False,
+        bootstrap=root.bootstrap,
+    )
+
+
+def _official_root_for_identity(identity: str) -> OfficialSourceRoot | None:
+    catalog = load_official_source_catalog()
+    direct = catalog.get(identity)
+    if direct is not None:
+        return direct
+    for root in catalog.values():
+        if identity == root.source:
+            return root
+    return None
+
+
+def _resolve_official_locator(locator: str) -> ResolvedSource | None:
+    catalog = load_official_source_catalog()
+    root = _official_root_for_identity(locator)
+    if root is not None:
+        return _resolved_official_root(locator, root)
+    for candidate in catalog.values():
+        child = next(
+            (
+                item
+                for key, item in candidate.children.items()
+                if locator in {key, item.expected_app_id}
+            ),
+            None,
+        )
+        if child is None or child.kind != "app":
+            continue
+        assert child.expected_app_id is not None
+        return ResolvedSource(
+            locator=locator,
+            source_kind="git",
+            repo_key=candidate.repo_key,
+            clone_source=candidate.source,
+            binding_kind="app",
+            subpath=child.subpath,
+            link_name=child.expected_app_id,
+            expected_app_id=child.expected_app_id,
+            pending_layout=False,
+            bootstrap=False,
+        )
+    return None
+
+
+def _resolved_manifest_repo(
+    locator: str,
+    *,
+    repo_key: str,
+    source: str,
+) -> ResolvedSource:
+    official = _official_root_for_identity(repo_key) or _official_root_for_identity(
+        source
+    )
+    return ResolvedSource(
+        locator=locator,
+        source_kind="git",
+        repo_key=repo_key,
+        clone_source=source,
+        binding_kind="directory",
+        subpath=PurePosixPath("."),
+        link_name=repo_key,
+        expected_app_id=None,
+        pending_layout=False,
+        bootstrap=False if official is None else official.bootstrap,
+    )
+
+
+def _resolved_manifest_binding(
+    locator: str,
+    *,
+    binding_key: str,
+    binding: DevBinding,
+    manifest: DevManifest,
+) -> ResolvedSource:
+    clone_source = binding.source
+    if binding.source_kind == "git":
+        assert binding.repo_key is not None
+        clone_source = manifest.repos[binding.repo_key].source
+    return ResolvedSource(
+        locator=locator,
+        source_kind=binding.source_kind,
+        repo_key=binding.repo_key,
+        clone_source=clone_source,
+        binding_kind=binding.kind,
+        subpath=binding.subpath,
+        link_name=binding.link.name,
+        expected_app_id=binding_key if binding.kind == "app" else None,
+        pending_layout=False,
+        bootstrap=False,
+    )
+
+
+def _locator_path_candidate(locator: str) -> Path | None:
+    candidate = Path(locator).expanduser()
+    try:
+        if candidate.exists():
+            return candidate.resolve()
+    except OSError:
+        return None
+    return None
+
+
+def _canonical_path_candidate(locator: str) -> Path | None:
+    candidate = Path(locator).expanduser()
+    if not (
+        candidate.is_absolute()
+        or locator.startswith((".", "~"))
+        or "/" in locator
+        or "\\" in locator
+    ):
+        return None
+    try:
+        return candidate.resolve(strict=False)
+    except OSError:
+        return None
+
+
+def _resolve_from_manifest(
+    locator: str,
+    *,
+    project_dir: Path,
+) -> ResolvedSource | None:
+    manifest = load_dev_manifest(project_dir)
+    if manifest is None:
+        return None
+    binding = manifest.bindings.get(locator)
+    if binding is not None:
+        return _resolved_manifest_binding(
+            locator,
+            binding_key=locator,
+            binding=binding,
+            manifest=manifest,
+        )
+    repo = manifest.repos.get(locator)
+    if repo is not None:
+        return _resolved_manifest_repo(
+            locator,
+            repo_key=locator,
+            source=repo.source,
+        )
+    for repo_key, candidate in manifest.repos.items():
+        if locator == candidate.source:
+            return _resolved_manifest_repo(
+                locator,
+                repo_key=repo_key,
+                source=candidate.source,
+            )
+    candidate_path = _canonical_path_candidate(locator)
+    if candidate_path is not None:
+        for repo_key, candidate in manifest.repos.items():
+            checkout = (project_dir / Path(*candidate.checkout.parts)).resolve(
+                strict=False
+            )
+            if candidate_path == checkout:
+                return _resolved_manifest_repo(
+                    locator,
+                    repo_key=repo_key,
+                    source=candidate.source,
+                )
+        for binding_key, candidate in manifest.bindings.items():
+            link = (project_dir / Path(*candidate.link.parts)).resolve(strict=False)
+            direct_source = (
+                Path(candidate.source).resolve(strict=False)
+                if candidate.source_kind == "link"
+                else None
+            )
+            if candidate_path in {link, direct_source}:
+                return _resolved_manifest_binding(
+                    locator,
+                    binding_key=binding_key,
+                    binding=candidate,
+                    manifest=manifest,
+                )
+    return None
+
+
+def _inspect_locator_leaf(package_root: Path) -> _LocatorLeaf | None:
+    pyproject_path = package_root / "pyproject.toml"
+    if not pyproject_path.is_file():
+        return None
+    try:
+        payload = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, tomllib.TOMLDecodeError):
+        return None
+    project = payload.get("project")
+    if not isinstance(project, dict):
+        return None
+    distribution = project.get("name")
+    if not isinstance(distribution, str) or not distribution.strip():
+        return None
+    app_id = distribution.strip().replace("-", "_")
+    try:
+        normalized = normalize_formal_app_id(app_id, action="resolve_source_locator")
+    except PzError:
+        return None
+    if normalized != app_id or not (package_root / app_id / "apps.py").is_file():
+        return None
+    return _LocatorLeaf(app_id=app_id, package_root=package_root.resolve())
+
+
+def _discover_locator_leaves(root: Path) -> tuple[_LocatorLeaf, ...]:
+    leaves: list[_LocatorLeaf] = []
+    for current, dirnames, _filenames in os.walk(root, followlinks=False):
+        dirnames[:] = sorted(name for name in dirnames if not name.startswith("."))
+        package_root = Path(current)
+        leaf = _inspect_locator_leaf(package_root)
+        if leaf is None:
+            continue
+        leaves.append(leaf)
+        dirnames.clear()
+    leaves.sort(key=lambda item: item.package_root.as_posix())
+    return tuple(leaves)
+
+
+def _locator_git_root(path: Path, *, action: str) -> Path | None:
+    if not any((candidate / ".git").exists() for candidate in (path, *path.parents)):
+        return None
+    argv = ("git", "-C", str(path), "rev-parse", "--show-toplevel")
+    try:
+        completed = subprocess.run(
+            argv,
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except OSError as exc:
+        raise PzError(
+            code="PZ_DEV_GIT_UNAVAILABLE",
+            message="git is required to classify a local source path.",
+            stage="dev",
+            owner="pz_core.authoring.official_dev_sources",
+            action=action,
+        ) from exc
+    if completed.returncode != 0:
+        return None
+    top_level = (completed.stdout or "").strip()
+    if not top_level:
+        return None
+    candidate = Path(top_level).expanduser().resolve()
+    return candidate if candidate.is_dir() else None
+
+
+def _normalized_repo_key(identity: str) -> str:
+    candidate = build_repo_key(identity).lower().replace("-", "_")
+    candidate = re.sub(r"[^a-z0-9_]+", "_", candidate).strip("_")
+    if not candidate:
+        return "repo"
+    if not candidate[0].isalpha():
+        return f"repo_{candidate}"
+    return candidate
+
+
+def _resolved_local_path(
+    locator: str,
+    path: Path,
+    *,
+    action: str,
+) -> ResolvedSource:
+    if not path.is_dir():
+        raise _source_unresolved(
+            locator, "local source must be a directory", action=action
+        )
+    leaves = _discover_locator_leaves(path)
+    if not leaves:
+        raise _source_unresolved(
+            locator,
+            "local source contains no formal minimal app",
+            action=action,
+        )
+    git_root = _locator_git_root(path, action=action)
+    source_kind: Literal["git", "link"] = "git" if git_root is not None else "link"
+    source_root = path if git_root is None else git_root
+    repo_key = None if git_root is None else _normalized_repo_key(str(git_root))
+    if len(leaves) == 1:
+        leaf = leaves[0]
+        return ResolvedSource(
+            locator=locator,
+            source_kind=source_kind,
+            repo_key=repo_key,
+            clone_source=str(source_root),
+            binding_kind="app",
+            subpath=PurePosixPath(
+                leaf.package_root.relative_to(source_root).as_posix()
+            ),
+            link_name=leaf.app_id,
+            expected_app_id=leaf.app_id,
+            pending_layout=False,
+            bootstrap=False,
+        )
+    directory_subpath = (
+        PurePosixPath(".")
+        if git_root is None or path == git_root
+        else PurePosixPath(path.relative_to(git_root).as_posix())
+    )
+    return ResolvedSource(
+        locator=locator,
+        source_kind=source_kind,
+        repo_key=repo_key,
+        clone_source=str(source_root),
+        binding_kind="directory",
+        subpath=directory_subpath,
+        link_name=_normalized_repo_key(path.name),
+        expected_app_id=None,
+        pending_layout=False,
+        bootstrap=False,
+    )
+
+
+def _is_explicit_git_url(locator: str) -> bool:
+    parsed = urlparse(locator)
+    if parsed.scheme in {"file", "git", "http", "https", "ssh"}:
+        return True
+    return bool(re.match(r"^[^\s/@]+@[^\s:]+:.+$", locator))
+
+
+def _resolved_pending_remote(locator: str) -> ResolvedSource:
+    repo_key = _normalized_repo_key(locator)
+    return ResolvedSource(
+        locator=locator,
+        source_kind="git",
+        repo_key=repo_key,
+        clone_source=locator,
+        binding_kind=None,
+        subpath=PurePosixPath("."),
+        link_name=repo_key,
+        expected_app_id=None,
+        pending_layout=True,
+        bootstrap=False,
+    )
+
+
+def resolve_source_locator(
+    locator: object,
+    *,
+    project_dir: Path,
+    action: str = "resolve_source_locator",
+) -> ResolvedSource:
+    normalized = _normalize_source_locator(locator, action=action)
+    existing = _resolve_from_manifest(normalized, project_dir=project_dir)
+    if existing is not None:
+        return existing
+    local_path = _locator_path_candidate(normalized)
+    if local_path is not None:
+        return _resolved_local_path(normalized, local_path, action=action)
+    if _is_explicit_git_url(normalized):
+        official = _resolve_official_locator(normalized)
+        return (
+            official if official is not None else _resolved_pending_remote(normalized)
+        )
+    official = _resolve_official_locator(normalized)
+    if official is not None:
+        return official
+    raise _source_unresolved(
+        normalized,
+        "use an existing manifest identity, local path, explicit Git URL, or official source name",
+        action=action,
+    )
+
+
+__all__ = ["ResolvedSource", "resolve_source_locator"]

pz_core/authoring/official_sources.json

@@ -0,0 +1,156 @@
+{
+  "pz": {
+    "source": "git@github.com:JiXiangTools/pyzza.git",
+    "kind": "directory",
+    "bootstrap": true,
+    "children": {
+      "pz-cli": {
+        "kind": "project",
+        "subpath": ".",
+        "expected_app_id": null
+      },
+      "pz-settings-center": {
+        "kind": "app",
+        "subpath": "pz_contrib/pz_settings_center",
+        "expected_app_id": "pz_settings_center"
+      },
+      "pz-foundation": {
+        "kind": "app",
+        "subpath": "pz_contrib/pz_foundation",
+        "expected_app_id": "pz_foundation"
+      }
+    }
+  },
+  "pz_apps": {
+    "source": "git@github.com:JiXiangTools/pyzza_platform.git",
+    "kind": "directory",
+    "bootstrap": false,
+    "children": {
+      "pz_account": {
+        "kind": "app",
+        "subpath": "pz_account",
+        "expected_app_id": "pz_account"
+      },
+      "pz_admin": {
+        "kind": "app",
+        "subpath": "pz_admin",
+        "expected_app_id": "pz_admin"
+      },
+      "pz_api_access": {
+        "kind": "app",
+        "subpath": "pz_api_access",
+        "expected_app_id": "pz_api_access"
+      },
+      "pz_auth": {
+        "kind": "app",
+        "subpath": "pz_auth",
+        "expected_app_id": "pz_auth"
+      },
+      "pz_packaging": {
+        "kind": "app",
+        "subpath": "pz_packaging",
+        "expected_app_id": "pz_packaging"
+      },
+      "pz_page_center": {
+        "kind": "app",
+        "subpath": "pz_page_center",
+        "expected_app_id": "pz_page_center"
+      },
+      "pz_preflight": {
+        "kind": "app",
+        "subpath": "pz_preflight",
+        "expected_app_id": "pz_preflight"
+      },
+      "pz_redirects": {
+        "kind": "app",
+        "subpath": "pz_redirects",
+        "expected_app_id": "pz_redirects"
+      },
+      "pz_risk_control": {
+        "kind": "app",
+        "subpath": "pz_risk_control",
+        "expected_app_id": "pz_risk_control"
+      },
+      "pz_seo": {
+        "kind": "app",
+        "subpath": "pz_seo",
+        "expected_app_id": "pz_seo"
+      },
+      "pz_settings_operator": {
+        "kind": "app",
+        "subpath": "pz_settings_operator",
+        "expected_app_id": "pz_settings_operator"
+      },
+      "pz_site_ui": {
+        "kind": "app",
+        "subpath": "pz_site_ui",
+        "expected_app_id": "pz_site_ui"
+      },
+      "pz_asset_service": {
+        "kind": "app",
+        "subpath": "pz_asset_service",
+        "expected_app_id": "pz_asset_service"
+      },
+      "pz_billing_and_credits": {
+        "kind": "app",
+        "subpath": "pz_billing_and_credits",
+        "expected_app_id": "pz_billing_and_credits"
+      },
+      "pz_file_service": {
+        "kind": "app",
+        "subpath": "pz_file_service",
+        "expected_app_id": "pz_file_service"
+      },
+      "pz_llms": {
+        "kind": "app",
+        "subpath": "pz_llms",
+        "expected_app_id": "pz_llms"
+      },
+      "pz_lottery": {
+        "kind": "app",
+        "subpath": "pz_lottery",
+        "expected_app_id": "pz_lottery"
+      },
+      "pz_proxies": {
+        "kind": "app",
+        "subpath": "pz_proxies",
+        "expected_app_id": "pz_proxies"
+      },
+      "pz_task_center": {
+        "kind": "app",
+        "subpath": "pz_task_center",
+        "expected_app_id": "pz_task_center"
+      },
+      "pz_blog": {
+        "kind": "app",
+        "subpath": "pz_blog",
+        "expected_app_id": "pz_blog"
+      },
+      "pz_cms": {
+        "kind": "app",
+        "subpath": "pz_cms",
+        "expected_app_id": "pz_cms"
+      },
+      "pz_pwa": {
+        "kind": "app",
+        "subpath": "pz_pwa",
+        "expected_app_id": "pz_pwa"
+      },
+      "pz_site_crawler": {
+        "kind": "app",
+        "subpath": "pz_site_crawler",
+        "expected_app_id": "pz_site_crawler"
+      },
+      "pz_site_essentials": {
+        "kind": "app",
+        "subpath": "pz_site_essentials",
+        "expected_app_id": "pz_site_essentials"
+      },
+      "pz_site_media": {
+        "kind": "app",
+        "subpath": "pz_site_media",
+        "expected_app_id": "pz_site_media"
+      }
+    }
+  }
+}