napt 0.3.1__py3-none-any.whl

napt/policy/updates.py

@@ -0,0 +1,126 @@
+# Copyright 2025 Roger Cibrian
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Update decision policy for NAPT.
+
+Determines whether a newly discovered remote artifact should be staged,
+based on version, hash, and org policy.
+
+Example:
+    Check if a new version should be staged:
+        ```python
+        from napt.policy.updates import should_stage, UpdatePolicy
+
+        decision = should_stage(
+            remote_version="124.0.6367.91",
+            remote_hash="abc...",
+            current_version="124.0.6367.70",
+            current_hash="def...",
+            policy=UpdatePolicy(
+                strategy="version_then_hash",
+                allow_same_version_hash_change=True,
+                comparator="semver"
+            ),
+        )
+        ```
+
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from napt.versioning import is_newer_any
+
+Strategy = Literal["version_only", "version_then_hash", "hash_or_version", "hash_only"]
+Comparator = Literal["semver", "lexicographic"]
+
+
+@dataclass(frozen=True)
+class UpdatePolicy:
+    """Update policy configuration for determining when to stage new versions.
+
+    Attributes:
+        strategy: Strategy for version comparison (default: "version_then_hash").
+        allow_same_version_hash_change: Allow staging when version is same but
+            hash differs (default: True).
+        comparator: Version comparison method - "semver" or "lexicographic"
+            (default: "semver").
+    """
+
+    strategy: Strategy = "version_then_hash"
+    allow_same_version_hash_change: bool = True
+    comparator: Comparator = "semver"
+
+
+def should_stage(
+    *,
+    remote_version: str,
+    remote_hash: str,
+    current_version: str | None,
+    current_hash: str | None,
+    policy: UpdatePolicy,
+) -> bool:
+    """Decide whether to stage a newly discovered artifact.
+
+    Compares remote version/hash against current state using the configured
+    policy strategy to determine if the new artifact should be staged.
+
+    Args:
+        remote_version: Version found during discovery.
+        remote_hash: SHA-256 hash of the newly downloaded artifact.
+        current_version: Version we last staged/deployed (None if none).
+        current_hash: Hash we last staged/deployed (None if none).
+        policy: UpdatePolicy controlling the decision algorithm.
+
+    Returns:
+        True if the new artifact should be staged, False otherwise.
+
+    """
+    # If we have no prior state, stage the first artifact.
+    if current_version is None and current_hash is None:
+        return True
+
+    # Normalized comparisons
+    version_changed = (
+        True
+        if current_version is None
+        else is_newer_any(remote_version, current_version, policy.comparator)
+        or remote_version != current_version
+        # Treat "different version string" as change even if comparator
+        # treats them equal
+    )
+
+    hash_changed = (current_hash or "").lower() != (remote_hash or "").lower()
+
+    if policy.strategy == "version_only":
+        return version_changed
+
+    if policy.strategy == "version_then_hash":
+        if version_changed:
+            return True
+        if not version_changed and policy.allow_same_version_hash_change:
+            # Same version string but bits changed (repack, resign, silent fix)
+            return hash_changed
+        return False
+
+    if policy.strategy == "hash_or_version":
+        return version_changed or hash_changed
+
+    if policy.strategy == "hash_only":
+        return hash_changed
+
+    # Safe default: do not stage on unknown strategy
+    return False

napt/psadt/__init__.py

@@ -0,0 +1,43 @@
+# Copyright 2025 Roger Cibrian
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""PSAppDeployToolkit integration for NAPT.
+
+This module handles PSAppDeployToolkit (PSADT) release management, caching,
+and integration with NAPT's build system.
+
+Example:
+    Basic usage:
+        ```python
+        from pathlib import Path
+        from napt.psadt import get_psadt_release, fetch_latest_psadt_version
+
+        # Get latest version
+        latest = fetch_latest_psadt_version()
+        print(f"Latest PSADT: {latest}")
+
+        # Download and cache
+        psadt_path = get_psadt_release("latest", Path("cache/psadt"))
+        print(f"PSADT cached at: {psadt_path}")
+        ```
+
+"""
+
+from .release import (
+    fetch_latest_psadt_version,
+    get_psadt_release,
+    is_psadt_cached,
+)
+
+__all__ = ["fetch_latest_psadt_version", "get_psadt_release", "is_psadt_cached"]

napt/psadt/release.py

@@ -0,0 +1,309 @@
+# Copyright 2025 Roger Cibrian
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""PSADT release management for NAPT.
+
+This module handles fetching, downloading, and caching PSAppDeployToolkit
+releases from the official GitHub repository. It reuses NAPT's existing
+GitHub release discovery infrastructure for consistency.
+
+Key Features:
+
+- Fetch latest PSADT version from GitHub API
+- Download and cache specific PSADT versions
+- Extract releases to cache directory
+- Version resolution ("latest" keyword support)
+
+Example:
+    Get and cache PSADT releases:
+        ```python
+        from pathlib import Path
+        from napt.psadt import get_psadt_release, is_psadt_cached
+
+        # Get latest PSADT
+        psadt_dir = get_psadt_release("latest", Path("cache/psadt"))
+
+        # Get specific version
+        psadt_dir = get_psadt_release("4.1.7", Path("cache/psadt"))
+
+        # Check if cached
+        if is_psadt_cached("4.1.7", Path("cache/psadt")):
+            print("Already cached!")
+        ```
+
+Note:
+    - Reuses notapkgtool.discovery.api_github for API calls
+    - Caches releases by version: cache/psadt/{version}/
+    - Downloads .zip releases and extracts to cache
+    - Validates extracted PSADT structure (PSAppDeployToolkit/ folder exists)
+
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+import re
+import zipfile
+
+import requests
+
+from napt.exceptions import NetworkError, PackagingError
+
+PSADT_REPO = "PSAppDeployToolkit/PSAppDeployToolkit"
+PSADT_GITHUB_API = f"https://api.github.com/repos/{PSADT_REPO}/releases/latest"
+
+
+def fetch_latest_psadt_version() -> str:
+    """Fetch the latest PSADT release version from GitHub.
+
+    Queries the GitHub API for the latest release and extracts the version
+    number from the tag name (e.g., "4.1.7" from tag "4.1.7").
+
+    Returns:
+        Version number (e.g., "4.1.7").
+
+    Raises:
+        RuntimeError: If the GitHub API request fails or version cannot be
+            extracted.
+
+    Example:
+        Get latest PSADT version from GitHub:
+            ```python
+            version = fetch_latest_psadt_version()
+            print(version)  # Output: "4.1.7"
+            ```
+
+    Note:
+        - Uses GitHub's public API (60 requests/hour limit without auth)
+        - Version is extracted from release tag name
+        - For higher rate limits, set GITHUB_TOKEN environment variable
+
+    """
+    from napt.logging import get_global_logger
+
+    logger = get_global_logger()
+    logger.verbose("PSADT", f"Querying GitHub API: {PSADT_GITHUB_API}")
+
+    try:
+        headers = {
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+
+        response = requests.get(PSADT_GITHUB_API, headers=headers, timeout=30)
+        response.raise_for_status()
+    except requests.RequestException as err:
+        raise NetworkError(
+            f"Failed to fetch latest PSADT release from GitHub: {err}"
+        ) from err
+
+    data = response.json()
+    tag_name = data.get("tag_name", "")
+
+    if not tag_name:
+        raise NetworkError("GitHub API response missing 'tag_name' field")
+
+    # Extract version from tag (e.g., "4.1.7" or "v4.1.7")
+    # PSADT uses tags without 'v' prefix
+    version_match = re.match(r"v?(\d+\.\d+\.\d+)", tag_name)
+    if not version_match:
+        raise NetworkError(f"Could not extract version from tag: {tag_name!r}")
+
+    version = version_match.group(1)
+    logger.verbose("PSADT", f"Latest PSADT version: {version}")
+
+    return version
+
+
+def is_psadt_cached(version: str, cache_dir: Path) -> bool:
+    """Check if a PSADT version is already cached.
+
+    Args:
+        version: PSADT version to check (e.g., "4.1.7").
+        cache_dir: Base cache directory (e.g., Path("cache/psadt")).
+
+    Returns:
+        True if the version is cached and valid, False otherwise.
+
+    Example:
+        Check if PSADT version is cached:
+            ```python
+            from pathlib import Path
+
+            if is_psadt_cached("4.1.7", Path("cache/psadt")):
+                print("Already downloaded!")
+            ```
+
+    Note:
+        Validates that the cache contains the expected PSADT structure:
+
+        - PSAppDeployToolkit/ folder must exist
+        - PSAppDeployToolkit.psd1 manifest must exist
+
+    """
+    version_dir = cache_dir / version
+    psadt_dir = version_dir / "PSAppDeployToolkit"
+    manifest = psadt_dir / "PSAppDeployToolkit.psd1"
+
+    return psadt_dir.exists() and manifest.exists()
+
+
+def get_psadt_release(release_spec: str, cache_dir: Path) -> Path:
+    """Download and extract a PSADT release to the cache directory.
+
+    Resolves "latest" to the current latest version from GitHub, then
+    downloads the release .zip file and extracts it to the cache.
+
+    Args:
+        release_spec: Version specifier - either "latest" or specific version
+            (e.g., "4.1.7").
+        cache_dir: Base cache directory for PSADT releases.
+
+    Returns:
+        Path to the cached PSADT directory (cache_dir/{version}).
+
+    Raises:
+        NetworkError: If download fails.
+        PackagingError: If extraction fails.
+        ConfigError: If release_spec is invalid.
+
+    Example:
+        Get latest version:
+            ```python
+            from pathlib import Path
+
+            psadt = get_psadt_release("latest", Path("cache/psadt"))
+            print(psadt)  # Output: cache/psadt/4.1.7
+            ```
+
+        Get specific version:
+            ```python
+            psadt = get_psadt_release("4.1.7", Path("cache/psadt"))
+            ```
+
+    Note:
+        - Caches by version: cache/psadt/{version}/PSAppDeployToolkit/
+        - If already cached, returns path immediately (no re-download)
+        - Downloads from GitHub releases as .zip files
+        - Extracts entire archive to version directory
+
+    """
+    from napt.logging import get_global_logger
+
+    logger = get_global_logger()
+    # Resolve "latest" to actual version
+    if release_spec == "latest":
+        logger.verbose("PSADT", "Resolving 'latest' to current version...")
+        version = fetch_latest_psadt_version()
+    else:
+        version = release_spec
+
+    logger.verbose("PSADT", f"PSADT version: {version}")
+
+    # Check if already cached
+    if is_psadt_cached(version, cache_dir):
+        version_dir = cache_dir / version
+        logger.verbose("PSADT", f"Using cached PSADT: {version_dir}")
+        return version_dir
+
+    # Need to download
+    logger.verbose("PSADT", f"Downloading PSADT {version}...")
+
+    # Get release info from GitHub
+    release_url = f"https://api.github.com/repos/{PSADT_REPO}/releases/tags/{version}"
+
+    try:
+        headers = {
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+
+        response = requests.get(release_url, headers=headers, timeout=30)
+        response.raise_for_status()
+    except requests.RequestException as err:
+        raise NetworkError(
+            f"Failed to fetch PSADT release {version} from GitHub: {err}"
+        ) from err
+
+    release_data = response.json()
+
+    # Find the Template_v4 .zip asset (the full v4 template structure)
+    assets = release_data.get("assets", [])
+    zip_asset = None
+
+    # Look for Template_v4 version specifically
+    for asset in assets:
+        name = asset.get("name", "")
+        if name.endswith(".zip") and "Template_v4" in name:
+            zip_asset = asset
+            break
+
+    # Fallback to any PSADT zip if Template_v4 not found
+    if not zip_asset:
+        for asset in assets:
+            name = asset.get("name", "")
+            if name.endswith(".zip") and "PSAppDeployToolkit" in name:
+                zip_asset = asset
+                break
+
+    if not zip_asset:
+        raise NetworkError(
+            f"No .zip asset found in PSADT release {version}. "
+            f"Available assets: {[a.get('name') for a in assets]}"
+        )
+
+    download_url = zip_asset.get("browser_download_url")
+    if not download_url:
+        raise NetworkError(f"Asset missing download URL: {zip_asset}")
+
+    logger.verbose("PSADT", f"Downloading: {zip_asset['name']}")
+
+    # Download the .zip file
+    try:
+        zip_response = requests.get(download_url, timeout=300)
+        zip_response.raise_for_status()
+    except requests.RequestException as err:
+        raise NetworkError(f"Failed to download PSADT release: {err}") from err
+
+    # Create cache directory
+    version_dir = cache_dir / version
+    version_dir.mkdir(parents=True, exist_ok=True)
+
+    # Save .zip temporarily
+    zip_path = version_dir / f"psadt_{version}.zip"
+    zip_path.write_bytes(zip_response.content)
+
+    logger.verbose("PSADT", f"Extracting to: {version_dir}")
+
+    # Extract .zip
+    try:
+        with zipfile.ZipFile(zip_path, "r") as zf:
+            zf.extractall(version_dir)
+    except zipfile.BadZipFile as err:
+        raise PackagingError(f"Failed to extract PSADT archive: {err}") from err
+    finally:
+        # Clean up .zip file
+        if zip_path.exists():
+            zip_path.unlink()
+
+    # Verify extracted structure
+    if not is_psadt_cached(version, cache_dir):
+        raise PackagingError(
+            f"PSADT extraction failed: PSAppDeployToolkit/ folder "
+            f"not found in {version_dir}"
+        )
+
+    logger.verbose("PSADT", f"PSADT {version} cached successfully")
+
+    return version_dir