autopkg-wrapper 2024.2.4__py3-none-any.whl → 2026.2.6__py3-none-any.whl

autopkg_wrapper/utils/args.py

@@ -14,6 +14,7 @@ def validate_file(arg):
         message = f"Error! This is not valid file: {arg}"
         raise argparse.ArgumentTypeError(message)
 
+
 def validate_directory(arg):
     dir_path = Path(arg).resolve()
     dir_exists = dir_path.is_dir()
@@ -25,38 +26,115 @@ def validate_directory(arg):
         raise argparse.ArgumentTypeError(message)
 
 
+def validate_bool(arg):
+    if isinstance(arg, bool):
+        return arg
+    elif isinstance(arg, str) and arg.lower() in ["0", "false", "no", "f"]:
+        return False
+    elif isinstance(arg, str) and arg.lower() in ["1", "true", "yes", "t"]:
+        return True
+
+
+def find_github_token():
+    if os.getenv("GITHUB_TOKEN", None):
+        return os.getenv("GITHUB_TOKEN")
+    elif os.getenv("GH_TOKEN", None):
+        return os.getenv("GH_TOKEN")
+    else:
+        return None
+
+
 def setup_args():
     parser = argparse.ArgumentParser(description="Run autopkg recipes")
     recipe_arguments = parser.add_mutually_exclusive_group()
     recipe_arguments.add_argument(
         "--recipe-file",
         type=validate_file,
-        default=None,
-        help="Path to a list of recipes to run",
+        default=os.getenv("AW_RECIPE_FILE", None),
+        help="Provide the list of recipes to run via a JSON file for easier management.",
     )
     recipe_arguments.add_argument(
         "--recipes",
-        "--recipe",
         nargs="*",
-        default=os.getenv("AUTOPKG_RECIPES", None),
-        help="Recipes to run with autopkg",
+        default=os.getenv("AW_RECIPES", None),
+        help="""
+            Recipes to run via CLI flag or environment variable. If the '--recipes' flag is used, simply
+            provide a space-separated list on the command line:
+                `autopkg-wrapper --recipes recipe_one.download recipe_two.download`
+            Alternatively, you can provide a space/comma-separated list in the 'AW_RECIPES' environment
+            variable:
+                `export AW_RECIPES="recipe_one.download recipe_two.download"`
+                `export AW_RECIPES="recipe_one.pkg,recipe_two.pkg"`
+                `autopkg-wrapper`
+            """,
     )
+    parser.add_argument(
+        "--recipe-processing-order",
+        nargs="*",
+        default=os.getenv("AW_RECIPE_PROCESSING_ORDER", None),
+        help="""
+            This option comes in handy if you include additional recipe type names in your overrides and wish them to be processed in a specific order.
+            We'll specifically look for these recipe types after the first period (.) in the recipe name.
+            Order items can be either a full type suffix (e.g. "upload.jamf") or a partial token (e.g. "upload", "auto_update").
+            Partial tokens are matched against the dot-separated segments after the first '.' so recipes like "Foo.epz.auto_update.jamf" will match "auto_update".
+            This can also be provided via the 'AW_RECIPE_PROCESSING_ORDER' environment variable as a comma-separated list (e.g. "upload,self_service,auto_update").
+            For example, if you have the following recipes to be processed:
+                ExampleApp.auto_install.jamf
+                ExampleApp.upload.jamf
+                ExampleApp.self_service.jamf
+            And you want to ensure that the .upload recipes are always processed first, followed by .auto_install, and finally .self_service, you would provide the following processing order:
+                `--recipe-processing-order upload.jamf auto_install.jamf self_service.jamf`
+            This would ensure that all .upload recipes are processed before any other recipe types.
+            Within each recipe type, the recipes will be ordered alphabetically.
+            We assume that no extensions are provided (but will strip them if needed - extensions that are stripped include .recipe or .recipe.yaml).
+            """,
+    )
+    parser.add_argument(
+        "--autopkg-bin",
+        default=os.getenv("AW_AUTOPKG_BIN", "/usr/local/bin/autopkg"),
+        help="Path to the autopkg binary (default: /usr/local/bin/autopkg). Can also be set via AW_AUTOPKG_BIN.",
+    )
+
     parser.add_argument(
         "--debug",
-        default=os.getenv("DEBUG", False),
+        default=validate_bool(os.getenv("AW_DEBUG", False)),
         action="store_true",
         help="Enable debug logging when running script",
     )
     parser.add_argument(
-        "--override-trust",
-        action="store_false",
-        help="If set recipe override trust verification will be disabled. (Default: True)",
+        "--disable-recipe-trust-check",
+        action="store_true",
+        help="""
+            If this option is used, recipe trust verification will not be run prior to a recipe run.
+            This does not set FAIL_RECIPES_WITHOUT_TRUST_INFO to No. You will need to set that outside
+            of this application.
+            """,
+    )
+    parser.add_argument(
+        "--disable-git-commands",
+        action="store_true",
+        help="""
+            If this option is used, git commands won't be run
+            """,
+    )
+    parser.add_argument(
+        "--concurrency",
+        type=int,
+        default=int(os.getenv("AW_CONCURRENCY", "1")),
+        help="Number of recipes to run in parallel (default: 1)",
     )
-    parser.add_argument("--slack-token", default=os.getenv("SLACK_WEBHOOK_TOKEN", None), help=argparse.SUPPRESS)
-    parser.add_argument("--github-token", default=os.getenv("GITHUB_TOKEN", None))
+    parser.add_argument(
+        "--slack-token",
+        default=os.getenv("SLACK_WEBHOOK_TOKEN", None),
+        help=argparse.SUPPRESS,
+    )
+    parser.add_argument("--github-token", default=find_github_token())
     parser.add_argument(
         "--branch-name",
-        default=os.getenv("AUTOPKG_TRUST_BRANCH", f"fix/update_trust_information/{datetime.now().strftime("%Y-%m-%dT%H-%M-%S")}"),
+        default=os.getenv(
+            "AW_TRUST_BRANCH",
+            f"fix/update_trust_information/{datetime.now().strftime('%Y-%m-%dT%H-%M-%S')}",
+        ),
         help="""
             Branch name to be used recipe overrides have failed their trust verification and need to be updated.
             By default, this will be in the format of \"fix/update_trust_information/YYYY-MM-DDTHH-MM-SS\"
@@ -64,18 +142,76 @@ def setup_args():
     )
     parser.add_argument(
         "--create-pr",
-        default=os.getenv("CREATE_PR", False),
+        default=os.getenv("AW_CREATE_PR", False),
         action="store_true",
         help="If enabled, autopkg_wrapper will open a PR for updated trust information",
     )
     parser.add_argument(
-        "--autopkg-overrides-repo-path",
-        default=os.getenv("AUTOPKG_OVERRIDES_REPO_PATH", None),
+        "--create-issues",
+        action="store_true",
+        help="Create a GitHub issue for recipes that fail during processing",
+    )
+    parser.add_argument(
+        "--overrides-repo-path",
+        default=os.getenv("AW_OVERRIDES_REPO_PATH", None),
         type=validate_directory,
         help="""
         The path on disk to the git repository containing the autopkg overrides directory.
         If none is provided, we will try to determine it for you.
         """,
     )
+    parser.add_argument(
+        "--post-processors",
+        default=os.getenv("AW_POST_PROCESSORS", None),
+        nargs="*",
+        help="""
+        One or more autopkg post processors to run after each recipe execution
+        """,
+    )
+    parser.add_argument(
+        "--autopkg-prefs",
+        default=os.getenv("AW_AUTOPKG_PREFS_FILE", None),
+        type=validate_file,
+        help="""
+        Path to the autopkg preferences you'd like to use
+        """,
+    )
+
+    # Report processing options
+    parser.add_argument(
+        "--process-reports",
+        action="store_true",
+        help="Process autopkg report directories or zip and emit markdown summaries",
+    )
+    parser.add_argument(
+        "--reports-zip",
+        default=os.getenv("AW_REPORTS_ZIP", None),
+        help="Path to an autopkg_report-*.zip to extract and process",
+    )
+    parser.add_argument(
+        "--reports-extract-dir",
+        default=os.getenv("AW_REPORTS_EXTRACT_DIR", "autopkg_reports_summary/reports"),
+        help="Directory to extract the zip into (default: autopkg_reports_summary/reports)",
+    )
+    parser.add_argument(
+        "--reports-dir",
+        default=os.getenv("AW_REPORTS_DIR", None),
+        help="Directory of reports to process (if no zip provided)",
+    )
+    parser.add_argument(
+        "--reports-out-dir",
+        default=os.getenv("AW_REPORTS_OUT_DIR", "autopkg_reports_summary/summary"),
+        help="Directory to write markdown outputs (default: autopkg_reports_summary/summary)",
+    )
+    parser.add_argument(
+        "--reports-run-date",
+        default=os.getenv("AW_REPORTS_RUN_DATE", ""),
+        help="Run date string to include in the summary",
+    )
+    parser.add_argument(
+        "--reports-strict",
+        action="store_true",
+        help="Exit non-zero if any errors are detected in processed reports",
+    )
 
     return parser.parse_args()

autopkg_wrapper/utils/git_functions.py

@@ -1,5 +1,7 @@
 import logging
+import re
 import subprocess
+from datetime import datetime
 
 from github import Github
 
@@ -20,12 +22,26 @@ def git_run(*args):
 
 
 def get_repo_info(override_repo_git_git_dir):
-    repo_url = (
-        git_run(override_repo_git_git_dir, "config", "--get", "remote.origin.url")
-        .stdout.strip()
-        .split(".git")[0]
+    remote = git_run(
+        override_repo_git_git_dir, "config", "--get", "remote.origin.url"
+    ).stdout.strip()
+
+    # Supports:
+    # - https://github.com/<owner>/<repo>.git
+    # - git@github.com:<owner>/<repo>.git
+    # - ssh://git@github.com/<owner>/<repo>.git
+    m = re.search(
+        r"github\.com[:/](?P<owner>[^/]+)/(?P<repo>[^\s/]+?)(?:\.git)?$",
+        remote,
+        flags=re.IGNORECASE,
     )
-    remote_repo_ref = repo_url.split("https://github.com/")[1]
+    if not m:
+        raise ValueError(f"Unsupported Git remote URL: {remote}")
+
+    owner = m.group("owner")
+    repo = m.group("repo")
+    remote_repo_ref = f"{owner}/{repo}"
+    repo_url = f"https://github.com/{remote_repo_ref}"
 
     logging.debug(f"Repo URL: {repo_url}")
     logging.debug(f"Remote Repo Ref: {remote_repo_ref}")
@@ -102,8 +118,58 @@ Please review and merge the updated trust information for this override.
 
     g = Github(git_info["github_token"])
     repo = g.get_repo(git_info["override_repo_remote_ref"])
-    pr = repo.create_pull(title=title, body=body, head=git_info["override_trust_branch"], base="main")
-    pr_url = f"{git_info["override_repo_url"]}/pull/{pr.number}"
+    pr = repo.create_pull(
+        title=title, body=body, head=git_info["override_trust_branch"], base="main"
+    )
+    pr_url = f"{git_info['override_repo_url']}/pull/{pr.number}"
 
     logging.debug(f"PR URL: {pr_url}")
     return pr_url
+
+
+def create_issue_for_failed_recipes(git_info, failed_recipes):
+    """
+    Creates a GitHub issue listing all recipes that failed during the run.
+
+    Args:
+        git_info (dict): Dictionary containing Git repository information
+        failed_recipes (list): List of Recipe objects that failed during processing
+
+    Returns:
+        str: URL of the created GitHub issue, or None if no issue was created
+    """
+
+    if not failed_recipes:
+        logging.debug("No failed recipes to report")
+        return None
+
+    g = Github(git_info["github_token"])
+    repo = g.get_repo(git_info["override_repo_remote_ref"])
+
+    # Create issue title and body
+    current_date = datetime.now().strftime("%Y-%m-%d")
+    title = f"AutoPkg Recipe Failures - {current_date}"
+
+    body = "## Recipe Failure Details:\n\n"
+    for recipe in failed_recipes:
+        body += f"#### {recipe.name}\n"
+
+        if recipe.results.get("failed"):
+            for failure in recipe.results.get("failed", []):
+                body += f"- {failure.get('message', 'Unknown error')}\n"
+
+        body += "\n"
+
+    body += "\nThis issue was automatically generated by autopkg-wrapper."
+
+    # Create the issue
+    issue = repo.create_issue(
+        title=title,
+        body=body,
+        labels=["autopkg-failure"],
+    )
+
+    issue_url = f"{git_info['override_repo_url']}/issues/{issue.number}"
+    logging.debug(f"Issue URL: {issue_url}")
+
+    return issue_url

autopkg_wrapper/utils/recipe_batching.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Iterable, Protocol, TypeVar
+
+
+class HasFilename(Protocol):
+    filename: str
+
+
+T = TypeVar("T", bound=HasFilename)
+
+
+def recipe_type_for(recipe: HasFilename) -> str:
+    parts = recipe.filename.split(".", 1)
+    return parts[1] if len(parts) == 2 else ""
+
+
+def build_recipe_batches(
+    recipe_list: Iterable[T], recipe_processing_order
+) -> list[list[T]]:
+    recipe_list = list(recipe_list)
+    if not recipe_list:
+        return []
+    if not recipe_processing_order:
+        return [recipe_list]
+
+    batches: list[list[T]] = []
+    current_batch: list[T] = []
+    current_type = None
+    for recipe in recipe_list:
+        r_type = recipe_type_for(recipe)
+        if current_type is None or r_type == current_type:
+            current_batch.append(recipe)
+            current_type = r_type
+            continue
+        batches.append(current_batch)
+        current_batch = [recipe]
+        current_type = r_type
+    if current_batch:
+        batches.append(current_batch)
+    return batches

autopkg_wrapper/utils/recipe_ordering.py

@@ -0,0 +1,149 @@
+import logging
+
+
+def order_recipe_list(recipe_list, order):
+    # This option comes in handy if you include additional recipe type names in your overrides and wish them to be processed in a specific order.
+    # We'll specifically look for these recipe types after the first period (.) in the recipe name.
+    # For example, if you have the following recipes to be processed:
+    #     ExampleApp.auto_install.jamf
+    #     ExampleApp.upload.jamf
+    #     ExampleApp.self_service.jamf
+    # And you want to ensure that the .upload recipes are always processed first, followed by .auto_install, and finally .self_service, you would provide the following processing order:
+    #     `--recipe-processing-order upload.jamf auto_install.jamf self_service.jamf`
+    # This would ensure that all .upload recipes are processed before any other recipe types.
+    # Within each recipe type, the recipes will be ordered alphabetically.
+    # We assume that no extensions are provided (but will strip them if needed - extensions that are stripped include .recipe or .recipe.yaml).
+
+    def strip_known_extensions(value: str) -> str:
+        value = value.strip()
+        if value.endswith(".recipe.yaml"):
+            return value[: -len(".recipe.yaml")]
+        if value.endswith(".recipe"):
+            return value[: -len(".recipe")]
+        return value
+
+    def normalise_processing_order(value):
+        if not value:
+            return []
+
+        items: list[str] = []
+        if isinstance(value, str):
+            raw = value.strip()
+            if not raw:
+                return []
+            # String values generally come from env var defaults; treat as comma-separated.
+            items = [v.strip() for v in raw.split(",")]
+        else:
+            # argparse typically provides a list here, but env var defaults can leak through.
+            for v in value:
+                if v is None:
+                    continue
+                v = str(v).strip()
+                if not v:
+                    continue
+                if "," in v:
+                    items.extend([p.strip() for p in v.split(",")])
+                else:
+                    items.append(v)
+
+        normalised: list[str] = []
+        seen: set[str] = set()
+        for item in items:
+            if not item:
+                continue
+            item = item.lstrip(".")
+            item = strip_known_extensions(item)
+            if not item or item in seen:
+                continue
+            seen.add(item)
+            normalised.append(item)
+        return normalised
+
+    def recipe_type(recipe_name: str) -> str:
+        # Type is everything after the first '.' (e.g. Example.upload.jamf -> upload.jamf)
+        parts = recipe_name.split(".", 1)
+        return parts[1] if len(parts) == 2 else ""
+
+    def recipe_segments_after_first_dot(recipe_name: str) -> list[str]:
+        after_first = recipe_type(recipe_name)
+        return [p for p in after_first.split(".") if p] if after_first else []
+
+    def pattern_matches_segments(pattern: str, segments: list[str]) -> bool:
+        # Pattern can be a single token ("auto_update") or a dot-separated sequence
+        # ("upload.jamf", "auto_update.jamf", etc.).
+        if not pattern:
+            return False
+        pattern_parts = [p for p in pattern.split(".") if p]
+        if not pattern_parts:
+            return False
+
+        # Case-insensitive matching.
+        segments_norm = [s.casefold() for s in segments]
+        pattern_parts_norm = [p.casefold() for p in pattern_parts]
+
+        if len(pattern_parts_norm) == 1:
+            return pattern_parts_norm[0] in segments_norm
+
+        # Contiguous subsequence match.
+        for start in range(0, len(segments_norm) - len(pattern_parts_norm) + 1):
+            if (
+                segments_norm[start : start + len(pattern_parts_norm)]
+                == pattern_parts_norm
+            ):
+                return True
+        return False
+
+    if not recipe_list:
+        return recipe_list
+
+    normalised_order = normalise_processing_order(order)
+
+    # If the provided order contains no usable tokens, do not re-order.
+    # (We still strip known extensions, which is order-preserving.)
+    if not normalised_order:
+        return [
+            strip_known_extensions(str(r).strip()) for r in recipe_list if r is not None
+        ]
+
+    # First, normalise recipe names by stripping known extensions.
+    normalised_recipes: list[str] = []
+    for r in recipe_list:
+        if r is None:
+            continue
+        normalised_recipes.append(strip_known_extensions(str(r).strip()))
+
+    # If a processing order is supplied, match each recipe to the *first* pattern it satisfies.
+    # This supports both direct matches ("upload.jamf") and partial matches ("upload",
+    # "auto_update") against dot-separated segments after the first '.' in the recipe name.
+    pattern_groups: dict[str, list[str]] = {p: [] for p in normalised_order}
+    unmatched: list[str] = []
+
+    for r in normalised_recipes:
+        segments = recipe_segments_after_first_dot(r)
+        matched = False
+        for p in normalised_order:
+            if pattern_matches_segments(p, segments):
+                pattern_groups[p].append(r)
+                matched = True
+                break
+        if not matched:
+            unmatched.append(r)
+
+    ordered: list[str] = []
+    for p in normalised_order:
+        ordered.extend(sorted(pattern_groups[p], key=str.casefold))
+
+    # Remaining recipes: group by their full type string and order groups alphabetically,
+    # with empty-type last.
+    groups: dict[str, list[str]] = {}
+    for r in unmatched:
+        t = recipe_type(r)
+        groups.setdefault(t, []).append(r)
+
+    for t in sorted(groups.keys(), key=lambda x: (x == "", x.casefold())):
+        ordered.extend(sorted(groups[t], key=str.casefold))
+
+    logging.debug(f"Recipe processing order: {normalised_order}")
+    logging.debug(f"Ordered recipes: {ordered}")
+
+    return ordered