repro-lambda 0.1.0__py3-none-any.whl

repro_lambda/__init__.py

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

repro_lambda/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m repro_lambda ...` invocation."""
+
+from repro_lambda.cli import app
+
+if __name__ == "__main__":
+    app()

repro_lambda/build.py

@@ -0,0 +1,141 @@
+"""Orchestrate stage -> hash -> probe -> build -> upload -> catalog for one lambda."""
+
+from __future__ import annotations
+
+import enum
+import tempfile
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from repro_lambda import __version__
+from repro_lambda.catalog import Catalog, CatalogEntry
+from repro_lambda.docker_runner import build_python_lambda
+from repro_lambda.hasher import compute_content_hash
+from repro_lambda.manifest import BuilderConfig, LambdaSpec
+from repro_lambda.s3_uploader import S3Uploader, UploadResult
+from repro_lambda.source_stager import stage_source
+
+
+class BuildResult(enum.Enum):
+    CACHE_HIT = "cache_hit"
+    BUILT_AND_UPLOADED = "built_and_uploaded"
+    DRY_RUN = "dry_run"
+
+
+@dataclass
+class BuildOutcome:
+    outcome: BuildResult
+    sha256: str
+    bucket_key: str
+
+
+def _bucket_for(spec: LambdaSpec, base_bucket: str) -> str:
+    if spec.region == "us-east-1":
+        return f"{base_bucket}-us-east-1"
+    return base_bucket
+
+
+def compute_sha_for(
+    *,
+    repo_root: Path,
+    spec: LambdaSpec,
+    builder: BuilderConfig,
+) -> str:
+    """Stage source and compute the content hash; tempdir disposed on exit."""
+    with tempfile.TemporaryDirectory(prefix="repro-lambda-") as td:
+        stage_dir = Path(td)
+        stage_source(
+            repo_root=repo_root,
+            source_dir=spec.source_dir,
+            builder=builder,
+            stage_dir=stage_dir,
+        )
+        lock_path = repo_root / spec.resolved_requirements_lock
+        if not lock_path.exists():
+            raise FileNotFoundError(f"requirements lock not found: {lock_path}")
+        return compute_content_hash(
+            staged_source_root=stage_dir / "source",
+            requirements_lock=lock_path,
+            spec=spec,
+            base_image=builder.base_image_python,
+            builder_version=__version__,
+        )
+
+
+def build_one(
+    *,
+    repo_root: Path,
+    spec: LambdaSpec,
+    builder: BuilderConfig,
+    bucket: str,
+    catalog: Catalog,
+    source_commit: str,
+    dry_run: bool = False,
+) -> BuildOutcome:
+    """Build one lambda end-to-end. Returns BuildOutcome with sha + cache verdict."""
+    target_bucket = _bucket_for(spec, bucket)
+
+    with tempfile.TemporaryDirectory(prefix="repro-lambda-") as td:
+        stage_dir = Path(td)
+        stage_source(
+            repo_root=repo_root,
+            source_dir=spec.source_dir,
+            builder=builder,
+            stage_dir=stage_dir,
+        )
+        lock_path = repo_root / spec.resolved_requirements_lock
+        sha = compute_content_hash(
+            staged_source_root=stage_dir / "source",
+            requirements_lock=lock_path,
+            spec=spec,
+            base_image=builder.base_image_python,
+            builder_version=__version__,
+        )
+        bucket_key = f"lambdas/{spec.logical_name}/{sha}.zip"
+
+        if dry_run:
+            return BuildOutcome(BuildResult.DRY_RUN, sha, bucket_key)
+
+        uploader = S3Uploader(region=spec.region)
+        if uploader.exists(bucket=target_bucket, key=bucket_key):
+            _record(catalog, spec, sha, source_commit, builder)
+            return BuildOutcome(BuildResult.CACHE_HIT, sha, bucket_key)
+
+        out_zip = stage_dir / "lambda.zip"
+        (stage_dir / "requirements.lock").write_bytes(lock_path.read_bytes())
+        build_python_lambda(
+            stage_dir=stage_dir,
+            out_zip=out_zip,
+            base_image=builder.base_image_python,
+            arch=spec.arch,
+            python_version=spec.runtime.removeprefix("python"),
+        )
+
+        result = uploader.upload(bucket=target_bucket, key=bucket_key, body_path=out_zip)
+        assert result in {UploadResult.UPLOADED, UploadResult.ALREADY_PRESENT}
+
+        _record(catalog, spec, sha, source_commit, builder)
+        return BuildOutcome(BuildResult.BUILT_AND_UPLOADED, sha, bucket_key)
+
+
+def _record(
+    catalog: Catalog,
+    spec: LambdaSpec,
+    sha: str,
+    source_commit: str,
+    builder: BuilderConfig,
+) -> None:
+    catalog.record(
+        spec.logical_name,
+        CatalogEntry(
+            sha256=sha,
+            source_commit=source_commit,
+            runtime=spec.runtime,
+            arch=spec.arch,
+            region=spec.region,
+            builder_version=__version__,
+            base_image_digest=builder.base_image_python.split("@", 1)[-1],
+            built_at=datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        ),
+    )

repro_lambda/catalog.py

@@ -0,0 +1,71 @@
+"""builds/catalog.json — bounded per-lambda build history committed to source repo."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+SCHEMA_VERSION = 1
+MAX_HISTORY = 10
+
+
+@dataclass
+class CatalogEntry:
+    sha256: str
+    source_commit: str
+    runtime: str
+    arch: str
+    region: str
+    builder_version: str
+    base_image_digest: str
+    built_at: str  # ISO-8601 UTC, e.g. "2026-05-27T09:30:00Z"
+
+
+@dataclass
+class LambdaCatalog:
+    current: str
+    history: list[CatalogEntry] = field(default_factory=list)
+
+
+@dataclass
+class Catalog:
+    lambdas: dict[str, LambdaCatalog]
+
+    def record(self, logical_name: str, entry: CatalogEntry) -> None:
+        lc = self.lambdas.get(logical_name)
+        if lc is None:
+            self.lambdas[logical_name] = LambdaCatalog(current=entry.sha256, history=[entry])
+            return
+        if lc.current == entry.sha256:
+            return
+        lc.history.insert(0, entry)
+        lc.current = entry.sha256
+        lc.history = lc.history[:MAX_HISTORY]
+
+    def save(self, path: Path) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "schema_version": SCHEMA_VERSION,
+            "lambdas": {
+                name: {
+                    "current": lc.current,
+                    "history": [asdict(e) for e in lc.history],
+                }
+                for name, lc in self.lambdas.items()
+            },
+        }
+        path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n")
+
+
+def load_catalog(path: Path) -> Catalog:
+    if not path.exists():
+        return Catalog(lambdas={})
+    raw = json.loads(path.read_text())
+    if raw.get("schema_version") != SCHEMA_VERSION:
+        raise ValueError(f"{path}: unsupported schema_version {raw.get('schema_version')!r}")
+    lambdas: dict[str, LambdaCatalog] = {}
+    for name, lc in raw.get("lambdas", {}).items():
+        history = [CatalogEntry(**e) for e in lc.get("history", [])]
+        lambdas[name] = LambdaCatalog(current=lc["current"], history=history)
+    return Catalog(lambdas=lambdas)

repro_lambda/cli.py

@@ -0,0 +1,219 @@
+"""repro-lambda CLI entrypoint."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from repro_lambda import __version__
+
+app = typer.Typer(
+    name="repro-lambda",
+    help="Build reproducible AWS Lambda packages outside Terraform.",
+    no_args_is_help=True,
+)
+
+
+ARCH_TO_UV_PLATFORM = {
+    "arm64": "aarch64-manylinux_2_28",
+    "x86_64": "x86_64-manylinux_2_28",
+}
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            help="Show version and exit.",
+            callback=_version_callback,
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    """Top-level callback. The --version flag is the only global option."""
+    _ = version
+
+
+@app.command()
+def build(
+    target: Annotated[str, typer.Argument(help="Lambda logical_name or 'all'.")] = "all",
+    manifest: Annotated[
+        Path,
+        typer.Option("--manifest", "-m", help="Path to lambdas.toml."),
+    ] = Path("lambdas.toml"),
+    bucket: Annotated[
+        str,
+        typer.Option(
+            "--bucket",
+            envvar="REPRO_LAMBDA_BUCKET",
+            help="Base S3 bucket name (us-east-1 variant auto-derived).",
+        ),
+    ] = "",
+    verify: Annotated[bool, typer.Option("--verify")] = False,
+    dry_run: Annotated[bool, typer.Option("--dry-run")] = False,
+    allow_dirty: Annotated[bool, typer.Option("--allow-dirty")] = False,
+) -> None:
+    """Build one lambda (or all) per manifest and upload to S3."""
+    import json
+
+    from repro_lambda.build import build_one
+    from repro_lambda.catalog import load_catalog
+    from repro_lambda.git_guard import DirtyWorktreeError, ensure_clean_worktree
+    from repro_lambda.manifest import load_manifest
+
+    repo_root = manifest.parent.resolve()
+    parsed = load_manifest(manifest)
+
+    selected = (
+        parsed.lambdas
+        if target == "all"
+        else [s for s in parsed.lambdas if s.logical_name == target]
+    )
+    if not selected:
+        typer.echo(f"no lambda named {target!r} in {manifest}", err=True)
+        raise typer.Exit(2)
+
+    if not dry_run and not bucket:
+        typer.echo(
+            "--bucket or REPRO_LAMBDA_BUCKET env var is required for non-dry-run",
+            err=True,
+        )
+        raise typer.Exit(2)
+
+    for spec in selected:
+        try:
+            ensure_clean_worktree(
+                repo_root=repo_root,
+                source_dir=spec.source_dir,
+                allow_dirty=allow_dirty,
+            )
+        except DirtyWorktreeError as e:
+            typer.echo(str(e), err=True)
+            raise typer.Exit(2) from e
+
+    catalog_path = repo_root / "builds" / "catalog.json"
+    catalog = load_catalog(catalog_path)
+
+    try:
+        source_commit = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=repo_root,
+            check=True,
+            capture_output=True,
+            text=True,
+        ).stdout.strip()
+    except subprocess.CalledProcessError:
+        source_commit = "unknown"
+
+    summary = []
+    for spec in selected:
+        outcome = build_one(
+            repo_root=repo_root,
+            spec=spec,
+            builder=parsed.builder,
+            bucket=bucket or "dry-run",
+            catalog=catalog,
+            source_commit=source_commit,
+            dry_run=dry_run,
+        )
+        summary.append(
+            {
+                "logical_name": spec.logical_name,
+                "outcome": outcome.outcome.value,
+                "sha256": outcome.sha256,
+                "bucket_key": outcome.bucket_key,
+            }
+        )
+
+    if verify:
+        from repro_lambda.verify import ReproducibilityError, verify_reproducible
+
+        for spec in selected:
+            try:
+                sha_a, _sha_b = verify_reproducible(
+                    repo_root=repo_root,
+                    spec=spec,
+                    builder=parsed.builder,
+                )
+                typer.echo(f"verify {spec.logical_name}: reproducible (sha={sha_a})")
+            except ReproducibilityError as e:
+                typer.echo(f"verify {spec.logical_name}: FAILED — {e}", err=True)
+                raise typer.Exit(1) from e
+
+    if not dry_run:
+        catalog.save(catalog_path)
+
+    typer.echo(json.dumps(summary, indent=2))
+
+
+@app.command()
+def lock(
+    manifest: Annotated[Path, typer.Option("--manifest", "-m")] = Path("lambdas.toml"),
+) -> None:
+    """Regenerate per-arch requirements.${arch}.lock files via `uv pip compile`."""
+    from repro_lambda.manifest import load_manifest
+
+    parsed = load_manifest(manifest)
+    repo_root = manifest.parent.resolve()
+
+    for spec in parsed.lambdas:
+        requirements_in = repo_root / spec.source_dir / "requirements.in"
+        if not requirements_in.exists():
+            typer.echo(f"skip {spec.logical_name}: no {requirements_in}", err=True)
+            continue
+        lock_path = repo_root / spec.resolved_requirements_lock
+        uv_platform = ARCH_TO_UV_PLATFORM[spec.arch]
+        py_version = spec.runtime.removeprefix("python")
+        cmd = [
+            "uv",
+            "pip",
+            "compile",
+            str(requirements_in),
+            "--python-version",
+            py_version,
+            "--python-platform",
+            uv_platform,
+            "--generate-hashes",
+            "-o",
+            str(lock_path),
+        ]
+        result = subprocess.run(cmd, check=False, capture_output=True, text=True)
+        if result.returncode != 0:
+            typer.echo(f"lock {spec.logical_name} failed: {result.stderr}", err=True)
+            raise typer.Exit(result.returncode)
+        typer.echo(f"lock {spec.logical_name}: wrote {lock_path}")
+
+
+@app.command()
+def init() -> None:
+    """Scaffold lambdas.toml and CI caller workflow."""
+    typer.echo("init stub")
+    raise typer.Exit(0)
+
+
+def _zip_impl(src: Path, out: Path) -> None:
+    """Pack a directory into a deterministic zip (used inside container)."""
+    from repro_lambda.zip_packager import pack_directory
+
+    pack_directory(src, out)
+
+
+@app.command(name="zip")
+def zip_(
+    src: Annotated[Path, typer.Option("--src", help="Staged package directory.")],
+    out: Annotated[Path, typer.Option("--out", help="Output zip path.")],
+) -> None:
+    """Pack a directory into a deterministic zip (used inside container)."""
+    _zip_impl(src, out)
+    raise typer.Exit(0)

repro_lambda/docker_runner.py

@@ -0,0 +1,122 @@
+"""Run pip install + cleanup + zip inside a digest-pinned Docker container."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+ARCH_TO_DOCKER_PLATFORM: dict[str, str] = {
+    "arm64": "linux/arm64",
+    "x86_64": "linux/amd64",
+}
+
+ARCH_TO_PIP_PLATFORM: dict[str, str] = {
+    "arm64": "manylinux_2_28_aarch64",
+    "x86_64": "manylinux_2_28_x86_64",
+}
+
+
+class DockerRunError(RuntimeError):
+    pass
+
+
+_CONTAINER_SCRIPT = r"""
+set -euxo pipefail
+PKG=/build/pkg
+mkdir -p "$PKG"
+
+pip install \
+  --no-cache-dir --no-compile \
+  --require-hashes --only-binary=:all: \
+  --platform "$PIP_PLATFORM" \
+  --python-version "$PY_VERSION" \
+  --implementation cp --abi "cp${PY_VERSION//./}" \
+  --target "$PKG" \
+  -r /src/requirements.lock
+
+find "$PKG" -depth -type d -name "__pycache__" -exec rm -rf {} +
+find "$PKG" -type f -name "*.pyc" -delete
+find "$PKG" -type d -name "*.dist-info" -exec sh -c \
+  'rm -f "$1/RECORD" "$1/INSTALLER" "$1/direct_url.json"' _ {} \;
+
+cp -R /src/source/. "$PKG/"
+
+python -m repro_lambda zip --src "$PKG" --out /out/lambda.zip
+"""
+
+
+def _builder_module_root() -> Path:
+    """Return the on-host directory containing the installed repro_lambda package."""
+    import repro_lambda
+
+    return Path(repro_lambda.__file__).parent.parent
+
+
+def build_python_lambda(
+    *,
+    stage_dir: Path,
+    out_zip: Path,
+    base_image: str,
+    arch: str,
+    python_version: str,
+) -> None:
+    """
+    Docker-run pip install + cleanup + zip in a digest-pinned container, mounting
+    the host-staged source and the host-side repro_lambda package read-only.
+
+    Mounts:
+      stage_dir         -> /src        (ro)  must contain source/ + requirements.lock
+      builder_root      -> /builder    (ro)  PYTHONPATH so `python -m repro_lambda` resolves
+      out_dir(out_zip)  -> /out        (rw)  destination for lambda.zip
+    """
+    if arch not in ARCH_TO_DOCKER_PLATFORM:
+        raise DockerRunError(
+            f"unsupported arch {arch!r}; supported: {list(ARCH_TO_DOCKER_PLATFORM)}"
+        )
+    if shutil.which("docker") is None:
+        raise DockerRunError("docker CLI not found on PATH")
+
+    docker_platform = ARCH_TO_DOCKER_PLATFORM[arch]
+    pip_platform = ARCH_TO_PIP_PLATFORM[arch]
+
+    out_dir = out_zip.parent
+    out_dir.mkdir(parents=True, exist_ok=True)
+    builder_root = _builder_module_root()
+
+    cmd = [
+        "docker",
+        "run",
+        "--rm",
+        "--platform",
+        docker_platform,
+        "-v",
+        f"{stage_dir}:/src:ro",
+        "-v",
+        f"{builder_root}:/builder:ro",
+        "-v",
+        f"{out_dir}:/out",
+        "-e",
+        "PYTHONPATH=/builder",
+        "-e",
+        f"PIP_PLATFORM={pip_platform}",
+        "-e",
+        f"PY_VERSION={python_version}",
+        "--entrypoint",
+        "bash",
+        base_image,
+        "-euxc",
+        _CONTAINER_SCRIPT,
+    ]
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise DockerRunError(
+            f"docker build failed (exit {result.returncode}):\n"
+            f"--- stderr ---\n{result.stderr}\n"
+            f"--- stdout ---\n{result.stdout}\n"
+        )
+
+    produced = out_dir / "lambda.zip"
+    if produced != out_zip:
+        produced.rename(out_zip)

repro_lambda/git_guard.py

@@ -0,0 +1,39 @@
+"""Refuse to build with uncommitted tracked changes (unless --allow-dirty)."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+class DirtyWorktreeError(RuntimeError):
+    """Raised when source_dir has uncommitted tracked changes."""
+
+
+def ensure_clean_worktree(
+    *,
+    repo_root: Path,
+    source_dir: str,
+    allow_dirty: bool = False,
+) -> None:
+    if allow_dirty:
+        return
+    result = subprocess.run(
+        [
+            "git",
+            "status",
+            "--porcelain",
+            "--untracked-files=no",
+            "--",
+            source_dir,
+        ],
+        cwd=repo_root,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    if result.stdout.strip():
+        raise DirtyWorktreeError(
+            f"Uncommitted changes in {source_dir}:\n{result.stdout}"
+            "Commit or pass --allow-dirty for local iteration."
+        )

repro_lambda/hasher.py

@@ -0,0 +1,56 @@
+"""Compute the content hash that keys S3 artifacts and decides cache reuse."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from repro_lambda.manifest import LambdaSpec
+
+
+def _sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(64 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def compute_content_hash(
+    staged_source_root: Path,
+    requirements_lock: Path,
+    spec: LambdaSpec,
+    base_image: str,
+    builder_version: str,
+) -> str:
+    """
+    sha256 over: sorted (relative-path, sha256(content)) tuples for the staged tree
+    + sha256(requirements_lock) + spec scalars + base_image + builder_version.
+
+    Inputs are concatenated with newline separators in a fixed order, then hashed.
+    """
+    h = hashlib.sha256()
+
+    files = sorted(p for p in staged_source_root.rglob("*") if p.is_file())
+    for f in files:
+        rel = f.relative_to(staged_source_root).as_posix()
+        h.update(rel.encode("utf-8"))
+        h.update(b"\x00")
+        h.update(_sha256_file(f).encode("ascii"))
+        h.update(b"\n")
+
+    h.update(b"---\n")
+    h.update(_sha256_file(requirements_lock).encode("ascii"))
+    h.update(b"\n")
+
+    h.update(f"runtime={spec.runtime}\n".encode())
+    h.update(f"arch={spec.arch}\n".encode())
+    h.update(f"handler={spec.handler}\n".encode())
+    h.update(f"region={spec.region}\n".encode())
+    h.update(f"package_manager={spec.package_manager}\n".encode())
+    h.update(f"lambda_at_edge={int(spec.lambda_at_edge)}\n".encode())
+    h.update(f"hash_extra={spec.hash_extra}\n".encode())
+    h.update(f"base_image={base_image}\n".encode())
+    h.update(f"builder_version={builder_version}\n".encode())
+
+    return h.hexdigest()

repro_lambda/manifest.py

@@ -0,0 +1,110 @@
+"""Parse and validate lambdas.toml."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+SUPPORTED_RUNTIMES = {"python3.11", "python3.12", "python3.13"}
+SUPPORTED_ARCHS: tuple[str, ...] = ("arm64", "x86_64")
+SUPPORTED_PACKAGE_MANAGERS = {"pip"}  # v0.1 — Node.js arrives in v0.2
+
+
+@dataclass(frozen=True)
+class LambdaSpec:
+    logical_name: str
+    source_dir: str
+    requirements_lock: str  # template with ${arch} placeholder
+    runtime: str
+    arch: str
+    handler: str
+    region: str = "eu-west-1"
+    package_manager: str = "pip"
+    lambda_at_edge: bool = False
+    hash_extra: str = ""
+
+    @property
+    def resolved_requirements_lock(self) -> str:
+        return self.requirements_lock.replace("${arch}", self.arch)
+
+
+@dataclass(frozen=True)
+class BuilderConfig:
+    base_image_python: str
+    include_patterns: list[str] = field(default_factory=lambda: ["**/*.py", "**/*.json"])
+    exclude_patterns: list[str] = field(
+        default_factory=lambda: [
+            ".venv/**",
+            ".pytest_cache/**",
+            "__pycache__/**",
+            "*.pyc",
+            ".git/**",
+            ".env*",
+        ]
+    )
+
+
+@dataclass(frozen=True)
+class Manifest:
+    lambdas: list[LambdaSpec]
+    builder: BuilderConfig
+
+
+def load_manifest(path: Path) -> Manifest:
+    """Parse lambdas.toml and validate semantic invariants."""
+    with path.open("rb") as f:
+        raw = tomllib.load(f)
+
+    if "lambda" not in raw or not raw["lambda"]:
+        raise ValueError(f"{path}: must define at least one [[lambda]] entry")
+    if "builder" not in raw:
+        raise ValueError(f"{path}: missing [builder] section")
+
+    builder_raw = raw["builder"]
+    base_image = builder_raw.get("base_image_python", "")
+    if "@sha256:" not in base_image:
+        raise ValueError(
+            f"{path}: builder.base_image_python must be pinned by digest "
+            f"(got {base_image!r}; need image@sha256:<digest>)"
+        )
+
+    defaults = BuilderConfig(base_image_python=base_image)
+    builder = BuilderConfig(
+        base_image_python=base_image,
+        include_patterns=list(builder_raw.get("include_patterns", defaults.include_patterns)),
+        exclude_patterns=list(builder_raw.get("exclude_patterns", defaults.exclude_patterns)),
+    )
+
+    lambdas: list[LambdaSpec] = []
+    for entry in raw["lambda"]:
+        runtime = entry.get("runtime")
+        if runtime not in SUPPORTED_RUNTIMES:
+            raise ValueError(
+                f"{path}: unsupported runtime {runtime!r}; supported: {sorted(SUPPORTED_RUNTIMES)}"
+            )
+        arch = entry.get("arch")
+        if arch not in SUPPORTED_ARCHS:
+            raise ValueError(
+                f"{path}: unsupported arch {arch!r}; supported: {list(SUPPORTED_ARCHS)}"
+            )
+        pkg = entry.get("package_manager", "pip")
+        if pkg not in SUPPORTED_PACKAGE_MANAGERS:
+            raise ValueError(f"{path}: unsupported package_manager {pkg!r}; v0.1 supports pip only")
+
+        lambdas.append(
+            LambdaSpec(
+                logical_name=entry["logical_name"],
+                source_dir=entry["source_dir"],
+                requirements_lock=entry["requirements_lock"],
+                runtime=runtime,
+                arch=arch,
+                handler=entry["handler"],
+                region=entry.get("region", "eu-west-1"),
+                package_manager=pkg,
+                lambda_at_edge=bool(entry.get("lambda_at_edge", False)),
+                hash_extra=entry.get("hash_extra", ""),
+            )
+        )
+
+    return Manifest(lambdas=lambdas, builder=builder)

repro_lambda/s3_uploader.py

@@ -0,0 +1,53 @@
+"""Idempotent S3 upload helper that relies on bucket-policy immutability."""
+
+from __future__ import annotations
+
+import enum
+from pathlib import Path
+
+import boto3
+from botocore.exceptions import ClientError
+
+
+class UploadResult(enum.Enum):
+    UPLOADED = "uploaded"
+    ALREADY_PRESENT = "already_present"
+
+
+class S3Uploader:
+    def __init__(self, region: str, client=None) -> None:
+        self._client = client or boto3.client("s3", region_name=region)
+
+    def exists(self, *, bucket: str, key: str) -> bool:
+        try:
+            self._client.head_object(Bucket=bucket, Key=key)
+            return True
+        except ClientError as e:
+            code = e.response.get("Error", {}).get("Code", "")
+            if code in ("404", "NoSuchKey", "NotFound"):
+                return False
+            raise
+
+    def upload(self, *, bucket: str, key: str, body_path: Path) -> UploadResult:
+        """
+        PutObject with If-None-Match=*.
+
+        On 412 PreconditionFailed (key already exists) returns ALREADY_PRESENT.
+        Any other error is re-raised.
+        """
+        body = body_path.read_bytes()
+        try:
+            self._client.put_object(
+                Bucket=bucket,
+                Key=key,
+                Body=body,
+                IfNoneMatch="*",
+                ServerSideEncryption="AES256",
+            )
+            return UploadResult.UPLOADED
+        except ClientError as e:
+            code = e.response.get("Error", {}).get("Code", "")
+            status = e.response.get("ResponseMetadata", {}).get("HTTPStatusCode")
+            if code == "PreconditionFailed" or status == 412:
+                return UploadResult.ALREADY_PRESENT
+            raise

repro_lambda/source_stager.py

@@ -0,0 +1,68 @@
+"""Stage git-tracked source files into a tempdir before container build."""
+
+from __future__ import annotations
+
+import fnmatch
+import shutil
+import subprocess
+from pathlib import Path
+
+from repro_lambda.manifest import BuilderConfig
+
+
+def _git_ls_files(repo_root: Path, source_dir: str) -> list[str]:
+    """Return paths of all tracked files under source_dir, relative to repo_root."""
+    result = subprocess.run(
+        ["git", "ls-files", "--cached", "-z", "--", source_dir],
+        cwd=repo_root,
+        check=True,
+        capture_output=True,
+    )
+    raw = result.stdout.decode("utf-8")
+    return [p for p in raw.split("\x00") if p]
+
+
+def _matches_any(path: str, patterns: list[str]) -> bool:
+    return any(fnmatch.fnmatch(path, p) for p in patterns)
+
+
+def _filter_paths(paths: list[str], include: list[str], exclude: list[str]) -> list[str]:
+    kept: list[str] = []
+    for p in paths:
+        if include and not _matches_any(p, include):
+            continue
+        if exclude and _matches_any(p, exclude):
+            continue
+        kept.append(p)
+    return kept
+
+
+def stage_source(
+    repo_root: Path,
+    source_dir: str,
+    builder: BuilderConfig,
+    stage_dir: Path,
+) -> list[str]:
+    """
+    Copy git-tracked files under source_dir into stage_dir/source/, preserving perms.
+
+    Returns the sorted list of relative paths (from repo_root) that were staged.
+    """
+    tracked = _git_ls_files(repo_root, source_dir)
+    filtered = _filter_paths(tracked, builder.include_patterns, builder.exclude_patterns)
+    filtered.sort()
+
+    target_root = stage_dir / "source"
+    target_root.mkdir(parents=True, exist_ok=True)
+
+    for rel in filtered:
+        src = repo_root / rel
+        rel_within_source = Path(rel).relative_to(source_dir)
+        dst = target_root / rel_within_source
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src, dst)
+        src_mode = src.stat().st_mode
+        if src_mode & 0o111:
+            dst.chmod(dst.stat().st_mode | 0o111)
+
+    return filtered

repro_lambda/verify.py

@@ -0,0 +1,61 @@
+"""Two-pass reproducibility check: build twice in isolated stage dirs, compare sha256."""
+
+from __future__ import annotations
+
+import hashlib
+import tempfile
+from pathlib import Path
+
+from repro_lambda.docker_runner import build_python_lambda
+from repro_lambda.manifest import BuilderConfig, LambdaSpec
+from repro_lambda.source_stager import stage_source
+
+
+class ReproducibilityError(RuntimeError):
+    pass
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(64 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def verify_reproducible(
+    *,
+    repo_root: Path,
+    spec: LambdaSpec,
+    builder: BuilderConfig,
+) -> tuple[str, str]:
+    """
+    Run the build twice in independent tempdirs and compare zip sha256.
+
+    Returns (sha_build_1, sha_build_2) on match. Raises ReproducibilityError on mismatch.
+    """
+    shas: list[str] = []
+    for _ in range(2):
+        with tempfile.TemporaryDirectory(prefix="repro-verify-") as td:
+            stage_dir = Path(td)
+            stage_source(
+                repo_root=repo_root,
+                source_dir=spec.source_dir,
+                builder=builder,
+                stage_dir=stage_dir,
+            )
+            lock_path = repo_root / spec.resolved_requirements_lock
+            (stage_dir / "requirements.lock").write_bytes(lock_path.read_bytes())
+            out_zip = stage_dir / "lambda.zip"
+            build_python_lambda(
+                stage_dir=stage_dir,
+                out_zip=out_zip,
+                base_image=builder.base_image_python,
+                arch=spec.arch,
+                python_version=spec.runtime.removeprefix("python"),
+            )
+            shas.append(_sha256(out_zip))
+
+    if shas[0] != shas[1]:
+        raise ReproducibilityError(f"two builds produced different zips: {shas[0]} vs {shas[1]}")
+    return shas[0], shas[1]

repro_lambda/zip_packager.py

@@ -0,0 +1,70 @@
+"""Pack a staged directory into a byte-reproducible zip."""
+
+from __future__ import annotations
+
+import fnmatch
+from pathlib import Path
+from zipfile import ZIP_DEFLATED, ZipFile, ZipInfo
+
+_EPOCH = (1980, 1, 1, 0, 0, 0)
+
+
+def _should_exclude(rel: str, exclude_glob: list[str]) -> bool:
+    return any(fnmatch.fnmatch(rel, pat) for pat in exclude_glob)
+
+
+def _zip_mode(path: Path) -> int:
+    src_mode = path.stat().st_mode
+    if path.is_dir():
+        return 0o755
+    if src_mode & 0o111 or path.suffix in {".so", ".node"}:
+        return 0o755
+    return 0o644
+
+
+def pack_directory(
+    src: Path,
+    out: Path,
+    *,
+    exclude_glob: list[str] | None = None,
+) -> None:
+    """
+    Pack `src` recursively into `out` as a deterministic zip.
+
+    Reproducibility properties set explicitly on every entry:
+      - Entries sorted alphabetically by POSIX relpath
+      - mtime forced to 1980-01-01 00:00:00
+      - Directory entries 0o755; files 0o644 (or 0o755 if executable / .so / .node)
+      - create_system = 3 (unix) so external_attr is interpreted as unix mode
+
+    Uses stdlib zipfile directly because repro_zipfile normalizes external_attr in a
+    way that strips per-file mode bits we need to preserve.
+    """
+    exclude_glob = exclude_glob or []
+
+    paths: list[Path] = []
+    for p in src.rglob("*"):
+        rel = p.relative_to(src).as_posix()
+        if _should_exclude(rel, exclude_glob):
+            continue
+        paths.append(p)
+
+    paths.sort(key=lambda p: p.relative_to(src).as_posix())
+
+    out.parent.mkdir(parents=True, exist_ok=True)
+    with ZipFile(out, "w", compression=ZIP_DEFLATED) as zf:
+        for p in paths:
+            rel = p.relative_to(src).as_posix()
+            zinfo = ZipInfo(
+                filename=(rel + "/") if p.is_dir() else rel,
+                date_time=_EPOCH,
+            )
+            zinfo.create_system = 3
+            mode = _zip_mode(p)
+            zinfo.external_attr = (mode & 0xFFFF) << 16
+            if p.is_dir():
+                zinfo.external_attr |= 0x10
+                data = b""
+            else:
+                data = p.read_bytes()
+            zf.writestr(zinfo, data)

repro_lambda-0.1.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: repro-lambda
+Version: 0.1.0
+Summary: Build reproducible AWS Lambda packages outside Terraform, optimized for terraform-aws-lambda by serverless.tf.
+Project-URL: Homepage, https://github.com/antonbabenko/repro-lambda
+Project-URL: Repository, https://github.com/antonbabenko/repro-lambda
+Project-URL: Issues, https://github.com/antonbabenko/repro-lambda/issues
+Author-email: Anton Babenko <anton@antonbabenko.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: aws,lambda,reproducible-builds,serverless,terraform
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Requires-Dist: boto3>=1.34
+Requires-Dist: repro-zipfile>=0.3.1
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: moto[s3]>=5; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# repro-lambda
+
+Build reproducible AWS Lambda packages outside Terraform, optimized for
+[terraform-aws-lambda by serverless.tf](https://registry.terraform.io/modules/terraform-aws-modules/lambda/aws/latest).
+
+Produces byte-identical zip files across local dev (macOS) and CI (Linux),
+uploads to S3 by content-hash key, and lets Terraform read `s3_existing_package`
+instead of building during `terraform plan`/`apply`.
+
+## Install
+
+    pip install repro-lambda
+
+## Usage
+
+    repro-lambda init           # scaffold lambdas.toml and CI caller workflow
+    repro-lambda lock           # regenerate per-arch lockfiles
+    repro-lambda build          # build all lambdas in lambdas.toml, upload to S3
+    repro-lambda build --verify # two-pass byte-reproducibility check
+
+See `docs/` for full design.
+
+## Release
+
+Releases are tag-driven. To cut v0.1.1:
+
+    git tag v0.1.1
+    git push origin v0.1.1
+
+The `publish.yml` workflow uses PyPI Trusted Publishing (OIDC) — no PyPI token
+needed in repo secrets. Configure once via PyPI's "Publishing" panel:
+
+- Owner: `antonbabenko`
+- Repository: `repro-lambda`
+- Workflow: `publish.yml`
+- Environment: (leave blank)

repro_lambda-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+repro_lambda/__init__.py,sha256=ZkpHpCqz2OfeNOU9veyWfnFUixyLeBt4HJZ2MH8CN8I,99
+repro_lambda/__main__.py,sha256=kj1fmZneM57F0kbNd_wNDyf2RfF3s2-LGyRArkN89eg,125
+repro_lambda/build.py,sha256=LaiiSEzikfefw9AKETHCzXeNMaY6TEm4x0MLi2Cr73k,4466
+repro_lambda/catalog.py,sha256=Gf15RyQqflgnSDCzQ1J7H0SoSI8ClzdNjWQGnYUmgpo,2146
+repro_lambda/cli.py,sha256=na_qWXHtXbhu3w_3LKhVJKYlWAnbHPdFMzMZ_OcRbeE,6545
+repro_lambda/docker_runner.py,sha256=NCPVt-HQqnVEaXlALDOKVgoBJ9-3tZmyesIDmqpFVAE,3287
+repro_lambda/git_guard.py,sha256=qNJ9AiD-OCBrO0EdEvZzAMNDxmoJZBSssxuJaYfEHGw,922
+repro_lambda/hasher.py,sha256=5UuM_fmpUewgbjH50EkEnMt2J6YeavNqITmvE16RBCY,1794
+repro_lambda/manifest.py,sha256=lnMTGAOpsEisZkz4fpUbx_9baxzIiKh11koFsNbL1y0,3642
+repro_lambda/s3_uploader.py,sha256=NgW9YJnODSx7VXfX5oEOsHAuQbLFmEnORx9xvP8Ivy0,1694
+repro_lambda/source_stager.py,sha256=cT4Ln5UAufQ9DzemLFbkU1JCDZKQ9Lx_VU7DtnyvlYY,2035
+repro_lambda/verify.py,sha256=g-NjbHrRXZXRIqlyWM-XlTqpX6_0csw43fXWHMbXBGs,1924
+repro_lambda/zip_packager.py,sha256=IPS0wNgFbGaZumOgnMTfLTRuudik2VYF468HPTPW7RM,2153
+repro_lambda-0.1.0.dist-info/METADATA,sha256=vR-i0w_mbOC7p9RxmNa-BCoB5tJcxwbcOUjPJK79wwU,2555
+repro_lambda-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+repro_lambda-0.1.0.dist-info/entry_points.txt,sha256=Ttp1Q08jEiPeuPo-kT2aKYM5STM-IPI4AGdXWXjGGRg,54
+repro_lambda-0.1.0.dist-info/licenses/LICENSE,sha256=3Bfccb39fnXN5VkSZh8RemjW03BH4JZkTEQgREhpFNU,9554
+repro_lambda-0.1.0.dist-info/RECORD,,

repro_lambda-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

repro_lambda-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+repro-lambda = repro_lambda.cli:app

repro_lambda-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,177 @@
+Apache License
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined in Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity exercising
+   permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or Object
+   form, made available under the License, as indicated by a copyright
+   notice that is included in or attached to the work (an example is
+   provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original Work and any Derivative Works thereof, that is intentionally
+   submitted to, or received by, Licensor for inclusion in the Work
+   by the copyright owner or by an individual or Legal Entity authorized
+   to submit on behalf of the copyright owner. For the purposes of this
+   definition, "submitted" means any form of electronic, verbal, or
+   written communication sent to the Licensor or its representatives,
+   including but not limited to communication on electronic mailing lists,
+   source code control systems, and issue tracking systems that are
+   managed by, or on behalf of, the Licensor for the purpose of
+   discussing and improving the Work, but excluding communication
+   that is conspicuously marked or otherwise designated in writing by
+   the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean any individual or Legal Entity on behalf
+   of whom a Contribution has been received by Licensor and subsequently
+   incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file, then any
+       Derivative Works that You distribute must include a readable
+       copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE from the Work, provided that
+       such additional attribution notices cannot be construed as
+       modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions of this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contribution.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS