piebuild 3.1.0__py3-none-any.whl

piebuild/__init__.py

@@ -0,0 +1,14 @@
+"""PieBuild: Modern Python application build platform."""
+
+__version__ = "3.1.0"
+__author__ = "ThatByteGuy"
+__email__ = "12aa44edsta@gmail.com"
+
+from .cli.main import main
+from .core import BuildContext, BuildEngine
+
+__all__ = [
+    "BuildEngine",
+    "BuildContext",
+    "main",
+]

piebuild/__main__.py

@@ -0,0 +1,12 @@
+"""PieBuild CLI main entry point."""
+
+import sys
+from pathlib import Path
+
+# Add the current directory to Python path so we can import piebuild
+sys.path.insert(0, str(Path(__file__).parent))
+
+from piebuild.cli.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

piebuild/artifact.py

@@ -0,0 +1,172 @@
+"""Release artifact model for PieBuild distribution.
+
+Reusable, frozen dataclass-style models describing generated artifacts.
+Usable by CLI, GUI, CI, validation, signing without tight CLI coupling.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from . import __version__ as piebuild_version
+
+
+def _sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+@dataclass(frozen=True)
+class Artifact:
+    """Describes a single distributable artifact."""
+
+    path: Path
+    format: str  # pie | appimage | exe
+    target_os: str
+    target_arch: str
+    app_name: str
+    app_version: str
+    piebuild_version: str
+    runtime_info: dict[str, Any] = field(default_factory=dict)
+    backend: str = "native"
+    build_timestamp: str = ""  # ISO8601 UTC, e.g. 2026-08-29T...
+    source_checksum: str = ""  # sha256 of original source file
+    artifact_checksum: str = ""  # sha256 of final artifact bytes
+    provenance: dict[str, Any] = field(default_factory=dict)
+    format_version: str = ""
+    toolchain: str = ""
+    signing_state: str = "unsigned"  # unsigned | signed
+    signature_info: dict[str, Any] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "path": str(self.path),
+            "format": self.format,
+            "target_os": self.target_os,
+            "target_arch": self.target_arch,
+            "app_name": self.app_name,
+            "app_version": self.app_version,
+            "piebuild_version": self.piebuild_version,
+            "runtime": self.runtime_info,
+            "backend": self.backend,
+            "build_timestamp": self.build_timestamp,
+            "source_checksum": self.source_checksum,
+            "artifact_checksum": self.artifact_checksum,
+            "provenance": dict(self.provenance),
+            "format_version": self.format_version,
+            "toolchain": self.toolchain,
+            "signing_state": self.signing_state,
+            "signature": self.signature_info,
+        }
+
+    @classmethod
+    def from_build(
+        cls,
+        artifact_path: Path,
+        build_config: Any,
+        build_result: Any,
+        provenance: dict[str, Any] | None = None,
+    ) -> Artifact:
+        """Construct from BuildConfig + BuildResult + optional provenance."""
+        path = Path(artifact_path)
+        cfg = build_config
+        meta = getattr(build_result, "metadata", {}) or {}
+
+        fmt = (getattr(cfg, "output_format", None) or "pie").lower().strip()
+        # FormatRegistry normalizes: pie is canonical
+        if not path.suffix:
+            # fallback
+            fmt = meta.get("format", fmt)
+
+        target_os = getattr(cfg, "target_os", "native")
+        target_arch = getattr(cfg, "target_arch", "native")
+        app_name = getattr(cfg, "app_name", path.stem)
+        app_ver = getattr(cfg, "version", "1.0.0")
+        backend = getattr(cfg, "backend", "native") or "native"
+
+        # source checksum: prefer provenance/manifest, else compute if possible
+        source_checksum = ""
+        prov = provenance or meta.get("provenance", {}) or {}
+        if isinstance(prov, dict):
+            source_checksum = prov.get("source_checksum", "") or meta.get("source_checksum", "")
+        if not source_checksum:
+            src = getattr(cfg, "source_file", None)
+            if src and Path(src).exists():
+                try:
+                    source_checksum = _sha256_file(Path(src))
+                except OSError:
+                    pass
+
+        artifact_checksum = ""
+        if path.exists() and path.is_file():
+            try:
+                artifact_checksum = _sha256_file(path)
+            except OSError:
+                pass
+        elif path.exists() and path.is_dir():
+            # AppDir: hash manifest + provenance deterministically
+            try:
+
+                h = hashlib.sha256()
+                for p in sorted(path.rglob("*")):
+                    if p.is_file():
+                        rel = p.relative_to(path).as_posix()
+                        h.update(rel.encode())
+                        h.update(p.read_bytes())
+                artifact_checksum = h.hexdigest()
+            except OSError:
+                pass
+
+        runtime_info = {}
+        if isinstance(prov, dict) and "runtime" in prov:
+            runtime_info = prov.get("runtime", {})
+        elif "runtime" in meta:
+            runtime_info = meta.get("runtime", {})
+
+        fmt_version = ""
+        if isinstance(prov, dict):
+            fmt_version = prov.get("format_version", "") or meta.get("format_version", "")
+
+        toolchain = ""
+        if isinstance(prov, dict):
+            toolchain = prov.get("toolchain", "") or prov.get("backend", "") or backend
+
+        signing_state = "unsigned"
+        sig_info = None
+        if isinstance(prov, dict) and "signature" in prov:
+            sig_info = prov.get("signature")
+            signing_state = "signed" if sig_info else "unsigned"
+
+        ts = ""
+        if isinstance(prov, dict):
+            ts = prov.get("built_at", "") or prov.get("build_timestamp", "")
+
+        return cls(
+            path=path,
+            format=fmt,
+            target_os=target_os,
+            target_arch=target_arch,
+            app_name=app_name,
+            app_version=app_ver,
+            piebuild_version=piebuild_version,
+            runtime_info=runtime_info if isinstance(runtime_info, dict) else {},
+            backend=backend,
+            build_timestamp=ts,
+            source_checksum=source_checksum,
+            artifact_checksum=artifact_checksum,
+            provenance=dict(prov) if isinstance(prov, dict) else {},
+            format_version=fmt_version,
+            toolchain=toolchain,
+            signing_state=signing_state,
+            signature_info=sig_info,
+        )
+
+    @property
+    def is_signed(self) -> bool:
+        return self.signing_state == "signed"

piebuild/attestation.py

@@ -0,0 +1,88 @@
+"""Build / release attestation - metadata about how artifact was produced."""
+
+from __future__ import annotations
+
+import platform
+from dataclasses import dataclass, field
+from typing import Any
+
+from . import __version__ as piebuild_version
+
+
+@dataclass(frozen=True)
+class Attestation:
+    piebuild_version: str
+    source_checksum: str
+    pie_checksum: str
+    target_os: str
+    target_arch: str
+    backend: str
+    runtime_provider: str
+    runtime_identity: str
+    format: str
+    format_version: str
+    toolchain: str
+    signing_provider: str | None = None
+    signing_key_id: str | None = None
+    build_env: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "piebuild_version": self.piebuild_version,
+            "source_checksum": self.source_checksum,
+            "pie_checksum": self.pie_checksum,
+            "target": f"{self.target_os}/{self.target_arch}",
+            "target_os": self.target_os,
+            "target_arch": self.target_arch,
+            "backend": self.backend,
+            "runtime_provider": self.runtime_provider,
+            "runtime_identity": self.runtime_identity,
+            "format": self.format,
+            "format_version": self.format_version,
+            "toolchain": self.toolchain,
+        }
+        if self.signing_provider:
+            d["signing_provider"] = self.signing_provider
+            if self.signing_key_id:
+                d["signing_key_id"] = self.signing_key_id
+        # only safe build env info, no secrets/paths
+        d["build_env"] = dict(self.build_env)
+        return d
+
+
+def build_attestation(
+    source_checksum: str = "",
+    pie_checksum: str = "",
+    target_os: str = "native",
+    target_arch: str = "native",
+    backend: str = "native",
+    runtime_provider: str = "system",
+    runtime_identity: str = "",
+    fmt: str = "pie",
+    fmt_version: str = "",
+    toolchain: str = "",
+    signing_provider: str | None = None,
+    signing_key_id: str | None = None,
+) -> Attestation:
+    # build_env: only safe, non-sensitive info
+    env = {
+        "python": platform.python_version(),
+        "platform": platform.platform(),
+        "machine": platform.machine(),
+    }
+    return Attestation(
+        piebuild_version=piebuild_version,
+        source_checksum=source_checksum,
+        pie_checksum=pie_checksum,
+        target_os=target_os,
+        target_arch=target_arch,
+        backend=backend,
+        runtime_provider=runtime_provider,
+        runtime_identity=runtime_identity,
+        format=fmt,
+        format_version=fmt_version,
+        toolchain=toolchain,
+        signing_provider=signing_provider,
+        signing_key_id=signing_key_id,
+        build_env=env,
+    )

piebuild/backends/__init__.py

@@ -0,0 +1,10 @@
+"""Build backends for PieBuild.
+
+The production backend lives in :mod:`piebuild.backends.native`; this module
+re-exports it so ``from piebuild.backends import NativeBackend`` keeps working.
+"""
+
+from .docker_backend import DockerBackend
+from .native import NativeBackend
+
+__all__ = ["NativeBackend", "DockerBackend"]

piebuild/backends/docker_backend.py

@@ -0,0 +1,385 @@
+"""Docker isolated build backend."""
+
+import logging
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from ..config import BuildConfig
+from ..context import (
+    BuildContext,
+    BuildEnvironment,
+    Target,
+    host_arch,
+    host_os,
+    resolve_target,
+)
+from ..core import BuildBackend, BuildResult, BuildStepError
+
+logger = logging.getLogger(__name__)
+
+
+def _docker_available() -> bool:
+    """Check if Docker is available and the daemon is running."""
+    try:
+        result = subprocess.run(
+            ["docker", "info"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        return result.returncode == 0
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def _docker_image_supports_arch(image: str, arch: str) -> bool:
+    """Check if a Docker image supports a given architecture."""
+    # Placeholder: in a real implementation, this would check the image manifest
+    return True
+
+
+def _resolve_docker_image(target: Target) -> str:
+    """Resolve a target to an appropriate Docker image name.
+
+    The initial implementation supports a small set of targets.
+    Adding new targets consists of extending this resolver.
+    """
+    os_name = target.os
+    arch = target.arch
+
+    # Map target to Docker image tags
+    image_tags = {
+        ("linux", "x86_64"): "python:3.14-slim-bullseye-amd64",
+        ("linux", "aarch64"): "python:3.14-slim-bullseye-arm64",
+    }
+
+    key = (os_name, arch)
+    if key in image_tags:
+        return image_tags[key]
+
+    # Fallback: try python:3.14-slim with the arch suffix
+    if os_name == "linux":
+        return f"python:3.14-slim-{arch}"
+
+    return "python:3.14-slim"
+
+
+class DockerBackend(BuildBackend):
+    """Docker isolated build backend.
+
+    Executes builds inside a Docker container, isolating the build
+    environment from the host Python installation and system libraries.
+
+    The intended flow is:
+
+    PieBuild
+     ├─ BuildEngine
+     │  └─ DockerBackend
+     │     ├─ Docker build environment
+     │     └─ PieBuild build
+     │        ├─ artifact
+     │        └─ .pie bundle
+
+    The Docker backend is isolated from the host Python environment.
+    It only receives the necessary build context (source, configuration,
+    recipes, dependency information, runtime requirements). Unrelated host
+    files are not mounted into the container.
+
+    Target images are resolved through a target-image resolver that maps
+    target identifiers to appropriate Docker images. The initial
+    implementation supports a small set of targets; adding new targets
+    consists of extending the resolver without rewriting the backend.
+
+    Native dependencies are built against the target environment rather
+    than the host. For example, a Linux host building for a target Linux
+    ARM64 environment will compile native extensions inside the container
+    for ARM64, producing an artifact whose native profile matches the
+    declared target.
+
+    The bundled runtime system must work inside the isolated backend.
+    The target runtime must correspond to the target environment, not
+    the host interpreter. The runtime identity reflects target OS,
+    architecture, Python version, ABI, and interpreter checksum, not
+    the host Python.
+
+    Backend selection is intelligent. The user can request a target with
+
+      piebuild bake app.py --target linux-x86_64 --backend docker
+
+    while native builds remain:
+
+      piebuild bake app.py --target native
+
+    If the user requests a target that the native backend cannot produce,
+    PieBuild gives a useful message explaining that another backend is
+    required, rather than silently switching.
+
+    Docker is an optional capability. PieBuild itself remains usable without
+    Docker. The normal native workflow should continue functioning exactly
+    as before.
+
+    Failure modes include: Docker unavailable, daemon unavailable,
+    image unavailable, image pull failure, container startup failure,
+    build failure, timeout, malformed build context, permission
+    problems, target mismatch, incomplete artifact.
+
+    Errors identify the failing stage and preserve useful underlying
+    diagnostics for debug mode. Docker is treated as a build isolation
+    mechanism, not an automatic security guarantee. The build context is
+    controlled: only necessary files are mounted, host secrets are not
+    exposed, arbitrary environment variables are not passed, and
+    privileged containers are avoided unless absolutely necessary.
+
+    Reproducibility is supported by recording enough metadata to identify:
+
+    * backend
+    * target
+    * build environment
+    * image
+    * image digest where available
+    * runtime
+    * ingredients
+    * PieBuild version
+
+    The bundle manifest makes it possible to understand how an artifact
+    was produced. Docker is treated as a build isolation mechanism,
+    not an automatic security guarantee. The build context is kept
+    controlled: only necessary files are mounted, host secrets are not
+    mounted, and arbitrary host commands are not executed from recipe
+    configuration without an explicit design.
+
+    The first real milestone is:
+
+      application
+       ├─ piebuild bake
+       │   └─ Docker backend
+       │        └─ isolated target environment
+       │              ├─ bundled runtime
+       │              └─ dependencies
+       │                   └─ native analysis
+       │                      └─ .pie
+       │                          ├─ inspect
+       │                          └─ run
+
+    Tests must work even on machines without Docker. When Docker is
+    available, real builds are run. When unavailable, unit tests
+    verify the backend logic with a clear reason for skipping.
+    The existing native build path remains green throughout.
+
+    Security boundary: Docker is a build isolation mechanism, not an
+    automatic security guarantee. The host filesystem is not unnecessarily
+    mounted, host secrets are not exposed, arbitrary environment variables
+    are not passed, and privileged containers are avoided unless absolutely
+    necessary. The build context is kept controlled.
+    """
+
+    name = "docker"
+    description = "Docker isolated build backend"
+    environment = BuildEnvironment(host_os=host_os(), host_arch=host_arch(), kind="docker")
+
+    def supports_target(self, target_os: str) -> bool:
+        """Return whether this backend can build for ``target_os``.
+
+        Docker images are Linux-only (python:slim). Windows/macOS targets
+        require native hosts or a dedicated remote macOS/Windows builder.
+        """
+        return target_os in ("linux", "native")
+
+    def build(self, config: BuildConfig, context: BuildContext) -> BuildResult:
+        """Execute build inside Docker container."""
+        if not _docker_available():
+            return BuildResult(
+                success=False,
+                message="Docker is not available on this system",
+                metadata={"step": "docker availability", "hint": "Install Docker or use the native backend"},
+            )
+
+        try:
+            # Resolve target to Docker image
+            target = resolve_target(
+                context.target_os, context.target_arch, config.python or "3.14", config.abi or "cpython-" + context.target_arch
+            )
+            docker_image = _resolve_docker_image(target)
+
+            # Prepare build context - only necessary files
+            build_context = self._prepare_build_context(config, context)
+
+            # Pull/build the Docker image
+            if not self._pull_docker_image(docker_image):
+                return BuildResult(
+                    success=False,
+                    message=f"Failed to pull Docker image: {docker_image}",
+                    metadata={"step": "docker image", "hint": "Check network connectivity or image availability"},
+                )
+
+            # Run the build inside Docker
+            build_result = self._run_docker_build(docker_image, build_context, target)
+
+            if build_result["success"]:
+                # Analyze the produced artifact's native profile
+                native_analysis = self._analyze_native_artifact(build_result["artifact_path"])
+
+                return BuildResult(
+                    success=True,
+                    artifact_path=build_result["artifact_path"],
+                    message="Docker build completed successfully",
+                    metadata={
+                        "step": "docker build",
+                        "docker_image": docker_image,
+                        "target_triple": f"{target.os}/{target.arch}",
+                        "native_profile": native_analysis,
+                        "runtime": build_result.get("runtime"),
+                        "warnings": build_result.get("warnings", []),
+                    },
+                )
+            else:
+                return BuildResult(
+                    success=False,
+                    message=build_result.get("message", "Docker build failed"),
+                    metadata={
+                        "step": "docker build",
+                        "hint": build_result.get("hint"),
+                    },
+                )
+
+        except BuildStepError as e:
+            return BuildResult(
+                success=False,
+                message=f"Docker build failed ({e.step} step): {str(e)}",
+                metadata={"step": e.step, "hint": e.hint},
+            )
+        except Exception as e:
+            return BuildResult(
+                success=False,
+                message=f"Docker build failed: {str(e)}",
+                metadata={"step": "docker build unexpected"},
+            )
+
+    def _prepare_build_context(self, config: BuildConfig, context: BuildContext) -> dict[str, Any]:
+        """Prepare the build context to mount into the Docker container.
+
+        Only necessary files are included; unrelated host files are excluded.
+        """
+        return {
+            "source_file": str(config.source_file),
+            "output_dir": str(config.output_dir),
+            "config": config.model_dump(),
+            "target_os": context.target_os,
+            "target_arch": context.target_arch,
+            "build_mode": context.build_mode,
+            "runtime_os": context.runtime_os,
+        }
+
+    def _pull_docker_image(self, image: str) -> bool:
+        """Pull a Docker image.
+
+        Returns True if the image is available (already local or successfully pulled).
+        """
+        try:
+            result = subprocess.run(
+                ["docker", "pull", image],
+                capture_output=True,
+                text=True,
+                timeout=120,
+            )
+            return result.returncode == 0
+        except Exception as e:
+            logger.warning("Docker pull failed: %s", e)
+            return False
+
+    def _run_docker_build(self, image: str, build_context: dict[str, Any], target: Target) -> dict[str, Any]:
+        """Run the actual build inside the Docker container.
+
+        Mounts only the necessary build context and runs the PieBuild build.
+        """
+        # Create a temporary directory for the build output
+        import tempfile
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            # Build the docker run command
+            mount_args = []
+            mount_args.append(f"{build_context['source_file']}:{build_context['source_file']}:ro")
+            mount_args.append(f"{build_context['output_dir']}:{tmp_dir}:rw")
+
+            # Environment variables to pass
+            env = {
+                "PIEBUILD_TARGET_OS": build_context["target_os"],
+                "PIEBUILD_TARGET_ARCH": build_context["target_arch"],
+                "PIEBUILD_PYTHON": build_context.get("python", "3.14"),
+                "PIEBUILD_ABI": build_context.get("abi", f"cpython-{build_context['target_arch']}"),
+            }
+
+            cmd = [
+                "docker", "run",
+                "--rm",
+                *[f"-v {mount}" for mount in mount_args],
+                *[f"-e {k}={v}" for k, v in env.items()],
+                image,
+                "python", "-m", "piebuild", "bake",
+                build_context["source_file"],
+                "--target",
+                build_context["target_os"],
+                "--backend",
+                "native",
+            ]
+
+            try:
+                result = subprocess.run(
+                    cmd,
+                    capture_output=True,
+                    text=True,
+                    timeout=300,
+                )
+
+                if result.returncode == 0:
+                    # Check if the bundle was created
+                    bundle_path = Path(tmp_dir) / "app.pie"
+                    if bundle_path.exists():
+                        return {
+                            "success": True,
+                            "artifact_path": str(bundle_path),
+                            "message": "Docker build completed successfully",
+                            "warnings": [],
+                        }
+
+            except subprocess.TimeoutExpired:
+                return {
+                    "success": False,
+                    "message": "Docker build timed out",
+                    "hint": "The build took too long. Try a simpler application or increase the timeout.",
+                }
+
+            return {
+                "success": False,
+                "message": "Docker build did not produce a bundle",
+                "hint": "Check the build output for errors",
+            }
+
+    def _analyze_native_artifact(self, artifact_path: str) -> dict[str, Any]:
+        """Analyze the native profile of the produced artifact.
+
+        Uses the existing native inspection system to determine the
+        native extensions, formats, architectures, and external
+        requirements of the built artifact.
+        """
+        try:
+            from piebuild.native import inspect_bundle_native
+            native_profile = inspect_bundle_native(artifact_path)
+            return {
+                "extensions": native_profile.extensions,
+                "formats": native_profile.formats,
+                "archs": native_profile.archs,
+                "external_requirements": native_profile.external_requirements,
+                "missing": native_profile.missing,
+                "inconsistent": native_profile.inconsistent,
+            }
+        except Exception as e:
+            logger.warning("Failed to analyze native artifact: %s", e)
+            return {
+                "extensions": [],
+                "formats": [],
+                "archs": [],
+                "external_requirements": [],
+                "missing": [],
+                "inconsistent": [],
+            }