feat: add extra_files manifest field (bundle prebuilt files/binaries into the package)

A [[lambda.extra_files]] entry stages a prebuilt file or directory (src,
repo-root-relative; dest, package-root-relative; optional +x) into the package
source tree, so it ships in the zip and folds into the content hash. The
executable bit folds into the hash separately. Lets a lambda vendor CI-built
binaries / release trees while the tool stays free of download logic. Specs
with no extra_files hash byte-identically to before.

Author: antonbabenko

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v0.4.0 - 2026-06-21
+
+### Added
+- `extra_files` manifest field: bundle prebuilt files or directories into a lambda package alongside its source. Each `[[lambda.extra_files]]` entry has `src` (repo-root-relative, where CI materialized it - e.g. a digest-pinned binary or an extracted release tree), `dest` (package-root-relative), and an optional `executable` flag (sets +x on a file; ignored for directories, which keep source perms). The bytes fold into the content hash via the staged source tree, and the executable bit folds in separately, so flipping it changes the artifact hash even when bytes are identical. This lets a lambda ship vendored CLIs or release trees the consumer's CI downloads and verifies, while the tool itself stays free of any network/tool-download logic. Paths are validated as relative and `..`-free. Specs without `extra_files` hash byte-identically to before.
+
 ## v0.3.0 - 2026-06-21
 
 ### Added

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "repro-lambda"
-version = "0.3.0"
+version = "0.4.0"
 description = "Build reproducible AWS Lambda packages outside Terraform, optimized for terraform-aws-lambda by serverless.tf."
 readme = "README.md"
 requires-python = ">=3.11"

src/repro_lambda/__init__.py

@@ -1,3 +1,3 @@
 """repro-lambda — reproducible AWS Lambda packaging outside Terraform."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

src/repro_lambda/build.py

@@ -75,6 +75,7 @@ def compute_sha_for(
             builder=builder,
             stage_dir=stage_dir,
             extra_files=extras,
+            payload_files=list(spec.extra_files),
         )
         return compute_content_hash(
             staged_source_root=stage_dir / "source",
@@ -83,6 +84,7 @@ def compute_sha_for(
             base_image=primary_base_image,
             builder_version=__version__,
             extra_files=extras,
+            payload_exec=[(ef.dest, ef.executable) for ef in spec.extra_files],
         )
 
 
@@ -113,6 +115,7 @@ def build_one(
             builder=builder,
             stage_dir=stage_dir,
             extra_files=extras,
+            payload_files=list(spec.extra_files),
         )
 
         sha = compute_content_hash(
@@ -122,6 +125,7 @@ def build_one(
             base_image=primary_base_image,
             builder_version=__version__,
             extra_files=extras,
+            payload_exec=[(ef.dest, ef.executable) for ef in spec.extra_files],
         )
         bucket_key = f"lambdas/{spec.logical_name}/{sha}.zip"
 

src/repro_lambda/hasher.py

@@ -24,6 +24,7 @@ def compute_content_hash(
     builder_version: str,
     *,
     extra_files: list[tuple[Path, str]] | None = None,
+    payload_exec: list[tuple[str, bool]] | None = None,
 ) -> str:
     """
     sha256 over: sorted (relative-path, sha256(content)) tuples for the staged tree
@@ -72,4 +73,13 @@ def compute_content_hash(
             h.update(_sha256_file(src).encode("ascii"))
             h.update(b"\n")
 
+    # Payload extra_files (prebuilt binaries/trees) are already hashed by content
+    # via the staged source tree above; fold in their executable bit here so that
+    # flipping +x changes the artifact hash even when bytes are unchanged. Omitted
+    # entirely when empty, preserving byte-identical hashes for specs with none.
+    if payload_exec:
+        h.update(b"---payload-exec---\n")
+        for dest, executable in sorted(payload_exec):
+            h.update(f"{dest}={int(executable)}\n".encode())
+
     return h.hexdigest()

src/repro_lambda/manifest.py

@@ -17,6 +17,24 @@
 SUPPORTED_PACKAGE_MANAGERS = {"pip", "npm"}
 
 
+@dataclass(frozen=True)
+class ExtraFile:
+    """A prebuilt file or directory staged into the package alongside the source.
+
+    `src` is relative to the repo root (where the caller's CI materialized it, e.g.
+    a downloaded + digest-pinned binary or an extracted release tree). `dest` is
+    where it lands in the package (relative to the package root). For a file,
+    `executable` sets the +x bit; for a directory, source perms are preserved and
+    `executable` is ignored. The bytes fold into the content hash via the staged
+    source tree; the executable flag folds in separately, so flipping it changes
+    the artifact hash even when bytes are unchanged.
+    """
+
+    src: str
+    dest: str
+    executable: bool = False
+
+
 @dataclass(frozen=True)
 class LambdaSpec:
     logical_name: str
@@ -30,6 +48,7 @@ class LambdaSpec:
     lambda_at_edge: bool = False
     hash_extra: str = ""
     package_json: str = ""
+    extra_files: tuple[ExtraFile, ...] = ()
 
     @property
     def resolved_requirements_lock(self) -> str:
@@ -63,6 +82,26 @@ class Manifest:
     builder: BuilderConfig
 
 
+def _parse_extra_files(path: Path, entry: dict) -> tuple[ExtraFile, ...]:
+    """Parse + validate a lambda's optional [[lambda.extra_files]] entries."""
+    parsed: list[ExtraFile] = []
+    for ef in entry.get("extra_files", []):
+        src = ef.get("src", "")
+        dest = ef.get("dest", "")
+        if not src or not dest:
+            raise ValueError(
+                f"{path}: extra_files entry requires non-empty 'src' and 'dest' (got {ef!r})"
+            )
+        for field_name, value in (("src", src), ("dest", dest)):
+            if value.startswith("/") or ".." in Path(value).parts:
+                raise ValueError(
+                    f"{path}: extra_files {field_name}={value!r} must be a relative path "
+                    f"without '..' (src is repo-root-relative, dest is package-root-relative)"
+                )
+        parsed.append(ExtraFile(src=src, dest=dest, executable=bool(ef.get("executable", False))))
+    return tuple(parsed)
+
+
 def load_manifest(path: Path) -> Manifest:
     """Parse lambdas.toml and validate semantic invariants."""
     with path.open("rb") as f:
@@ -119,6 +158,8 @@ def load_manifest(path: Path) -> Manifest:
                 f"point it at the lambda's package.json relative to repo root"
             )
 
+        extra_files = _parse_extra_files(path, entry)
+
         lambdas.append(
             LambdaSpec(
                 logical_name=entry["logical_name"],
@@ -132,6 +173,7 @@ def load_manifest(path: Path) -> Manifest:
                 package_manager=pkg,
                 lambda_at_edge=bool(entry.get("lambda_at_edge", False)),
                 hash_extra=entry.get("hash_extra", ""),
+                extra_files=extra_files,
             )
         )
 

src/repro_lambda/source_stager.py

@@ -7,7 +7,7 @@
 import subprocess
 from pathlib import Path
 
-from repro_lambda.manifest import BuilderConfig
+from repro_lambda.manifest import BuilderConfig, ExtraFile
 
 
 def _git_ls_files(repo_root: Path, source_dir: str) -> list[str]:
@@ -37,20 +37,46 @@ def _filter_paths(paths: list[str], include: list[str], exclude: list[str]) -> l
     return kept
 
 
+def _stage_payload_files(
+    repo_root: Path, target_root: Path, payload_files: list[ExtraFile]
+) -> None:
+    """Stage prebuilt files/dirs (CI-materialized, not git-tracked) into the package.
+
+    Each lands at target_root/<dest> (the staged source tree, so it ships in the zip
+    and folds into the content hash). Files get the +x bit when `executable`; dirs
+    are copied recursively with source perms preserved.
+    """
+    for ef in payload_files:
+        src = repo_root / ef.src
+        dest = target_root / ef.dest
+        if src.is_dir():
+            shutil.copytree(src, dest, dirs_exist_ok=True)
+        elif src.is_file():
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src, dest)
+            if ef.executable:
+                dest.chmod(dest.stat().st_mode | 0o111)
+        else:
+            raise FileNotFoundError(f"extra_files src not found: {src} (declared src={ef.src!r})")
+
+
 def stage_source(
     repo_root: Path,
     source_dir: str,
     builder: BuilderConfig,
     stage_dir: Path,
     *,
     extra_files: list[tuple[Path, str]] | None = None,
+    payload_files: list[ExtraFile] | None = None,
 ) -> list[str]:
     """
     Copy git-tracked files under source_dir into stage_dir/source/, preserving perms.
 
-    Optionally copy additional files (outside source_dir) directly into stage_dir.
-    Each entry in extra_files is (src_path, rel_name) where rel_name is the
-    destination path relative to stage_dir (not stage_dir/source/).
+    `extra_files` are build inputs (e.g. the requirements lock) copied to
+    stage_dir/<rel_name> - consumed by the container, not shipped in the zip.
+
+    `payload_files` are prebuilt artifacts copied into stage_dir/source/<dest> so
+    they ship in the zip and fold into the content hash.
 
     Returns the sorted list of relative paths (from repo_root) that were staged.
     """
@@ -71,6 +97,8 @@ def stage_source(
         if src_mode & 0o111:
             dst.chmod(dst.stat().st_mode | 0o111)
 
+    _stage_payload_files(repo_root, target_root, payload_files or [])
+
     for src_path, rel_name in extra_files or []:
         if not src_path.is_file():
             raise FileNotFoundError(f"extra_files source not found: {src_path}")