qyro-engine 0.1.0__py3-none-any.whl

qyro/__init__.py

@@ -0,0 +1,69 @@
+"""
+Qyro.
+Clean Architecture runtime engine and lifecycle framework for Python desktop GUI apps.
+Decoupled from CLI tools, independent and multi-toolkit ready.
+"""
+
+from qyro.client.velto_context import VeltoContext
+from qyro.container import EngineContainer
+from qyro.adapters.platform.detector import PlatformDetector
+from qyro.domain.entities import PlatformType, ExecutionMode, AppMetadata
+from qyro.domain.errors import (
+    QyroEngineError,
+    ResourceNotFoundError,
+    SettingsNotFoundError,
+    FrameworkNotAvailableError,
+)
+
+__version__ = "0.1.0"
+
+# Module-level singleton container for quick procedural usage
+_default_container: EngineContainer | None = None
+
+
+def _get_default_container() -> EngineContainer:
+    global _default_container
+    app_container = VeltoContext._global_container
+    if app_container is not None:
+        _default_container = app_container
+        return app_container
+
+    if _default_container is None:
+        _default_container = EngineContainer()
+    return _default_container
+
+
+def get_resource(*segments: str, required: bool = True) -> str:
+    """Convenience helper to resolve a resource path without a context instance."""
+    container = _get_default_container()
+    return str(container.resolve_resource_use_case.execute(*segments, required=required))
+
+
+def load_build_settings() -> dict:
+    """Convenience helper to load build settings dictionary."""
+    container = _get_default_container()
+    return container.load_settings_use_case.execute().raw_settings
+
+
+def is_frozen() -> bool:
+    """Convenience helper to check if running in a frozen executable."""
+    container = _get_default_container()
+    return container.env_adapter.is_frozen()
+
+
+
+__all__ = [
+    "VeltoContext",
+    "EngineContainer",
+    "PlatformDetector",
+    "PlatformType",
+    "ExecutionMode",
+    "AppMetadata",
+    "QyroEngineError",
+    "ResourceNotFoundError",
+    "SettingsNotFoundError",
+    "FrameworkNotAvailableError",
+    "get_resource",
+    "load_build_settings",
+    "is_frozen",
+]

qyro/adapters/__init__.py

@@ -0,0 +1,20 @@
+"""
+Qyro - Adapters Layer.
+Concrete implementations of application ports.
+"""
+
+from .environment.system_environment import SystemEnvironmentAdapter
+from .settings.json_settings import JsonSettingsAdapter
+from .resources.filesystem_resources import FileSystemResourceAdapter
+from .telemetry.console_hook import ConsoleExceptionHookAdapter
+from .telemetry.sentry_hook import SentryExceptionHookAdapter
+from .platform.detector import PlatformDetector
+
+__all__ = [
+    "SystemEnvironmentAdapter",
+    "JsonSettingsAdapter",
+    "FileSystemResourceAdapter",
+    "ConsoleExceptionHookAdapter",
+    "SentryExceptionHookAdapter",
+    "PlatformDetector",
+]

qyro/adapters/environment/__init__.py

@@ -0,0 +1,3 @@
+from .system_environment import SystemEnvironmentAdapter
+
+__all__ = ["SystemEnvironmentAdapter"]

qyro/adapters/environment/system_environment.py

@@ -0,0 +1,57 @@
+"""
+System Environment Adapter.
+Implements IEnvironmentPort for PyInstaller, cx_Freeze, and Source environments.
+"""
+
+import sys
+from pathlib import Path
+from qyro.application.ports.environment import IEnvironmentPort
+from qyro.domain.entities import ExecutionMode, PlatformType
+from qyro.adapters.platform.detector import PlatformDetector
+
+
+class SystemEnvironmentAdapter(IEnvironmentPort):
+    """Detects runtime execution specifics across operating systems."""
+
+    def __init__(self, custom_root: Path | None = None) -> None:
+        self._custom_root = custom_root
+
+    def is_frozen(self) -> bool:
+        return getattr(sys, "frozen", False)
+
+    def get_execution_mode(self) -> ExecutionMode:
+        if self.is_frozen():
+            if hasattr(sys, "_MEIPASS"):
+                return ExecutionMode.FROZEN_PYINSTALLER
+            return ExecutionMode.FROZEN_GENERIC
+        return ExecutionMode.SOURCE
+
+    def get_platform(self) -> PlatformType:
+        return PlatformDetector.get_platform()
+
+    def get_root_dir(self) -> Path:
+        if self._custom_root:
+            return self._custom_root
+
+        if self.is_frozen():
+            # Executable directory
+            return Path(sys.executable).resolve().parent
+
+        # Source mode: find project root containing pyproject.toml or src/
+        cwd = Path.cwd()
+        for parent in [cwd] + list(cwd.parents):
+            if (parent / "pyproject.toml").exists() or (parent / "src").exists():
+                return parent
+        return cwd
+
+    def get_bundle_dir(self) -> Path:
+        if self.is_frozen() and hasattr(sys, "_MEIPASS"):
+            return Path(getattr(sys, "_MEIPASS")).resolve()
+
+        # macOS bundle check
+        if self.is_frozen() and sys.platform == "darwin":
+            mac_resources = Path(sys.executable).resolve().parent.parent / "Resources"
+            if mac_resources.exists():
+                return mac_resources
+
+        return self.get_root_dir()

qyro/adapters/platform/__init__.py

@@ -0,0 +1,3 @@
+from .detector import PlatformDetector
+
+__all__ = ["PlatformDetector"]

qyro/adapters/platform/detector.py

@@ -0,0 +1,73 @@
+"""
+Platform Detection Adapter.
+Detects OS and desktop environment with fine-grained distro support.
+"""
+
+import os
+import sys
+from qyro.domain.entities import PlatformType
+
+
+class PlatformDetector:
+    """Detects host operating system, architecture, and desktop flavors."""
+
+
+    @staticmethod
+    def get_platform() -> PlatformType:
+        """Return the platform type detected from the current operating system."""
+        if sys.platform.startswith("win"):
+            return PlatformType.WINDOWS
+        if sys.platform == "darwin":
+            return PlatformType.MACOS
+        if sys.platform.startswith("linux"):
+            return PlatformType.LINUX
+        if sys.platform.startswith("android"):
+            return PlatformType.ANDROID
+        return PlatformType.UNKNOWN
+
+    @classmethod
+    def is_windows(cls) -> bool:
+        return cls.get_platform() == PlatformType.WINDOWS
+
+    @classmethod
+    def is_mac(cls) -> bool:
+        return cls.get_platform() == PlatformType.MACOS
+
+    @classmethod
+    def is_linux(cls) -> bool:
+        return cls.get_platform() == PlatformType.LINUX
+
+    @classmethod
+    def is_ubuntu(cls) -> bool:
+        return cls._linux_distro_id() == "ubuntu"
+
+    @classmethod
+    def is_fedora(cls) -> bool:
+        return cls._linux_distro_id() == "fedora"
+
+    @classmethod
+    def is_arch(cls) -> bool:
+        return cls._linux_distro_id() in ("arch", "manjaro")
+
+    @classmethod
+    def is_gnome(cls) -> bool:
+        de = os.environ.get("XDG_CURRENT_DESKTOP", "").lower()
+        return "gnome" in de
+
+    @classmethod
+    def is_kde(cls) -> bool:
+        de = os.environ.get("XDG_CURRENT_DESKTOP", "").lower()
+        return "kde" in de
+
+    @staticmethod
+    def _linux_distro_id() -> str:
+        if not sys.platform.startswith("linux"):
+            return ""
+        try:
+            with open("/etc/os-release", "r", encoding="utf-8") as f:
+                for line in f:
+                    if line.startswith("ID="):
+                        return line.strip().split("=")[1].strip('"').lower()
+        except Exception:
+            pass
+        return ""

qyro/adapters/resources/__init__.py

@@ -0,0 +1,3 @@
+from .filesystem_resources import FileSystemResourceAdapter
+
+__all__ = ["FileSystemResourceAdapter"]

qyro/adapters/resources/filesystem_resources.py

@@ -0,0 +1,217 @@
+
+"""
+Filesystem resource adapter implementing IResourcePort.
+
+Resolves application resources across source and frozen environments,
+including optional protected resource bundles.
+"""
+
+from pathlib import Path
+
+from qyro.application.ports.environment import IEnvironmentPort
+from qyro.application.ports.resources import IResourcePort
+from qyro.adapters.resources.protected_bundle import ProtectedResourceBundle
+from qyro.domain.entities import PlatformType, ResourceQuery, ResourceResult
+
+
+class FileSystemResourceAdapter(IResourcePort):
+    """Resolve resources across source and frozen directory hierarchies."""
+
+    _PLATFORM_DIRECTORIES = {
+        PlatformType.WINDOWS: ("windows", "win32"),
+        PlatformType.MACOS: ("mac", "darwin"),
+        PlatformType.LINUX: ("linux",),
+    }
+
+    _RESOURCE_ALIASES = frozenset({
+        "base",
+        "windows",
+        "win32",
+        "mac",
+        "darwin",
+        "linux",
+    })
+
+    def __init__(
+        self,
+        env_port: IEnvironmentPort,
+        custom_resources_dir: Path | None = None,
+    ) -> None:
+        """Initialize the adapter with its environment and optional resource root."""
+        self._env = env_port
+        self._custom_resources_dir = custom_resources_dir
+
+    def _get_candidate_roots(self) -> list[Path]:
+        """Return resource directories in resolution priority order."""
+        if self._custom_resources_dir is not None:
+            custom_root = Path(self._custom_resources_dir).resolve()
+            if custom_root.is_dir():
+                return [custom_root]
+
+        platform_dirs = self._PLATFORM_DIRECTORIES.get(
+            self._env.get_platform(),
+            (),
+        )
+
+        candidates: list[Path] = []
+
+        if self._env.is_frozen():
+            protected_root = ProtectedResourceBundle.get_extracted_root(self._env)
+            if protected_root is not None:
+                protected_resources = protected_root / "resources"
+                candidates.extend(
+                    self._resource_directories(
+                        protected_resources,
+                        platform_dirs,
+                    )
+                )
+
+            bundle = self._env.get_bundle_dir()
+
+            candidates.extend(
+                self._resource_directories(
+                    bundle / "resources",
+                    platform_dirs,
+                )
+            )
+            candidates.extend(
+                self._resource_directories(
+                    bundle / "src" / "main" / "resources",
+                    platform_dirs,
+                )
+            )
+            candidates.append(bundle)
+
+        else:
+            root = self._env.get_root_dir()
+
+            candidates.extend(
+                self._resource_directories(
+                    root / "resources",
+                    platform_dirs,
+                )
+            )
+            candidates.extend(
+                self._resource_directories(
+                    root / "src" / "main" / "resources",
+                    platform_dirs,
+                )
+            )
+
+            protected_root = ProtectedResourceBundle.get_extracted_root(self._env)
+            if protected_root is not None:
+                protected_resources = protected_root / "resources"
+                candidates.extend(
+                    self._resource_directories(
+                        protected_resources,
+                        platform_dirs,
+                    )
+                )
+
+        return self._existing_unique_directories(candidates)
+
+    @staticmethod
+    def _resource_directories(
+        root: Path,
+        platform_dirs: tuple[str, ...],
+    ) -> list[Path]:
+        """Build platform-specific and shared resource directories."""
+        return [
+            *(root / directory for directory in platform_dirs),
+            root / "base",
+            root,
+        ]
+
+    @staticmethod
+    def _existing_unique_directories(
+        candidates: list[Path],
+    ) -> list[Path]:
+        """Filter missing directories and duplicates while preserving order."""
+        unique: list[Path] = []
+        seen: set[Path] = set()
+
+        for candidate in candidates:
+            path = candidate.resolve()
+
+            if not path.is_dir() or path in seen:
+                continue
+
+            seen.add(path)
+            unique.append(path)
+
+        return unique
+
+    def resolve(self, query: ResourceQuery) -> ResourceResult:
+        """Resolve a resource query to an absolute filesystem path."""
+        rel_path = Path(*query.relative_path_segments)
+        rel_candidates = self._candidate_relative_paths(rel_path)
+        candidates = self._get_candidate_roots()
+
+        frozen = self._env.is_frozen()
+        platform = self._env.get_platform()
+
+        for root in candidates:
+            for relative_path in rel_candidates:
+                target = root / relative_path
+
+                if target.is_file():
+                    return ResourceResult(
+                        absolute_path=target.resolve(),
+                        exists=True,
+                        is_bundled=frozen,
+                        target_os=platform,
+                    )
+
+        primary_root = (
+            candidates[0]
+            if candidates
+            else self._env.get_root_dir()
+        )
+
+        return ResourceResult(
+            absolute_path=(primary_root / rel_path).resolve(),
+            exists=False,
+            is_bundled=frozen,
+        )
+
+    def _candidate_relative_paths(
+        self,
+        rel_path: Path,
+    ) -> list[Path]:
+        """Generate relative path variants for resource directory aliases."""
+        alternatives = [rel_path]
+        parts = rel_path.parts
+
+        if (
+            len(parts) >= 2
+            and parts[0].lower() in self._RESOURCE_ALIASES
+        ):
+            alternatives.append(Path(*parts[1:]))
+
+        return list(dict.fromkeys(alternatives))
+
+    def list_resources(
+        self,
+        subdirectory: str = "",
+    ) -> list[Path]:
+        """List resources while preserving directory resolution priority."""
+        relative_path = Path(subdirectory)
+        results: list[Path] = []
+        seen: set[Path] = set()
+
+        for root in self._get_candidate_roots():
+            target_dir = root / relative_path
+
+            if not target_dir.is_dir():
+                continue
+
+            for path in target_dir.iterdir():
+                resolved = path.resolve()
+
+                if resolved in seen:
+                    continue
+
+                seen.add(resolved)
+                results.append(resolved)
+
+        return results

qyro/adapters/resources/protected_bundle.py

@@ -0,0 +1,227 @@
+"""
+Protected bundle runtime loader.
+
+Loads and extracts Velto's protected resources package generated by velto-cli,
+making embedded settings/ and resources/ folders available through filesystem
+paths without changing existing public APIs.
+"""
+
+from __future__ import annotations
+
+import atexit
+import hashlib
+import hmac
+import io
+import shutil
+import tempfile
+import zipfile
+from pathlib import Path
+from threading import Lock
+
+from qyro.application.ports.environment import IEnvironmentPort
+from qyro.adapters.resources.runtime_secret import (
+    find_runtime_secret_module,
+    read_runtime_secret,
+)
+
+
+_MAGIC = b"QYRPKG"
+_NONCE_LEN = 16
+_SALT_LEN = 16
+_TAG_LEN = 32
+_KEY_LEN = 32
+_RUNTIME_SECRET_MODULE_STEM = "runtime"
+_SECRETS_ARCHIVE_PATH = ".velto/secrets.enc"
+
+
+class ProtectedResourceBundle:
+    """Utility that extracts protected bundle contents when available."""
+
+    _lock = Lock()
+    _extracted_cache: dict[str, Path] = {}
+    _encrypted_secrets_cache: dict[str, bytes | None] = {}
+
+    @classmethod
+    def get_extracted_root(cls, env_port: IEnvironmentPort) -> Path | None:
+        """Return extracted root containing settings/ and resources/ when present."""
+        base_dir = env_port.get_bundle_dir() if env_port.is_frozen() else env_port.get_root_dir()
+        package_path = base_dir / ".velto" / "resources.pak"
+        secret_module_path = cls._find_runtime_secret_module(base_dir / ".velto")
+
+        if not package_path.exists() or secret_module_path is None:
+            return None
+
+        cache_key = cls._cache_key(package_path, secret_module_path)
+        with cls._lock:
+            cached = cls._extracted_cache.get(cache_key)
+            if cached and cached.exists():
+                return cached
+            try:
+                extracted_root, encrypted_payload = cls._extract_bundle(package_path, secret_module_path)
+            except Exception:
+                return None
+            cls._extracted_cache[cache_key] = extracted_root
+            cls._encrypted_secrets_cache[cache_key] = encrypted_payload
+            return extracted_root
+
+    @classmethod
+    def get_encrypted_secrets_payload(cls, env_port: IEnvironmentPort) -> bytes | None:
+        """Return encrypted secrets payload embedded in resources.pak when available."""
+        base_dir = env_port.get_bundle_dir() if env_port.is_frozen() else env_port.get_root_dir()
+        package_path = base_dir / ".velto" / "resources.pak"
+        secret_module_path = cls._find_runtime_secret_module(base_dir / ".velto")
+
+        if not package_path.exists() or secret_module_path is None:
+            return None
+
+        cache_key = cls._cache_key(package_path, secret_module_path)
+        with cls._lock:
+            if cache_key in cls._encrypted_secrets_cache:
+                return cls._encrypted_secrets_cache[cache_key]
+
+            try:
+                extracted_root, encrypted_payload = cls._extract_bundle(package_path, secret_module_path)
+            except Exception:
+                return None
+
+            cls._extracted_cache[cache_key] = extracted_root
+            cls._encrypted_secrets_cache[cache_key] = encrypted_payload
+            return encrypted_payload
+
+    @staticmethod
+    def _find_runtime_secret_module(protected_dir: Path) -> Path | None:
+        return find_runtime_secret_module(protected_dir)
+
+    @staticmethod
+    def _cache_key(package_path: Path, secret_module_path: Path) -> str:
+        stat_a = package_path.stat()
+        stat_b = secret_module_path.stat()
+        return (
+            f"{package_path}:{stat_a.st_mtime_ns}:{stat_a.st_size}:"
+            f"{secret_module_path}:{stat_b.st_mtime_ns}:{stat_b.st_size}"
+        )
+
+    @classmethod
+    def _extract_bundle(cls, package_path: Path, secret_module_path: Path) -> tuple[Path, bytes | None]:
+        zip_bytes = cls._decrypt_package_to_zip_bytes(package_path, secret_module_path)
+        encrypted_secrets_payload = cls._read_embedded_secrets_payload(zip_bytes)
+        extract_root = Path(tempfile.mkdtemp(prefix="velto_protected_"))
+
+        try:
+            with zipfile.ZipFile(io.BytesIO(zip_bytes), "r") as archive:
+                for member in archive.infolist():
+                    normalized_name = member.filename.strip("/")
+                    if not normalized_name or member.is_dir():
+                        continue
+                    if normalized_name == _SECRETS_ARCHIVE_PATH:
+                        continue
+                    if normalized_name.startswith(".velto/"):
+                        continue
+
+                    relative_path = Path(normalized_name)
+                    if (
+                        "\\" in normalized_name
+                        or relative_path.is_absolute()
+                        or ".." in relative_path.parts
+                        or not relative_path.parts
+                        or relative_path.parts[0] not in {"settings", "resources"}
+                    ):
+                        raise ValueError("Protected resources package contains an invalid path")
+
+                    destination = extract_root / relative_path
+                    destination.parent.mkdir(parents=True, exist_ok=True)
+                    with archive.open(member) as source, destination.open("wb") as target:
+                        shutil.copyfileobj(source, target)
+        except Exception:
+            shutil.rmtree(extract_root, ignore_errors=True)
+            raise
+
+        atexit.register(shutil.rmtree, extract_root, ignore_errors=True)
+        return extract_root, encrypted_secrets_payload
+
+    @classmethod
+    def _decrypt_package_to_zip_bytes(cls, package_path: Path, secret_module_path: Path) -> bytes:
+        payload = package_path.read_bytes()
+        runtime_secret = cls._read_runtime_secret(secret_module_path)
+        key, ciphertext, nonce, tag = cls._parse_payload(payload, runtime_secret)
+
+        expected_tag = hmac.new(key, nonce + ciphertext, hashlib.sha256).digest()
+        if not hmac.compare_digest(tag, expected_tag):
+            raise ValueError("Protected resources signature mismatch")
+
+        return cls._xor_keystream(ciphertext, key=key, nonce=nonce)
+
+    @staticmethod
+    def _read_embedded_secrets_payload(zip_bytes: bytes) -> bytes | None:
+        with zipfile.ZipFile(io.BytesIO(zip_bytes), "r") as archive:
+            try:
+                return archive.read(_SECRETS_ARCHIVE_PATH)
+            except KeyError:
+                return None
+
+    @classmethod
+    def _parse_payload(cls, payload: bytes, runtime_secret: bytes) -> tuple[bytes, bytes, bytes, bytes]:
+        min_len = len(_MAGIC) + _SALT_LEN + _KEY_LEN + _NONCE_LEN + _TAG_LEN
+        if len(payload) <= min_len or not payload.startswith(_MAGIC):
+            raise ValueError("Invalid protected resources package format")
+
+        cursor = len(_MAGIC)
+        salt = payload[cursor:cursor + _SALT_LEN]
+        cursor += _SALT_LEN
+
+        wrapped_key = payload[cursor:cursor + _KEY_LEN]
+        cursor += _KEY_LEN
+
+        nonce = payload[cursor:cursor + _NONCE_LEN]
+        cursor += _NONCE_LEN
+
+        tag = payload[cursor:cursor + _TAG_LEN]
+        cursor += _TAG_LEN
+
+        ciphertext = payload[cursor:]
+        key = cls._unwrap_key(wrapped_key=wrapped_key, salt=salt, runtime_secret=runtime_secret)
+        return key, ciphertext, nonce, tag
+
+    @classmethod
+    def _unwrap_key(cls, *, wrapped_key: bytes, salt: bytes, runtime_secret: bytes) -> bytes:
+        mask = cls._keystream(seed=cls._master_seed(salt, runtime_secret), size=len(wrapped_key))
+        return bytes(value ^ mask[i] for i, value in enumerate(wrapped_key))
+
+    @staticmethod
+    def _master_seed(salt: bytes, runtime_secret: bytes) -> bytes:
+        return hashlib.sha256(runtime_secret + salt).digest()
+
+    @classmethod
+    def _keystream(cls, *, seed: bytes, size: int) -> bytes:
+        blocks: list[bytes] = []
+        index = 0
+        total = 0
+        while total < size:
+            block = hashlib.sha256(seed + index.to_bytes(8, "big")).digest()
+            blocks.append(block)
+            total += len(block)
+            index += 1
+        return b"".join(blocks)[:size]
+
+    @staticmethod
+    def _read_runtime_secret(secret_module_path: Path) -> bytes:
+        return read_runtime_secret(secret_module_path)
+
+    @staticmethod
+    def _xor_keystream(data: bytes, *, key: bytes, nonce: bytes) -> bytes:
+        out = bytearray(len(data))
+        block_index = 0
+        offset = 0
+
+        while offset < len(data):
+            block_seed = nonce + block_index.to_bytes(8, "big")
+            stream = hashlib.sha256(key + block_seed).digest()
+            chunk = data[offset:offset + len(stream)]
+
+            for i, value in enumerate(chunk):
+                out[offset + i] = value ^ stream[i]
+
+            offset += len(chunk)
+            block_index += 1
+
+        return bytes(out)