pz-cli 5.0.0__py3-none-any.whl

pz_core/authoring/release.py

@@ -0,0 +1,1382 @@
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass
+from email.parser import BytesParser
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import tempfile
+import tomllib
+import zipfile
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+from urllib.parse import quote, urlsplit, urlunsplit
+
+from pz_core.runtime.errors import PzError
+from pz_core.utils import load_jsonc_file
+
+from .publish_lock import enforce_publish_lock
+from .publish_git import (
+    PublishCommitResult,
+    PublishTagResult,
+    commit_publish_app,
+    preflight_publish_app,
+    require_publish_checkout_at_tag,
+    require_publish_tag,
+    tag_publish_app,
+)
+from .publish_source import resolve_publish_source
+from .project_state import normalize_formal_app_id, resolve_project_config_path
+from .workspace import resolve_workspace_package
+
+
+@dataclass(frozen=True, slots=True)
+class PublishTarget:
+    name: str
+    index: str | None = None
+    publish_url: str | None = None
+    check_url: str | None = None
+    trusted_publishing: str | None = None
+    token_env: str | None = None
+    username_env: str | None = None
+    password_env: str | None = None
+    install_username_env: str | None = None
+    install_password_env: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class InstallTarget:
+    name: str
+    index_url: str | None = None
+    username_env: str | None = None
+    password_env: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class PublishResult:
+    app_id: str
+    version: str
+    package_root: Path
+    dist_dir: Path
+    target: PublishTarget
+    dry_run: bool
+    commit: str | None = None
+    tag: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class UnpublishResult:
+    app_id: str
+    distribution_name: str
+    version: str
+    package_root: Path
+    target: PublishTarget
+    project_url: str
+    removed_versions: tuple[str, ...]
+    dry_run: bool
+    force: bool
+
+
+def normalize_publish_app_id(
+    project_dir: Path,
+    app_id: str,
+    *,
+    action: str,
+) -> str:
+    del project_dir
+    workspace_package = resolve_workspace_package(str(app_id))
+    if workspace_package is not None:
+        return workspace_package.app_id
+    if not isinstance(app_id, str) or not app_id.strip():
+        raise PzError(
+            code="PZ_PUBLISH_APP_ID_INVALID",
+            message="publish app id must be a non-empty string.",
+            stage="cli",
+            owner="pz_core.authoring.release",
+            action=action,
+        )
+    return normalize_formal_app_id(
+        app_id.strip().replace("-", "_"),
+        action=action,
+    )
+
+
+def resolve_publish_package_root(
+    project_dir: Path,
+    app_id: str,
+    *,
+    action: str,
+) -> Path:
+    normalized_app_id = normalize_publish_app_id(
+        project_dir,
+        app_id,
+        action=action,
+    )
+    workspace_package = resolve_workspace_package(normalized_app_id)
+    if workspace_package is not None and workspace_package.repo.is_dir():
+        return workspace_package.repo.resolve()
+
+    from pz_core.assembly.app_discovery import iter_visible_app_projections
+
+    for projection in iter_visible_app_projections(project_dir):
+        if projection.app_id == normalized_app_id:
+            return projection.source_root
+
+    requested_distribution = normalized_app_id.replace("_", "-")
+    if _read_project_distribution_name(project_dir) == requested_distribution:
+        return project_dir.resolve()
+    raise PzError(
+        code="PZ_PUBLISH_SOURCE_MISSING",
+        message=f"could not resolve package root for {normalized_app_id}.",
+        stage="cli",
+        owner="pz_core.authoring.release",
+        action=action,
+    )
+
+
+def _read_project_distribution_name(package_root: Path) -> str | None:
+    pyproject = package_root / "pyproject.toml"
+    if not pyproject.is_file():
+        return None
+    try:
+        payload = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, tomllib.TOMLDecodeError):
+        return None
+    project = payload.get("project")
+    if not isinstance(project, dict):
+        return None
+    name = project.get("name")
+    return name.strip() if isinstance(name, str) and name.strip() else None
+
+
+def _read_dotenv(path: Path, *, action: str) -> dict[str, str]:
+    values: dict[str, str] = {}
+    if not path.is_file():
+        return values
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except Exception as exc:
+        raise PzError(
+            code="PZ_SCAFFOLD_DOTENV_INVALID",
+            message=f"failed to read env file: {path}",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    for line_number, raw_line in enumerate(lines, start=1):
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in raw_line:
+            raise PzError(
+                code="PZ_SCAFFOLD_DOTENV_INVALID",
+                message=f"invalid env entry at line {line_number}: missing '=' delimiter.",
+                stage="cli",
+                owner="pz_core.authoring",
+                action=action,
+                detail=str(path),
+            )
+        key, raw_value = raw_line.split("=", 1)
+        normalized_key = key.strip()
+        if not normalized_key:
+            raise PzError(
+                code="PZ_SCAFFOLD_DOTENV_INVALID",
+                message=f"invalid env entry at line {line_number}: key must be non-empty.",
+                stage="cli",
+                owner="pz_core.authoring",
+                action=action,
+                detail=str(path),
+            )
+        value = raw_value.strip()
+        if value[:1] in {"'", '"'}:
+            quote_char = value[0]
+            if len(value) < 2 or not value.endswith(quote_char):
+                raise PzError(
+                    code="PZ_SCAFFOLD_DOTENV_INVALID",
+                    message=f"invalid env entry at line {line_number}: unterminated quoted value.",
+                    stage="cli",
+                    owner="pz_core.authoring",
+                    action=action,
+                    detail=str(path),
+                )
+            value = value[1:-1]
+        values[normalized_key] = value
+    return values
+
+
+def build_authoring_env(*roots: Path, action: str) -> dict[str, str]:
+    env = dict(os.environ)
+    seen: set[Path] = set()
+    for root in roots:
+        candidate_root = Path(root).expanduser().resolve()
+        if candidate_root in seen:
+            continue
+        seen.add(candidate_root)
+        for key, value in _read_dotenv(candidate_root / ".env", action=action).items():
+            env.setdefault(key, value)
+    return env
+
+
+def _is_devpi_target(target: PublishTarget, *urls: str | None) -> bool:
+    target_name = str(target.name or "").strip().lower()
+    if target_name.startswith("devpi_") or target_name == "devpi":
+        return True
+    for url in urls:
+        if not isinstance(url, str) or not url.strip():
+            continue
+        path = str(urlsplit(url.strip()).path or "").strip().lower()
+        if path.endswith("/+simple/") or path.endswith("/+simple"):
+            return True
+    return False
+
+
+def _inject_basic_auth(url: str, *, username: str, password: str) -> str:
+    parsed = urlsplit(url)
+    hostname = str(parsed.hostname or "").strip()
+    if not hostname:
+        return url
+    userinfo = f"{quote(username, safe='')}:{quote(password, safe='')}"
+    netloc = f"{userinfo}@{hostname}"
+    if parsed.port is not None:
+        netloc += f":{parsed.port}"
+    return urlunsplit(
+        (parsed.scheme, netloc, parsed.path, parsed.query, parsed.fragment)
+    )
+
+
+def _require_named_env(
+    env: dict[str, str], env_name: str, *, code: str, message: str, action: str
+) -> str:
+    value = str(env.get(env_name) or "").strip()
+    if value:
+        return value
+    raise PzError(
+        code=code,
+        message=message,
+        stage="cli",
+        owner="pz_core.authoring",
+        action=action,
+    )
+
+
+def _clean_build_artifacts(package_root: Path) -> None:
+    for relative_path in ("build", "dist"):
+        candidate = package_root / relative_path
+        if candidate.exists():
+            shutil.rmtree(candidate)
+    for candidate in package_root.glob("*.egg-info"):
+        if candidate.is_dir():
+            shutil.rmtree(candidate)
+        elif candidate.exists():
+            candidate.unlink()
+
+
+def _validate_optional_string(
+    raw_value: object, *, field: str, action: str
+) -> str | None:
+    if raw_value is None:
+        return None
+    if not isinstance(raw_value, str) or not raw_value.strip():
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_CONFIG_INVALID",
+            message=f"publish config field `{field}` must be a non-empty string when provided.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    return raw_value.strip()
+
+
+def _load_project_payload(project_dir: Path, *, action: str) -> dict[str, object]:
+    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,
+        )
+    payload = load_jsonc_file(
+        resolve_project_config_path(project_dir),
+        code="PZ_SCAFFOLD_PROJECT_CONFIG_INVALID",
+        owner="pz_core.authoring",
+        action=action,
+    )
+    if payload and not isinstance(payload, dict):
+        raise PzError(
+            code="PZ_SCAFFOLD_PROJECT_CONFIG_INVALID",
+            message="project config must decode to an object.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    return payload or {}
+
+
+def _load_source_root_pyproject_payload(
+    source_root: Path, *, action: str
+) -> dict[str, object]:
+    pyproject_path = source_root / "pyproject.toml"
+    if not pyproject_path.is_file():
+        return {}
+    try:
+        payload = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_CONFIG_INVALID",
+            message=f"source-root pyproject.toml is unreadable: {pyproject_path}",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    if not isinstance(payload, dict):
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_CONFIG_INVALID",
+            message=f"source-root pyproject.toml must decode to an object: {pyproject_path}",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    return payload
+
+
+def _resolve_pyproject_publish_config(
+    source_root: Path,
+    *,
+    action: str,
+) -> tuple[dict[str, object] | None, str, str]:
+    pyproject_path = source_root / "pyproject.toml"
+    pyproject_payload = _load_source_root_pyproject_payload(source_root, action=action)
+    if not pyproject_path.is_file():
+        return None, str(pyproject_path), "tool.pz.publish"
+    tool = pyproject_payload.get("tool")
+    if tool is None:
+        return None, str(pyproject_path), "tool.pz.publish"
+    if not isinstance(tool, dict):
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_CONFIG_INVALID",
+            message="`tool` in source-root pyproject.toml must be an object.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    pz_tool = tool.get("pz")
+    if pz_tool is None:
+        return None, str(pyproject_path), "tool.pz.publish"
+    if not isinstance(pz_tool, dict):
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_CONFIG_INVALID",
+            message="`tool.pz` in source-root pyproject.toml must be an object.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    return pz_tool.get("publish"), str(pyproject_path), "tool.pz.publish"
+
+
+def _resolve_publish_config(
+    project_dir: Path,
+    *,
+    package_root: Path | None = None,
+    workspace_package_root: Path | None = None,
+    action: str,
+) -> tuple[dict[str, object] | None, str, str]:
+    project_config_path = resolve_project_config_path(project_dir)
+    if project_config_path.is_file():
+        payload = _load_project_payload(project_dir, action=action)
+        publish_config = payload.get("publish")
+        if publish_config is not None:
+            if not isinstance(publish_config, dict):
+                raise PzError(
+                    code="PZ_SCAFFOLD_PUBLISH_CONFIG_INVALID",
+                    message="`publish` in project config must be an object.",
+                    stage="cli",
+                    owner="pz_core.authoring",
+                    action=action,
+                )
+            return publish_config, str(project_config_path), "publish"
+    seen: set[Path] = set()
+    for search_root in (package_root, workspace_package_root):
+        if search_root is None:
+            continue
+        for candidate in (search_root, *search_root.parents):
+            resolved_candidate = candidate.resolve()
+            if resolved_candidate in seen:
+                continue
+            seen.add(resolved_candidate)
+            publish_config, config_label, field_prefix = (
+                _resolve_pyproject_publish_config(
+                    resolved_candidate,
+                    action=action,
+                )
+            )
+            if publish_config is not None:
+                return publish_config, config_label, field_prefix
+    publish_config, config_label, field_prefix = _resolve_pyproject_publish_config(
+        project_dir, action=action
+    )
+    if publish_config is not None:
+        return publish_config, config_label, field_prefix
+    return None, str(project_config_path), "publish"
+
+
+def _load_publish_target(
+    project_dir: Path,
+    *,
+    package_root: Path | None = None,
+    workspace_package_root: Path | None = None,
+    target_name: str | None,
+    action: str,
+) -> PublishTarget:
+    publish_config, config_label, field_prefix = _resolve_publish_config(
+        project_dir,
+        package_root=package_root,
+        workspace_package_root=workspace_package_root,
+        action=action,
+    )
+    target = (
+        target_name.strip()
+        if isinstance(target_name, str) and target_name.strip()
+        else None
+    )
+    if publish_config is None:
+        return PublishTarget(name=target or "default")
+    if not isinstance(publish_config, dict):
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_CONFIG_INVALID",
+            message=f"`{field_prefix}` must be an object.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    default_target = _validate_optional_string(
+        publish_config.get("default_target"),
+        field=f"{field_prefix}.default_target",
+        action=action,
+    )
+    resolved_target_name = target or default_target or "default"
+    raw_targets = publish_config.get("targets")
+    if raw_targets is None:
+        return PublishTarget(name=resolved_target_name)
+    if not isinstance(raw_targets, dict):
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_CONFIG_INVALID",
+            message=f"`{field_prefix}.targets` must be an object.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    raw_target = raw_targets.get(resolved_target_name)
+    if raw_target is None:
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_TARGET_UNKNOWN",
+            message=(
+                f"publish target `{resolved_target_name}` is not defined in "
+                f"{config_label}."
+            ),
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    if not isinstance(raw_target, dict):
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_CONFIG_INVALID",
+            message=f"`{field_prefix}.targets.{resolved_target_name}` must be an object.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    return PublishTarget(
+        name=resolved_target_name,
+        index=_validate_optional_string(
+            raw_target.get("index"),
+            field=f"{field_prefix}.targets.{resolved_target_name}.index",
+            action=action,
+        ),
+        publish_url=_validate_optional_string(
+            raw_target.get("publish_url"),
+            field=f"{field_prefix}.targets.{resolved_target_name}.publish_url",
+            action=action,
+        ),
+        check_url=_validate_optional_string(
+            raw_target.get("check_url"),
+            field=f"{field_prefix}.targets.{resolved_target_name}.check_url",
+            action=action,
+        ),
+        trusted_publishing=_validate_optional_string(
+            raw_target.get("trusted_publishing"),
+            field=f"{field_prefix}.targets.{resolved_target_name}.trusted_publishing",
+            action=action,
+        ),
+        token_env=_validate_optional_string(
+            raw_target.get("token_env"),
+            field=f"{field_prefix}.targets.{resolved_target_name}.token_env",
+            action=action,
+        ),
+        username_env=_validate_optional_string(
+            raw_target.get("username_env"),
+            field=f"{field_prefix}.targets.{resolved_target_name}.username_env",
+            action=action,
+        ),
+        password_env=_validate_optional_string(
+            raw_target.get("password_env"),
+            field=f"{field_prefix}.targets.{resolved_target_name}.password_env",
+            action=action,
+        ),
+        install_username_env=_validate_optional_string(
+            raw_target.get("install_username_env"),
+            field=f"{field_prefix}.targets.{resolved_target_name}.install_username_env",
+            action=action,
+        ),
+        install_password_env=_validate_optional_string(
+            raw_target.get("install_password_env"),
+            field=f"{field_prefix}.targets.{resolved_target_name}.install_password_env",
+            action=action,
+        ),
+    )
+
+
+def load_install_target(
+    app_id: str, *, project_dir: Path, action: str
+) -> InstallTarget:
+    workspace_package = resolve_workspace_package(str(app_id), anchors=(project_dir,))
+    package_root = workspace_package.repo if workspace_package is not None else None
+    return load_install_target_for_package_root(
+        package_root, project_dir=project_dir, action=action
+    )
+
+
+def load_install_target_for_package_root(
+    package_root: Path | None,
+    *,
+    project_dir: Path,
+    target_name: str | None = None,
+    action: str,
+) -> InstallTarget:
+    target = _load_publish_target(
+        project_dir,
+        package_root=package_root,
+        workspace_package_root=package_root,
+        target_name=target_name,
+        action=action,
+    )
+    index_url = target.check_url or target.index
+    username_env = target.install_username_env
+    password_env = target.install_password_env
+    if index_url and _is_devpi_target(
+        target, index_url, target.check_url, target.publish_url
+    ):
+        username_env = username_env or "DEVPI_INSTALL_USER"
+        password_env = password_env or "DEVPI_INSTALL_PASSWORD"
+    return InstallTarget(
+        name=target.name,
+        index_url=index_url,
+        username_env=username_env,
+        password_env=password_env,
+    )
+
+
+def install_env(
+    *, target: InstallTarget, project_dir: Path, action: str
+) -> dict[str, str]:
+    return install_env_for_targets((target,), project_dir=project_dir, action=action)
+
+
+def install_env_for_targets(
+    targets: tuple[InstallTarget, ...],
+    *,
+    project_dir: Path,
+    action: str,
+) -> dict[str, str]:
+    env = build_authoring_env(project_dir, action=action)
+    index_urls = tuple(
+        _install_index_url(target=target, env=env, action=action)
+        for target in targets
+        if target.index_url is not None
+    )
+    if not index_urls:
+        return env
+    if len(index_urls) == 1:
+        env["UV_DEFAULT_INDEX"] = index_urls[0]
+        return env
+    env["UV_INDEX"] = " ".join(index_urls[:-1])
+    env["UV_DEFAULT_INDEX"] = index_urls[-1]
+    return env
+
+
+def _install_index_url(
+    *, target: InstallTarget, env: dict[str, str], action: str
+) -> str:
+    index_url = str(target.index_url or "").strip()
+    if target.username_env is not None or target.password_env is not None:
+        if target.username_env is None or target.password_env is None:
+            raise PzError(
+                code="PZ_SCAFFOLD_INSTALL_TARGET_INVALID",
+                message=f"install target `{target.name}` must declare both install username and password env vars.",
+                stage="cli",
+                owner="pz_core.authoring",
+                action=action,
+            )
+        username = _require_named_env(
+            env,
+            target.username_env,
+            code="PZ_SCAFFOLD_INSTALL_AUTH_MISSING",
+            message=f"install target `{target.name}` requires env var `{target.username_env}`.",
+            action=action,
+        )
+        password = _require_named_env(
+            env,
+            target.password_env,
+            code="PZ_SCAFFOLD_INSTALL_AUTH_MISSING",
+            message=f"install target `{target.name}` requires env var `{target.password_env}`.",
+            action=action,
+        )
+        index_url = _inject_basic_auth(index_url, username=username, password=password)
+    return index_url
+
+
+def _publish_env(
+    *, target: PublishTarget, project_dir: Path, action: str
+) -> dict[str, str]:
+    env = build_authoring_env(project_dir, action=action)
+    for source_name, destination_name in (
+        (target.token_env, "UV_PUBLISH_TOKEN"),
+        (target.username_env, "UV_PUBLISH_USERNAME"),
+        (target.password_env, "UV_PUBLISH_PASSWORD"),
+    ):
+        if source_name is None:
+            continue
+        env[destination_name] = _require_named_env(
+            env,
+            source_name,
+            code="PZ_SCAFFOLD_PUBLISH_AUTH_MISSING",
+            message=f"publish target `{target.name}` requires env var `{source_name}`.",
+            action=action,
+        )
+    return env
+
+
+def _publish_argv(
+    *, uv_binary: str, target: PublishTarget, dist_dir: Path, dry_run: bool
+) -> list[str]:
+    argv = [uv_binary, "publish"]
+    if target.index:
+        argv.extend(["--index", target.index])
+    if target.publish_url:
+        argv.extend(["--publish-url", target.publish_url])
+    if target.check_url:
+        argv.extend(["--check-url", target.check_url])
+    if target.trusted_publishing:
+        argv.extend(["--trusted-publishing", target.trusted_publishing])
+    if dry_run:
+        argv.append("--dry-run")
+    argv.append(str(dist_dir / "*"))
+    return argv
+
+
+def _run_uv(argv: list[str], *, cwd: Path, env: dict[str, str], action: str) -> None:
+    completed = subprocess.run(
+        argv,
+        cwd=str(cwd),
+        env=env,
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    if completed.returncode == 0:
+        return
+    detail = (
+        completed.stderr or completed.stdout or "dependency backend command failed"
+    ).strip()
+    if len(argv) > 1 and argv[1] == "build":
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_BUILD_FAILED",
+            message="publish failed while building release artifacts.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+            detail=detail,
+        )
+    raise PzError(
+        code="PZ_SCAFFOLD_PUBLISH_UPLOAD_FAILED",
+        message="publish failed while uploading release artifacts.",
+        stage="cli",
+        owner="pz_core.authoring",
+        action=action,
+        detail=detail,
+    )
+
+
+def _read_project_version(package_root: Path, *, action: str) -> str:
+    pyproject_path = package_root / "pyproject.toml"
+    if not pyproject_path.is_file():
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_LAYOUT_INVALID",
+            message=f"package root is missing pyproject.toml: {package_root}",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    try:
+        payload = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_LAYOUT_INVALID",
+            message=f"package root has an unreadable pyproject.toml: {pyproject_path}",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    project = payload.get("project")
+    if not isinstance(project, dict):
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_LAYOUT_INVALID",
+            message=f"package root is missing [project] metadata: {pyproject_path}",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    version = project.get("version")
+    if not isinstance(version, str) or not version.strip():
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_VERSION_MISSING",
+            message="publish requires an explicit project.version before building release artifacts.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    return version.strip()
+
+
+def _read_project_name(package_root: Path, *, action: str) -> str:
+    pyproject_path = package_root / "pyproject.toml"
+    if not pyproject_path.is_file():
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_LAYOUT_INVALID",
+            message=f"package root is missing pyproject.toml: {package_root}",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    try:
+        payload = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_LAYOUT_INVALID",
+            message=f"package root has an unreadable pyproject.toml: {pyproject_path}",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    project = payload.get("project")
+    if not isinstance(project, dict):
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_LAYOUT_INVALID",
+            message=f"package root is missing [project] metadata: {pyproject_path}",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    name = project.get("name")
+    if not isinstance(name, str) or not name.strip():
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_LAYOUT_INVALID",
+            message="publish/unpublish requires an explicit project.name.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    return name.strip()
+
+
+def _derive_devpi_index_url(target: PublishTarget, *, action: str) -> str:
+    if isinstance(target.publish_url, str) and target.publish_url.strip():
+        return target.publish_url.strip()
+    if isinstance(target.index, str) and target.index.strip():
+        return target.index.strip()
+    check_url = str(target.check_url or "").strip()
+    if check_url.endswith("/+simple/"):
+        return check_url[: -len("/+simple/")] + "/"
+    if check_url.endswith("/+simple"):
+        return check_url[: -len("/+simple")] + "/"
+    raise PzError(
+        code="PZ_SCAFFOLD_UNPUBLISH_TARGET_INVALID",
+        message=(
+            f"publish target `{target.name}` must define `publish_url`, `index`, "
+            "or a devpi `check_url` to support unpublish."
+        ),
+        stage="cli",
+        owner="pz_core.authoring",
+        action=action,
+    )
+
+
+def _build_basic_auth_header(*, username: str, password: str) -> str:
+    token = base64.b64encode(f"{username}:{password}".encode("utf-8")).decode("ascii")
+    return f"Basic {token}"
+
+
+def _add_empty_query_flag(url: str, name: str) -> str:
+    parsed = urlsplit(url)
+    query = parsed.query
+    query = f"{query}&{name}=" if query else f"{name}="
+    return urlunsplit(
+        (parsed.scheme, parsed.netloc, parsed.path, query, parsed.fragment)
+    )
+
+
+def _devpi_request_json(
+    url: str,
+    *,
+    method: str,
+    username: str,
+    password: str,
+    action: str,
+) -> dict[str, object]:
+    headers = {
+        "Accept": "application/json",
+        "content-type": "application/json",
+        "Authorization": _build_basic_auth_header(username=username, password=password),
+    }
+    request = Request(url, method=method.upper(), headers=headers)
+    try:
+        with urlopen(request) as response:
+            raw = response.read().decode("utf-8")
+    except HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="ignore").strip()
+        if exc.code == 404:
+            raise PzError(
+                code="PZ_SCAFFOLD_UNPUBLISH_NOT_FOUND",
+                message="publish target does not contain the requested package.",
+                stage="cli",
+                owner="pz_core.authoring",
+                action=action,
+                detail=detail or url,
+            ) from exc
+        raise PzError(
+            code="PZ_SCAFFOLD_UNPUBLISH_REQUEST_FAILED",
+            message="unpublish request failed.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+            detail=detail or f"HTTP {exc.code} {exc.reason}",
+        ) from exc
+    except URLError as exc:
+        raise PzError(
+            code="PZ_SCAFFOLD_UNPUBLISH_REQUEST_FAILED",
+            message="unpublish request failed.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+            detail=str(exc.reason),
+        ) from exc
+    if not raw.strip():
+        return {}
+    try:
+        payload = json.loads(raw)
+    except Exception as exc:
+        raise PzError(
+            code="PZ_SCAFFOLD_UNPUBLISH_RESPONSE_INVALID",
+            message="unpublish target returned a non-JSON response.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+            detail=raw[:500],
+        ) from exc
+    if not isinstance(payload, dict):
+        raise PzError(
+            code="PZ_SCAFFOLD_UNPUBLISH_RESPONSE_INVALID",
+            message="unpublish target returned an invalid JSON payload.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    return payload
+
+
+def _extract_devpi_versions_for_project(
+    payload: dict[str, object], *, index_url: str, action: str
+) -> tuple[str, ...]:
+    result = payload.get("result")
+    if not isinstance(result, dict):
+        raise PzError(
+            code="PZ_SCAFFOLD_UNPUBLISH_RESPONSE_INVALID",
+            message="unpublish target did not return a projectconfig object.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    index_prefix = index_url.rstrip("/")
+    versions: list[str] = []
+    for version, metadata in result.items():
+        if not isinstance(version, str) or not isinstance(metadata, dict):
+            continue
+        links = metadata.get("+links")
+        if not isinstance(links, list):
+            continue
+        if any(
+            isinstance(link, dict)
+            and isinstance(link.get("href"), str)
+            and str(link.get("href")).startswith(index_prefix)
+            for link in links
+        ):
+            versions.append(version)
+    return tuple(sorted(versions))
+
+
+def _build_and_publish_package(
+    *,
+    app_id: str,
+    project_dir: Path,
+    package_root: Path,
+    workspace_package_root: Path | None,
+    target_name: str | None,
+    dry_run: bool,
+    action: str,
+    commit: str | None = None,
+    tag: str | None = None,
+) -> PublishResult:
+    version = _read_project_version(package_root, action=action)
+    distribution_name = _read_project_name(package_root, action=action)
+    target = _load_publish_target(
+        project_dir,
+        package_root=package_root,
+        workspace_package_root=workspace_package_root,
+        target_name=target_name,
+        action=action,
+    )
+    enforce_publish_lock(
+        project_dir=project_dir,
+        app_id=app_id,
+        distribution_name=distribution_name,
+        target=target,
+        action=action,
+    )
+    uv_binary = shutil.which("uv")
+    if not uv_binary:
+        raise PzError(
+            code="PZ_SCAFFOLD_PUBLISH_UV_MISSING",
+            message="required publish backend was not found on PATH.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    env = _publish_env(target=target, project_dir=project_dir, action=action)
+    _clean_build_artifacts(package_root)
+    _run_uv([uv_binary, "build"], cwd=package_root, env=env, action=action)
+    _validate_and_smoke_wheel(
+        app_id=app_id,
+        distribution_name=distribution_name,
+        version=version,
+        dist_dir=package_root / "dist",
+        uv_binary=uv_binary,
+        env=env,
+        action=action,
+    )
+    _run_uv(
+        _publish_argv(
+            uv_binary=uv_binary,
+            target=target,
+            dist_dir=package_root / "dist",
+            dry_run=dry_run,
+        ),
+        cwd=package_root,
+        env=env,
+        action=action,
+    )
+    return PublishResult(
+        app_id=app_id,
+        version=version,
+        package_root=package_root,
+        dist_dir=package_root / "dist",
+        target=target,
+        dry_run=dry_run,
+        commit=commit,
+        tag=tag,
+    )
+
+
+def _normalized_distribution(value: str) -> str:
+    return re.sub(r"[-_.]+", "-", value).lower()
+
+
+def _wheel_import_roots(names: tuple[str, ...] | list[str]) -> tuple[str, ...]:
+    roots: set[str] = set()
+    for name in names:
+        parts = name.split("/")
+        if len(parts) >= 2 and parts[1] == "__init__.py":
+            candidate = parts[0]
+        elif len(parts) == 1 and name.endswith(".py"):
+            candidate = name[:-3]
+        else:
+            continue
+        if candidate.isidentifier():
+            roots.add(candidate)
+    return tuple(sorted(roots))
+
+
+def _validate_and_smoke_wheel(
+    *,
+    app_id: str,
+    distribution_name: str,
+    version: str,
+    dist_dir: Path,
+    uv_binary: str,
+    env: dict[str, str],
+    action: str,
+) -> None:
+    wheels = sorted(dist_dir.glob("*.whl"))
+    if len(wheels) != 1:
+        raise PzError(
+            code="PZ_PUB_WHEEL_INVALID",
+            message="构建结果必须且只能包含一个 wheel。",
+            stage="cli",
+            owner="pz_core.authoring.release",
+            action=action,
+            detail=str(dist_dir),
+        )
+    wheel = wheels[0]
+    try:
+        with zipfile.ZipFile(wheel) as archive:
+            metadata_names = [
+                name for name in archive.namelist() if name.endswith(".dist-info/METADATA")
+            ]
+            if len(metadata_names) != 1:
+                raise ValueError("wheel METADATA is missing or ambiguous")
+            metadata = BytesParser().parsebytes(archive.read(metadata_names[0]))
+            import_roots = _wheel_import_roots(archive.namelist())
+    except Exception as exc:
+        raise PzError(
+            code="PZ_PUB_WHEEL_INVALID",
+            message="无法读取发布 wheel 的 metadata。",
+            stage="cli",
+            owner="pz_core.authoring.release",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    actual_name = str(metadata.get("Name") or "")
+    actual_version = str(metadata.get("Version") or "")
+    if (
+        _normalized_distribution(actual_name)
+        != _normalized_distribution(distribution_name)
+        or actual_version != version
+    ):
+        raise PzError(
+            code="PZ_PUB_WHEEL_IDENTITY_MISMATCH",
+            message="wheel metadata 与目标子包的 distribution/version 不一致。",
+            stage="cli",
+            owner="pz_core.authoring.release",
+            action=action,
+            detail=f"expected={distribution_name}=={version}; actual={actual_name}=={actual_version}",
+        )
+    if not import_roots:
+        raise PzError(
+            code="PZ_PUB_WHEEL_INVALID",
+            message="发布 wheel 中没有可验证的顶层 Python import package。",
+            stage="cli",
+            owner="pz_core.authoring.release",
+            action=action,
+            detail=str(wheel),
+        )
+    with tempfile.TemporaryDirectory(prefix="pz-pub-smoke-") as raw_temp:
+        venv = Path(raw_temp) / "venv"
+        _run_uv([uv_binary, "venv", str(venv)], cwd=dist_dir, env=env, action=action)
+        python = venv / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+        _run_uv(
+            [uv_binary, "pip", "install", "--python", str(python), "--no-deps", str(wheel)],
+            cwd=dist_dir,
+            env=env,
+            action=action,
+        )
+        smoke = subprocess.run(
+            (
+                str(python),
+                "-I",
+                "-c",
+                "import importlib,sys; [importlib.import_module(name) for name in sys.argv[1:]]",
+                *import_roots,
+            ),
+            cwd=str(dist_dir),
+            env=env,
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        if smoke.returncode != 0:
+            raise PzError(
+                code="PZ_PUB_WHEEL_SMOKE_FAILED",
+                message="wheel 在干净环境中的安装/import smoke 失败。",
+                stage="cli",
+                owner="pz_core.authoring.release",
+                action=action,
+                detail=(smoke.stderr or smoke.stdout).strip()[:500],
+            )
+
+
+def publish_commit(
+    app_id: str,
+    *,
+    project_dir: Path,
+    action: str = "publish_commit_main",
+) -> PublishCommitResult:
+    source = resolve_publish_source(project_dir, app_id, action=action)
+    version = _read_project_version(source.package_root, action=action)
+    return commit_publish_app(
+        source.app_id,
+        project_dir=project_dir,
+        version=version,
+        action=action,
+    )
+
+
+def publish_tag(
+    app_id: str,
+    *,
+    project_dir: Path,
+    commit: str | None = None,
+    action: str = "publish_tag_main",
+) -> PublishTagResult:
+    source = resolve_publish_source(project_dir, app_id, action=action)
+    version = _read_project_version(source.package_root, action=action)
+    return tag_publish_app(
+        source.app_id,
+        project_dir=project_dir,
+        version=version,
+        commit=commit,
+        action=action,
+    )
+
+
+def publish_upload(
+    app_id: str,
+    *,
+    project_dir: Path,
+    target_name: str | None = None,
+    dry_run: bool = False,
+    version: str | None = None,
+    tag_result: PublishTagResult | None = None,
+    action: str = "publish_upload_main",
+) -> PublishResult:
+    source = resolve_publish_source(project_dir, app_id, action=action)
+    resolved_version = version or _read_project_version(source.package_root, action=action)
+    resolved_tag = tag_result or require_publish_tag(
+        source.app_id,
+        project_dir=project_dir,
+        version=resolved_version,
+        action=action,
+    )
+    package_root = require_publish_checkout_at_tag(resolved_tag, action=action)
+    current_version = _read_project_version(package_root, action=action)
+    if current_version != resolved_version:
+        raise PzError(
+            code="PZ_PUB_RELEASE_STATE_INVALID",
+            message="当前 project.version 与发布版本不一致。",
+            stage="cli",
+            owner="pz_core.authoring.release",
+            action=action,
+        )
+    result = _build_and_publish_package(
+        app_id=source.app_id,
+        project_dir=project_dir,
+        package_root=package_root,
+        workspace_package_root=source.git_root,
+        target_name=target_name,
+        dry_run=dry_run,
+        action=action,
+        commit=resolved_tag.commit_result.commit,
+        tag=resolved_tag.tag,
+    )
+    return PublishResult(
+        app_id=result.app_id,
+        version=result.version,
+        package_root=source.package_root,
+        dist_dir=source.package_root / "dist",
+        target=result.target,
+        dry_run=result.dry_run,
+        commit=result.commit,
+        tag=result.tag,
+    )
+
+
+def publish_app(
+    app_id: str,
+    *,
+    project_dir: Path,
+    target_name: str | None = None,
+    dry_run: bool = False,
+    action: str = "publish_main",
+) -> PublishResult:
+    source = resolve_publish_source(project_dir, app_id, action=action)
+    if dry_run:
+        source = preflight_publish_app(
+            source.app_id,
+            project_dir=project_dir,
+            action=action,
+            source=source,
+        )
+        return _build_and_publish_package(
+            app_id=source.app_id,
+            project_dir=project_dir,
+            package_root=source.package_root,
+            workspace_package_root=source.git_root,
+            target_name=target_name,
+            dry_run=True,
+            action=action,
+        )
+    source = preflight_publish_app(
+        source.app_id,
+        project_dir=project_dir,
+        action=action,
+        source=source,
+    )
+    # The index/hash conflict check performed by `uv publish --dry-run` must
+    # happen before release history is mutated.
+    try:
+        _build_and_publish_package(
+            app_id=source.app_id,
+            project_dir=project_dir,
+            package_root=source.package_root,
+            workspace_package_root=source.git_root,
+            target_name=target_name,
+            dry_run=True,
+            action=action,
+        )
+    finally:
+        _clean_build_artifacts(source.package_root)
+    commit_result = publish_commit(source.app_id, project_dir=project_dir, action=action)
+    tag_result = publish_tag(
+        source.app_id,
+        project_dir=project_dir,
+        commit=commit_result.commit,
+        action=action,
+    )
+    return publish_upload(
+        source.app_id,
+        project_dir=project_dir,
+        target_name=target_name,
+        tag_result=tag_result,
+        action=action,
+    )
+
+
+def unpublish_app(
+    app_id: str,
+    *,
+    project_dir: Path,
+    target_name: str | None = None,
+    dry_run: bool = False,
+    force: bool = False,
+    action: str = "publish_rm_main",
+) -> UnpublishResult:
+    workspace_package = resolve_workspace_package(str(app_id), anchors=(project_dir,))
+    normalized_app_id = (
+        workspace_package.app_id
+        if workspace_package is not None
+        else normalize_publish_app_id(project_dir, str(app_id), action=action)
+    )
+    package_root = resolve_publish_package_root(
+        project_dir, normalized_app_id, action=action
+    )
+    version = _read_project_version(package_root, action=action)
+    distribution_name = _read_project_name(package_root, action=action)
+    target = _load_publish_target(
+        project_dir,
+        package_root=package_root,
+        workspace_package_root=workspace_package.repo
+        if workspace_package is not None
+        else None,
+        target_name=target_name,
+        action=action,
+    )
+    index_url = _derive_devpi_index_url(target, action=action)
+    if not _is_devpi_target(target, index_url, target.publish_url, target.check_url):
+        raise PzError(
+            code="PZ_SCAFFOLD_UNPUBLISH_TARGET_UNSUPPORTED",
+            message="unpublish currently supports formal devpi targets only.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+        )
+    username_env = target.username_env or "DEVPI_OWNER"
+    password_env = target.password_env or "DEVPI_OWNER_PASSWORD"
+    env = build_authoring_env(project_dir, action=action)
+    username = _require_named_env(
+        env,
+        username_env,
+        code="PZ_SCAFFOLD_PUBLISH_AUTH_MISSING",
+        message=f"publish target `{target.name}` requires env var `{username_env}`.",
+        action=action,
+    )
+    password = _require_named_env(
+        env,
+        password_env,
+        code="PZ_SCAFFOLD_PUBLISH_AUTH_MISSING",
+        message=f"publish target `{target.name}` requires env var `{password_env}`.",
+        action=action,
+    )
+    project_url = f"{index_url.rstrip('/')}/{quote(distribution_name, safe='')}"
+    inspect_url = _add_empty_query_flag(project_url, "ignore_bases")
+    payload = _devpi_request_json(
+        inspect_url,
+        method="GET",
+        username=username,
+        password=password,
+        action=action,
+    )
+    removed_versions = _extract_devpi_versions_for_project(
+        payload, index_url=index_url, action=action
+    )
+    if not removed_versions:
+        raise PzError(
+            code="PZ_SCAFFOLD_UNPUBLISH_NOT_FOUND",
+            message="publish target does not contain the requested package.",
+            stage="cli",
+            owner="pz_core.authoring",
+            action=action,
+            detail=distribution_name,
+        )
+    delete_url = _add_empty_query_flag(project_url, "force") if force else project_url
+    if not dry_run:
+        _devpi_request_json(
+            delete_url,
+            method="DELETE",
+            username=username,
+            password=password,
+            action=action,
+        )
+    return UnpublishResult(
+        app_id=normalized_app_id,
+        distribution_name=distribution_name,
+        version=version,
+        package_root=package_root,
+        target=target,
+        project_url=project_url,
+        removed_versions=removed_versions,
+        dry_run=dry_run,
+        force=force,
+    )
+
+
+__all__ = [
+    "InstallTarget",
+    "PublishResult",
+    "PublishTarget",
+    "UnpublishResult",
+    "build_authoring_env",
+    "install_env",
+    "install_env_for_targets",
+    "load_install_target",
+    "publish_app",
+    "publish_commit",
+    "publish_tag",
+    "publish_upload",
+    "unpublish_app",
+]