napt 0.3.1__py3-none-any.whl

napt/build/packager.py

@@ -0,0 +1,315 @@
+# 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.
+
+""".intunewin package generation for NAPT.
+
+This module handles creating .intunewin packages from built PSADT directories
+using Microsoft's IntuneWinAppUtil.exe tool.
+
+Design Principles:
+    - IntuneWinAppUtil.exe is cached globally (not per-build)
+    - Package output is named by IntuneWinAppUtil.exe: Invoke-AppDeployToolkit.intunewin
+    - Build directory can optionally be cleaned after packaging
+    - Tool is downloaded from Microsoft's official GitHub repository
+
+Example:
+    Basic usage:
+        ```python
+        from pathlib import Path
+        from napt.build.packager import create_intunewin
+
+        result = create_intunewin(
+            build_dir=Path("builds/napt-chrome/141.0.7390.123"),
+            output_dir=Path("packages")
+        )
+
+        print(f"Package: {result.package_path}")
+        ```
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+import shutil
+import subprocess
+
+import requests
+
+from napt.exceptions import ConfigError, NetworkError, PackagingError
+from napt.results import PackageResult
+
+# TODO: Add version tracking for IntuneWinAppUtil.exe
+# Currently downloads from master branch (always latest), with no version tracking.
+# Future enhancements:
+#   - Track tool version in cache metadata
+#   - Allow pinning to specific commit/release
+#   - Auto-detect when tool updates are available
+#   - Optional: Add config setting for tool version/source
+INTUNEWIN_TOOL_URL = (
+    "https://github.com/microsoft/Microsoft-Win32-Content-Prep-Tool"
+    "/raw/master/IntuneWinAppUtil.exe"
+)
+
+
+def _verify_build_structure(build_dir: Path) -> None:
+    """Verify that the build directory has a valid PSADT structure.
+
+    Args:
+        build_dir: Build directory to verify.
+
+    Raises:
+        ValueError: If required files/directories are missing.
+    """
+    required = [
+        "PSAppDeployToolkit",
+        "Files",
+        "Invoke-AppDeployToolkit.ps1",
+        "Invoke-AppDeployToolkit.exe",
+    ]
+
+    missing = []
+    for item in required:
+        if not (build_dir / item).exists():
+            missing.append(item)
+
+    if missing:
+        raise ConfigError(
+            f"Invalid PSADT build directory: {build_dir}\n"
+            f"Missing: {', '.join(missing)}"
+        )
+
+
+def _get_intunewin_tool(cache_dir: Path) -> Path:
+    """Download and cache IntuneWinAppUtil.exe.
+
+    Args:
+        cache_dir: Directory to cache the tool.
+
+    Returns:
+        Path to the IntuneWinAppUtil.exe tool.
+
+    Raises:
+        NetworkError: If download fails.
+    """
+    from napt.logging import get_global_logger
+
+    logger = get_global_logger()
+    tool_path = cache_dir / "IntuneWinAppUtil.exe"
+
+    if tool_path.exists():
+        logger.verbose("PACKAGE", f"Using cached IntuneWinAppUtil: {tool_path}")
+        return tool_path
+
+    logger.verbose("PACKAGE", "Downloading IntuneWinAppUtil.exe...")
+
+    # Download the tool
+    try:
+        response = requests.get(INTUNEWIN_TOOL_URL, timeout=60)
+        response.raise_for_status()
+    except requests.RequestException as err:
+        raise NetworkError(f"Failed to download IntuneWinAppUtil.exe: {err}") from err
+
+    # Save to cache
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    tool_path.write_bytes(response.content)
+
+    logger.verbose("PACKAGE", f"[OK] IntuneWinAppUtil.exe cached: {tool_path}")
+
+    return tool_path
+
+
+def _execute_packaging(
+    tool_path: Path,
+    source_dir: Path,
+    setup_file: str,
+    output_dir: Path,
+) -> Path:
+    """Execute IntuneWinAppUtil.exe to create .intunewin package.
+
+    Args:
+        tool_path: Path to IntuneWinAppUtil.exe.
+        source_dir: Source directory (build directory).
+        setup_file: Name of the setup file (e.g., "Invoke-AppDeployToolkit.exe").
+        output_dir: Output directory for .intunewin file.
+
+    Returns:
+        Path to the created .intunewin file.
+
+    Raises:
+        PackagingError: If packaging fails.
+    """
+    from napt.logging import get_global_logger
+
+    logger = get_global_logger()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Build command
+    # IntuneWinAppUtil.exe -c <source> -s <setup file> -o <output> -q
+    cmd = [
+        str(tool_path),
+        "-c",
+        str(source_dir),
+        "-s",
+        setup_file,
+        "-o",
+        str(output_dir),
+        "-q",  # Quiet mode
+    ]
+
+    logger.verbose("PACKAGE", f"Running: {' '.join(cmd)}")
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=300,
+        )
+
+        if result.stdout:
+            for line in result.stdout.strip().split("\n"):
+                logger.verbose("PACKAGE", f"  {line}")
+
+    except subprocess.CalledProcessError as err:
+        error_msg = f"IntuneWinAppUtil.exe failed (exit code {err.returncode})"
+        if err.stderr:
+            error_msg += f"\n{err.stderr}"
+        raise PackagingError(error_msg) from err
+    except subprocess.TimeoutExpired as err:
+        raise PackagingError(
+            f"IntuneWinAppUtil.exe timed out after {err.timeout}s"
+        ) from err
+
+    # Find the generated .intunewin file
+    intunewin_files = list(output_dir.glob("*.intunewin"))
+
+    if not intunewin_files:
+        raise PackagingError(
+            f"IntuneWinAppUtil.exe completed but no .intunewin file found in {output_dir}"
+        )
+
+    # Return the most recently created file
+    intunewin_path = max(intunewin_files, key=lambda p: p.stat().st_mtime)
+    logger.verbose("PACKAGE", f"[OK] Created: {intunewin_path.name}")
+
+    return intunewin_path
+
+
+def create_intunewin(
+    build_dir: Path,
+    output_dir: Path | None = None,
+    clean_source: bool = False,
+) -> PackageResult:
+    """Create a .intunewin package from a PSADT build directory.
+
+    Uses Microsoft's IntuneWinAppUtil.exe tool to package a PSADT build
+    directory into a .intunewin file suitable for Intune deployment.
+
+    Args:
+        build_dir: Path to the built PSADT package directory.
+        output_dir: Directory for the .intunewin output.
+            Default: packages/{app_id}/
+        clean_source: If True, remove the build directory
+            after packaging. Default is False.
+
+    Returns:
+        Package metadata including .intunewin path, app ID, and version.
+
+    Raises:
+        ConfigError: If build directory structure is invalid.
+        PackagingError: If packaging fails.
+        NetworkError: If IntuneWinAppUtil.exe download fails.
+
+    Example:
+        Basic packaging:
+            ```python
+            result = create_intunewin(
+                build_dir=Path("builds/napt-chrome/141.0.7390.123")
+            )
+            print(result.package_path)
+            # packages/napt-chrome/Invoke-AppDeployToolkit.intunewin
+            ```
+
+        With cleanup:
+            ```python
+            result = create_intunewin(
+                build_dir=Path("builds/napt-chrome/141.0.7390.123"),
+                clean_source=True
+            )
+            # Build directory is removed after packaging
+            ```
+
+    Note:
+        Requires build directory from 'napt build' command. IntuneWinAppUtil.exe
+        is downloaded and cached on first use. Setup file is always
+        "Invoke-AppDeployToolkit.exe". Output file is named by IntuneWinAppUtil.exe:
+        packages/{app_id}/Invoke-AppDeployToolkit.intunewin
+    """
+    from napt.logging import get_global_logger
+
+    logger = get_global_logger()
+
+    build_dir = build_dir.resolve()
+
+    if not build_dir.exists():
+        raise PackagingError(f"Build directory not found: {build_dir}")
+
+    # Extract app_id and version from directory structure (app_id/version/)
+    version = build_dir.name
+    app_id = build_dir.parent.name
+
+    logger.verbose("PACKAGE", f"Packaging {app_id} v{version}")
+
+    # Verify build structure
+    logger.step(1, 4, "Verifying build structure...")
+    _verify_build_structure(build_dir)
+
+    # Determine output directory
+    if output_dir is None:
+        output_dir = Path("packages") / app_id
+
+    output_dir = output_dir.resolve()
+
+    # Get IntuneWinAppUtil tool
+    logger.step(2, 4, "Getting IntuneWinAppUtil tool...")
+    tool_cache = Path("cache/tools")
+    tool_path = _get_intunewin_tool(tool_cache)
+
+    # Create .intunewin package
+    logger.step(3, 4, "Creating .intunewin package...")
+    package_path = _execute_packaging(
+        tool_path,
+        build_dir,
+        "Invoke-AppDeployToolkit.exe",
+        output_dir,
+    )
+
+    # Optionally clean source
+    if clean_source:
+        logger.step(4, 4, "Cleaning source build directory...")
+        shutil.rmtree(build_dir)
+        logger.verbose("PACKAGE", f"[OK] Removed build directory: {build_dir}")
+    else:
+        logger.step(4, 4, "Package complete")
+
+    logger.verbose("PACKAGE", f"[OK] Package created: {package_path}")
+
+    return PackageResult(
+        build_dir=build_dir,
+        package_path=package_path,
+        app_id=app_id,
+        version=version,
+        status="success",
+    )

napt/build/template.py

@@ -0,0 +1,301 @@
+# 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.
+
+"""Invoke-AppDeployToolkit.ps1 template generation for NAPT.
+
+This module handles generating the Invoke-AppDeployToolkit.ps1 script by
+reading PSADT's template, substituting configuration values, and inserting
+recipe-specific install/uninstall code.
+
+Design Principles:
+    - PSADT template remains pristine in cache
+    - Generate script by substitution, not modification
+    - Preserve PSADT's structure and comments
+    - Support dynamic values (AppScriptDate, discovered version)
+    - Merge org defaults with recipe overrides
+
+Example:
+    Basic usage:
+        ```python
+        from pathlib import Path
+        from napt.build.template import generate_invoke_script
+
+        script = generate_invoke_script(
+            template_path=Path("cache/psadt/4.1.7/Invoke-AppDeployToolkit.ps1"),
+            config=recipe_config,
+            version="141.0.7390.123",
+            psadt_version="4.1.7"
+        )
+
+        Path("builds/app/version/Invoke-AppDeployToolkit.ps1").write_text(script)
+        ```
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+import re
+from typing import Any
+
+from napt.exceptions import PackagingError
+
+
+def _format_powershell_value(value: Any) -> str:
+    """Format a Python value as a PowerShell literal.
+
+    Args:
+        value: Python value to convert.
+
+    Returns:
+        PowerShell literal representation.
+
+    Example:
+        Format values for PowerShell:
+            ```python
+            _format_powershell_value("hello")      # Returns: "'hello'"
+            _format_powershell_value(True)         # Returns: '$true'
+            _format_powershell_value([0, 1, 2])    # Returns: '@(0, 1, 2)'
+            ```
+    """
+    if isinstance(value, bool):
+        return "$true" if value else "$false"
+    elif isinstance(value, str):
+        # Escape single quotes in strings
+        escaped = value.replace("'", "''")
+        return f"'{escaped}'"
+    elif isinstance(value, (int, float)):
+        return str(value)
+    elif isinstance(value, list):
+        # Format as PowerShell array
+        items = [_format_powershell_value(item) for item in value]
+        return f"@({', '.join(items)})"
+    elif value is None or value == "":
+        return "''"
+    else:
+        # Fallback: convert to string and quote
+        return f"'{str(value)}'"
+
+
+def _build_adtsession_vars(
+    config: dict[str, Any], version: str, psadt_version: str
+) -> dict[str, Any]:
+    """Build the $adtSession hashtable variables from configuration.
+
+    Merges organization defaults with recipe-specific overrides.
+
+    Args:
+        config: Merged configuration (org + vendor + recipe).
+        version: Discovered application version.
+        psadt_version: PSADT version being used.
+
+    Returns:
+        Dictionary of variable name -> value mappings.
+
+    Note:
+        Organization defaults come from config['defaults']['psadt']['app_vars'].
+        Recipe overrides come from config['app']['psadt']['app_vars'].
+        Special handling for ${discovered_version} placeholder.
+        Auto-generates AppScriptDate if not set.
+    """
+    app = config["app"]
+
+    # Get base variables from org defaults
+    org_defaults = config.get("defaults", {}).get("psadt", {}).get("app_vars", {})
+
+    # Get recipe overrides
+    recipe_overrides = app.get("psadt", {}).get("app_vars", {})
+
+    # Merge (recipe overrides org)
+    merged_vars = {**org_defaults, **recipe_overrides}
+
+    # Replace ${discovered_version} placeholder
+    for key, value in merged_vars.items():
+        if isinstance(value, str) and "${discovered_version}" in value:
+            merged_vars[key] = value.replace("${discovered_version}", version)
+
+    # Add auto-generated fields
+    merged_vars.setdefault("AppScriptDate", date.today().strftime("%Y-%m-%d"))
+    merged_vars["DeployAppScriptVersion"] = psadt_version
+
+    # Add vendor if available
+    vendor = config.get("vendor") or app.get("vendor", "")
+    if vendor:
+        merged_vars.setdefault("AppVendor", vendor)
+
+    return merged_vars
+
+
+def _replace_session_block(template: str, vars_dict: dict[str, Any]) -> str:
+    """Replace the $adtSession = @{...} block in the template.
+
+    Finds the hashtable initialization and replaces it with values from
+    vars_dict.
+
+    Args:
+        template: PSADT template script text.
+        vars_dict: Variable name -> value mappings.
+
+    Returns:
+        Script with replaced $adtSession block.
+
+    Raises:
+        RuntimeError: If $adtSession block cannot be found in template.
+    """
+    # Find the $adtSession = @{ ... } block
+    # Pattern matches from $adtSession = @{ to the closing }
+    pattern = r"(\$adtSession = @\{)(.*?)(\n\})"
+
+    match = re.search(pattern, template, re.DOTALL)
+    if not match:
+        raise PackagingError(
+            "Could not find $adtSession hashtable in PSADT template. "
+            "Template may be from an unsupported PSADT version."
+        )
+
+    # Build replacement hashtable
+    lines = []
+    for key, value in vars_dict.items():
+        ps_value = _format_powershell_value(value)
+        lines.append(f"    {key} = {ps_value}")
+
+    replacement = "$adtSession = @{\n" + "\n".join(lines) + "\n}"
+
+    # Replace in template
+    result = re.sub(pattern, replacement, template, flags=re.DOTALL)
+
+    return result
+
+
+def _insert_recipe_code(
+    script: str, install_code: str | None, uninstall_code: str | None
+) -> str:
+    """Insert recipe install/uninstall code at marker positions.
+
+    Args:
+        script: Generated script with placeholders.
+        install_code: PowerShell code for installation.
+        uninstall_code: PowerShell code for uninstallation.
+
+    Returns:
+        Script with recipe code inserted.
+
+    Note:
+        Replaces these PSADT markers:
+        - "## <Perform Installation tasks here>"
+        - "## <Perform Uninstallation tasks here>"
+    """
+    if install_code:
+        # Ensure proper indentation (4 spaces to match PSADT style)
+        indented_install = "\n".join(
+            "    " + line if line.strip() else line
+            for line in install_code.strip().split("\n")
+        )
+
+        script = script.replace(
+            "    ## <Perform Installation tasks here>",
+            f"    ## <Perform Installation tasks here>\n{indented_install}",
+        )
+
+    if uninstall_code:
+        # Ensure proper indentation
+        indented_uninstall = "\n".join(
+            "    " + line if line.strip() else line
+            for line in uninstall_code.strip().split("\n")
+        )
+
+        script = script.replace(
+            "    ## <Perform Uninstallation tasks here>",
+            f"    ## <Perform Uninstallation tasks here>\n{indented_uninstall}",
+        )
+
+    return script
+
+
+def generate_invoke_script(
+    template_path: Path,
+    config: dict[str, Any],
+    version: str,
+    psadt_version: str,
+) -> str:
+    """Generate Invoke-AppDeployToolkit.ps1 from PSADT template and config.
+
+    Reads the PSADT template, replaces the $adtSession hashtable with
+    values from the configuration, and inserts recipe-specific install/
+    uninstall code.
+
+    Args:
+        template_path: Path to PSADT's Invoke-AppDeployToolkit.ps1 template.
+        config: Merged configuration (org + vendor + recipe).
+        version: Application version (from filesystem).
+        psadt_version: PSADT version being used.
+
+    Returns:
+        Generated PowerShell script text.
+
+    Raises:
+        PackagingError: If template doesn't exist or template parsing fails.
+
+    Example:
+        Generate deployment script from template:
+            ```python
+            from pathlib import Path
+
+            script = generate_invoke_script(
+                Path("cache/psadt/4.1.7/Invoke-AppDeployToolkit.ps1"),
+                config,
+                "141.0.7390.123",
+                "4.1.7"
+            )
+            ```
+    """
+    from napt.logging import get_global_logger
+
+    logger = get_global_logger()
+    if not template_path.exists():
+        raise PackagingError(f"PSADT template not found: {template_path}")
+
+    logger.verbose("BUILD", f"Reading PSADT template: {template_path.name}")
+
+    # Read template
+    template = template_path.read_text(encoding="utf-8")
+
+    # Build $adtSession variables
+    logger.verbose("BUILD", "Building $adtSession variables...")
+    session_vars = _build_adtsession_vars(config, version, psadt_version)
+
+    logger.debug("BUILD", "--- $adtSession Variables ---")
+    for key, value in session_vars.items():
+        logger.debug("BUILD", f"  {key} = {value}")
+
+    # Replace $adtSession block
+    script = _replace_session_block(template, session_vars)
+    logger.verbose("BUILD", "[OK] Replaced $adtSession hashtable")
+
+    # Insert recipe code
+    app = config["app"]
+    psadt_config = app.get("psadt", {})
+    install_code = psadt_config.get("install")
+    uninstall_code = psadt_config.get("uninstall")
+
+    if install_code:
+        logger.verbose("BUILD", "Inserting install code from recipe")
+    if uninstall_code:
+        logger.verbose("BUILD", "Inserting uninstall code from recipe")
+
+    script = _insert_recipe_code(script, install_code, uninstall_code)
+
+    logger.verbose("BUILD", "[OK] Script generation complete")
+
+    return script