repro-lambda 0.1.0__tar.gz → 0.2.1__tar.gz

{repro_lambda-0.1.0 → repro_lambda-0.2.1}/.github/workflows/build.yml

@@ -9,7 +9,7 @@ on:
         description: Path to lambdas.toml in the caller repo.
       repro_lambda_version:
         type: string
-        default: "0.1.0"
+        default: "0.2.1"
         description: Pinned repro-lambda PyPI version.
     secrets:
       aws-dev-role-arn:
@@ -55,9 +55,6 @@ jobs:
       - uses: actions/checkout@v4
       - uses: astral-sh/setup-uv@v3
 
-      - name: Install repro-lambda
-        run: uv pip install --system "repro-lambda==${{ inputs.repro_lambda_version }}"
-
       - name: Configure AWS credentials (dev)
         uses: aws-actions/configure-aws-credentials@v4
         with:
@@ -67,11 +64,11 @@ jobs:
       - name: Build (dev bucket)
         env:
           REPRO_LAMBDA_BUCKET: dev-ctf-lambda-artifacts
-        run: repro-lambda build --manifest "${{ inputs.manifest_path }}"
+        run: uvx --from "repro-lambda==${{ inputs.repro_lambda_version }}" repro-lambda build --manifest "${{ inputs.manifest_path }}"
 
       - name: Verify reproducible (PR only)
         if: github.event_name == 'pull_request'
-        run: repro-lambda build --manifest "${{ inputs.manifest_path }}" --verify --dry-run
+        run: uvx --from "repro-lambda==${{ inputs.repro_lambda_version }}" repro-lambda build --manifest "${{ inputs.manifest_path }}" --verify --dry-run
 
       - name: Configure AWS credentials (prod)
         if: github.ref == 'refs/heads/master' && secrets.aws-prod-role-arn != ''
@@ -84,7 +81,7 @@ jobs:
         if: github.ref == 'refs/heads/master' && secrets.aws-prod-role-arn != ''
         env:
           REPRO_LAMBDA_BUCKET: prod-ctf-lambda-artifacts
-        run: repro-lambda build --manifest "${{ inputs.manifest_path }}"
+        run: uvx --from "repro-lambda==${{ inputs.repro_lambda_version }}" repro-lambda build --manifest "${{ inputs.manifest_path }}"
 
       - name: Commit catalog drift (master only, dev bot)
         if: github.ref == 'refs/heads/master'

repro_lambda-0.2.1/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+## v0.2.1 - 2026-05-27
+
+### Changed
+- CI workflow: `uvx --from "repro-lambda==<v>" repro-lambda <args>` replaces `uv pip install --system "repro-lambda==<v>"`. uv 0.11+ deprecates the `uv pip` legacy interface for install/uninstall/sync.
+
+### Docs
+- README install instruction switches to `uv tool install repro-lambda` (plus `uvx repro-lambda` ephemeral alternative).
+- SETUP.md examples bumped to `@v0.2.1` / `repro_lambda_version: "0.2.1"`.
+
+### Consumer migration
+- Consumer repos must bump their workflow ref to `uses: antonbabenko/repro-lambda/.github/workflows/build.yml@v0.2.1` to receive the uvx-based install. The v0.2.0 workflow ref still works but invokes the deprecated install command.
+
+## v0.2.0 - 2026-05-27
+
+### Added
+- Node.js Lambda packaging (`nodejs20.x`, `nodejs22.x`) via `npm ci --omit=dev --ignore-scripts --cpu=${arch} --os=linux` in the digest-pinned Node base image.
+- Two-container Node build: install in the Node base image, pack the resulting `pkg/` directory inside the digest-pinned Python base image (the Python image's zlib is the only deflate implementation invoked, so macOS arm64 hosts and Linux x86_64 CI produce byte-identical output).
+- `BuilderConfig.base_image_nodejs` (required when any lambda uses `package_manager = "npm"`).
+- `LambdaSpec.package_json` (required for npm specs) + `package_json_resolved` property.
+- `ARCH_TO_NPM_CPU` mapping (`arm64` -> `arm64`, `x86_64` -> `x64`).
+- `build_nodejs_lambda` + `install_nodejs_dependencies` + `pack_in_python_sidecar` in `docker_runner`.
+- `stage_source(... extra_files=[(host_path, dest_relname), ...])` for staging artifacts outside `source_dir` (e.g. `package.json`, `package-lock.json`).
+- `compute_content_hash(... extra_files=...)` keyed by destination relname so npm `package.json` edits bump the cache key.
+- SETUP.md sections for Node.js + Lambda@Edge usage + caveats.
+- Docker-gated end-to-end Node.js reproducibility test (`test_e2e_nodejs_lambda.py`) using a `tslib@2.7.0` fixture.
+- Python byte-compat regression test (`test_python_byte_compat_regression.py`) pinning v0.1 zip output against a digest-pinned base image.
+
+### Changed
+- `build.py` and `verify.py` route per `spec.package_manager` (pip | npm). Both pre-stage source + extras BEFORE the cache-key hash so cache-hit and cache-miss branches see the same hash inputs.
+- `manifest.py` accepts `nodejs20.x` and `nodejs22.x` runtimes and `package_manager = "npm"`.
+- `lock` subcommand skips npm specs (npm uses package-lock.json directly; regenerate with `npm install` upstream).
+- `zip_packager.pack_directory` skips symlinks with a stderr warning (zip cannot preserve link semantics).
+- Docker `--user $(id -u):$(id -g)` on POSIX (skipped on Windows; `sys.platform == "win32"` gate).
+- `_PYTHON_INSTALL_SCRIPT` now declares the full pip platform quartet (`--platform`, `--abi`, `--python-version`, `--implementation`) and strips `REQUESTED` files alongside `RECORD` / `INSTALLER` / `direct_url.json`. Module-level invariance assert keeps `ARCH_TO_DOCKER_PLATFORM` / `ARCH_TO_PIP_PLATFORM` / `ARCH_TO_NPM_CPU` keys in lockstep.
+
+### Compatibility
+- v0.1 zip byte-output preserved (regression-tested by `test_python_byte_compat_regression.py` once the operator records the v0.1.0 reference sha against the pinned base image digest).
+- Content-hash key shifts ONCE at the v0.1 -> v0.2 cut-line because the lockfile is now hashed via the unified `extra_files` channel. v0.1-built zips remain pullable by their old keys (content-addressed S3 storage), so the shift only affects the next rebuild.
+
+### Known caveats
+- npm workspaces NOT supported (single `package.json` per Lambda only).
+- Native deps must ship a `linux-${arch}` binary via `optionalDependencies` in `package-lock.json`; npm cannot cross-compile native modules.
+- Symlinks inside `source_dir` are skipped (zip cannot preserve link semantics). Replace with file contents if your build relies on them.
+- Per-arch lockfiles remain Python-only.
+- Windows host: the `--user` flag is skipped; Docker Desktop's default user mapping applies.
+
+## v0.1.0 - 2026-05-27
+
+Initial public release.
+
+### Features
+
+- Python 3.11/3.12/3.13 Lambda packaging with `pip install --require-hashes`
+- Byte-reproducible zips via deterministic `zipfile.ZipFile` writes
+  (sorted entries, fixed mtime 1980-01-01, 0o755 dirs / 0o644 files / 0o755 executables)
+- Content-hash sha256 cache key (source tree + lockfile + spec + base image digest + builder version)
+- Idempotent S3 upload via `If-None-Match=*`, designed for bucket-policy-enforced immutability
+- `--verify` two-pass byte-reproducibility check
+- `--dry-run` for hash + catalog inspection
+- `--allow-dirty` for local iteration
+- `builds/catalog.json` with bounded 10-entry history per lambda
+- Per-arch lockfile generation via `uv pip compile`
+- Reusable GitHub Actions workflow at `.github/workflows/build.yml`
+- Native arm64 + x86_64 build matrix (no QEMU)
+
+### Not yet supported (planned for v0.2)
+
+- Node.js / npm packaging
+- Lambda@Edge-specific constraints (us-east-1 routing, no env vars)
+- Rust runtime

{repro_lambda-0.1.0 → repro_lambda-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repro-lambda
-Version: 0.1.0
+Version: 0.2.1
 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
@@ -33,7 +33,7 @@ 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).
+[terraform-aws-lambda](https://registry.terraform.io/modules/terraform-aws-modules/lambda/aws/latest) by [serverless.tf](https://serverless.tf/).
 
 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`
@@ -54,10 +54,10 @@ See `docs/` for full design.
 
 ## Release
 
-Releases are tag-driven. To cut v0.1.1:
+Releases are tag-driven. To cut v0.2.1:
 
-    git tag v0.1.1
-    git push origin v0.1.1
+    git tag v0.2.1
+    git push origin v0.2.1
 
 The `publish.yml` workflow uses PyPI Trusted Publishing (OIDC) — no PyPI token
 needed in repo secrets. Configure once via PyPI's "Publishing" panel:
@@ -66,3 +66,9 @@ needed in repo secrets. Configure once via PyPI's "Publishing" panel:
 - Repository: `repro-lambda`
 - Workflow: `publish.yml`
 - Environment: (leave blank)
+
+## Setup
+
+See [SETUP.md](./SETUP.md) for a copy-paste-able guide to provisioning the
+S3 buckets, IAM OIDC role, and CI workflow needed to use `repro-lambda` in
+your project.

{repro_lambda-0.1.0 → repro_lambda-0.2.1}/README.md

@@ -1,7 +1,7 @@
 # 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).
+[terraform-aws-lambda](https://registry.terraform.io/modules/terraform-aws-modules/lambda/aws/latest) by [serverless.tf](https://serverless.tf/).
 
 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`
@@ -22,10 +22,10 @@ See `docs/` for full design.
 
 ## Release
 
-Releases are tag-driven. To cut v0.1.1:
+Releases are tag-driven. To cut v0.2.1:
 
-    git tag v0.1.1
-    git push origin v0.1.1
+    git tag v0.2.1
+    git push origin v0.2.1
 
 The `publish.yml` workflow uses PyPI Trusted Publishing (OIDC) — no PyPI token
 needed in repo secrets. Configure once via PyPI's "Publishing" panel:
@@ -34,3 +34,9 @@ needed in repo secrets. Configure once via PyPI's "Publishing" panel:
 - Repository: `repro-lambda`
 - Workflow: `publish.yml`
 - Environment: (leave blank)
+
+## Setup
+
+See [SETUP.md](./SETUP.md) for a copy-paste-able guide to provisioning the
+S3 buckets, IAM OIDC role, and CI workflow needed to use `repro-lambda` in
+your project.

repro_lambda-0.2.1/SETUP.md

@@ -0,0 +1,482 @@
+# Setting up `repro-lambda` for your project
+
+`repro-lambda` builds and uploads Lambda artifacts to S3 outside of Terraform.
+For Terraform to read those artifacts via `s3_existing_package`, you need to
+provision the supporting AWS infrastructure once per AWS account and region.
+
+This guide is a copy-paste-able reference. Adapt the names and account IDs to
+your environment.
+
+## Architecture
+
+For each environment (e.g. `dev`, `prod`) you typically need:
+
+```
+${env}-my-lambda-artifacts            S3 bucket, region = eu-west-1 (or your primary region)
+${env}-my-lambda-artifacts-us-east-1  S3 bucket, region = us-east-1 (for Lambda@Edge — optional)
+
+gha-lambda-builder-${env}             IAM role, assumed via GitHub OIDC by source-repo CI to upload
+```
+
+Both buckets enforce **key-level immutability** via bucket policy:
+
+- `s3:PutObject` denied unless `If-None-Match=*` is set (writes are first-write-wins)
+- `s3:DeleteObject` and `s3:DeleteObjectVersion` denied
+- The Lambda service is allowed `s3:GetObject` so functions can load their zip
+
+Once an artifact with a content-hash key (`lambdas/<name>/<sha256>.zip`) is
+uploaded, the key is permanently bound to those bytes. `repro-lambda` treats
+HTTP 412 PreconditionFailed on a duplicate upload as success.
+
+## Terraform — per-account bootstrap
+
+The Terraform below assumes you already have a configured AWS provider in the
+target account. Drop it into your bootstrap directory (or anywhere you provision
+account-wide infrastructure that has no dependencies on other Terraform state).
+
+```hcl
+# us-east-1 is needed only for Lambda@Edge artifacts. Skip if you don't use L@E.
+provider "aws" {
+  alias  = "us_east_1"
+  region = "us-east-1"
+}
+
+locals {
+  env                     = "dev" # change per environment
+  lambda_artifacts_bucket_primary  = "${local.env}-my-lambda-artifacts"
+  lambda_artifacts_bucket_us_east_1 = "${local.env}-my-lambda-artifacts-us-east-1"
+
+  # GitHub OIDC subjects allowed to assume the builder role.
+  # Pattern: repo:<owner>/<repo>:* — narrow to specific refs in production.
+  lambda_builder_oidc_subjects = [
+    "repo:my-org/my-source-repo:*",
+  ]
+}
+
+# Immutability policy applied to every artifact bucket.
+data "aws_iam_policy_document" "lambda_artifacts_immutability" {
+  for_each = toset([
+    local.lambda_artifacts_bucket_primary,
+    local.lambda_artifacts_bucket_us_east_1,
+  ])
+
+  statement {
+    sid    = "DenyOverwrites"
+    effect = "Deny"
+
+    principals {
+      type        = "*"
+      identifiers = ["*"]
+    }
+
+    actions   = ["s3:PutObject"]
+    resources = ["arn:aws:s3:::${each.value}/*"]
+
+    condition {
+      test     = "StringNotEquals"
+      variable = "s3:If-None-Match"
+      values   = ["*"]
+    }
+  }
+
+  statement {
+    sid    = "DenyDelete"
+    effect = "Deny"
+
+    principals {
+      type        = "*"
+      identifiers = ["*"]
+    }
+
+    actions = [
+      "s3:DeleteObject",
+      "s3:DeleteObjectVersion",
+    ]
+    resources = ["arn:aws:s3:::${each.value}/*"]
+  }
+
+  statement {
+    sid    = "AllowLambdaServiceRead"
+    effect = "Allow"
+
+    principals {
+      type        = "Service"
+      identifiers = ["lambda.amazonaws.com"]
+    }
+
+    actions   = ["s3:GetObject"]
+    resources = ["arn:aws:s3:::${each.value}/*"]
+
+    condition {
+      test     = "StringEquals"
+      variable = "aws:SourceAccount"
+      values   = [data.aws_caller_identity.current.account_id]
+    }
+  }
+}
+
+data "aws_caller_identity" "current" {}
+
+# Primary-region bucket
+module "lambda_artifacts_bucket_primary" {
+  source  = "terraform-aws-modules/s3-bucket/aws"
+  version = "~> 4.0"
+
+  bucket = local.lambda_artifacts_bucket_primary
+
+  versioning = {
+    enabled = false # sha-as-key IS the versioning
+  }
+
+  server_side_encryption_configuration = {
+    rule = {
+      apply_server_side_encryption_by_default = {
+        sse_algorithm = "AES256"
+      }
+    }
+  }
+
+  attach_policy = true
+  policy        = data.aws_iam_policy_document.lambda_artifacts_immutability[local.lambda_artifacts_bucket_primary].json
+
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+
+  force_destroy = false
+}
+
+# us-east-1 bucket — only needed for Lambda@Edge. Remove if not using L@E.
+module "lambda_artifacts_bucket_us_east_1" {
+  source  = "terraform-aws-modules/s3-bucket/aws"
+  version = "~> 4.0"
+
+  providers = {
+    aws = aws.us_east_1
+  }
+
+  bucket = local.lambda_artifacts_bucket_us_east_1
+
+  versioning = {
+    enabled = false
+  }
+
+  server_side_encryption_configuration = {
+    rule = {
+      apply_server_side_encryption_by_default = {
+        sse_algorithm = "AES256"
+      }
+    }
+  }
+
+  attach_policy = true
+  policy        = data.aws_iam_policy_document.lambda_artifacts_immutability[local.lambda_artifacts_bucket_us_east_1].json
+
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+
+  force_destroy = false
+}
+
+# OIDC role assumed by GitHub Actions in source repos to upload artifacts.
+module "gha_lambda_builder_role" {
+  source  = "terraform-aws-modules/iam/aws//modules/iam-role"
+  version = "~> 6.0"
+
+  name = "gha-lambda-builder-${local.env}"
+
+  enable_github_oidc     = true
+  oidc_wildcard_subjects = local.lambda_builder_oidc_subjects
+
+  create_inline_policy = true
+  inline_policy_permissions = {
+    WriteLambdaArtifacts = {
+      actions = [
+        "s3:PutObject",
+        "s3:GetObject",
+        "s3:HeadObject",
+        "s3:ListBucket",
+      ]
+      resources = [
+        module.lambda_artifacts_bucket_primary.s3_bucket_arn,
+        "${module.lambda_artifacts_bucket_primary.s3_bucket_arn}/*",
+        module.lambda_artifacts_bucket_us_east_1.s3_bucket_arn,
+        "${module.lambda_artifacts_bucket_us_east_1.s3_bucket_arn}/*",
+      ]
+    }
+  }
+}
+
+output "lambda_artifacts_bucket_primary_arn" {
+  value = module.lambda_artifacts_bucket_primary.s3_bucket_arn
+}
+
+output "lambda_artifacts_bucket_us_east_1_arn" {
+  value = module.lambda_artifacts_bucket_us_east_1.s3_bucket_arn
+}
+
+output "gha_lambda_builder_role_arn" {
+  value = module.gha_lambda_builder_role.arn
+}
+```
+
+> Note: if you only use a single region (no Lambda@Edge), delete the
+> `lambda_artifacts_bucket_us_east_1` module and the `us_east_1` provider alias.
+> The OIDC role policy only needs the primary bucket then.
+
+Apply the Terraform once per environment. The bucket names and role ARN are
+referenced by your source repos' CI workflows below.
+
+## GitHub OIDC provider
+
+If your account doesn't already have the GitHub Actions OIDC provider, the
+`terraform-aws-modules/iam` collection includes a module for it:
+
+```hcl
+module "iam_github_oidc_provider" {
+  source  = "terraform-aws-modules/iam/aws//modules/iam-oidc-provider"
+  version = "~> 6.0"
+}
+```
+
+The provider is shared per AWS account — declare it once, not per environment.
+
+## Source-repo CI workflow
+
+In each repo that builds a Lambda, add a thin caller workflow that delegates to
+the reusable workflow in `antonbabenko/repro-lambda`:
+
+```yaml
+# .github/workflows/build-lambdas.yml
+name: build-lambdas
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+
+jobs:
+  build:
+    uses: antonbabenko/repro-lambda/.github/workflows/build.yml@v0.2.1
+    with:
+      manifest_path: lambdas.toml
+      repro_lambda_version: "0.2.1"
+    secrets:
+      aws-dev-role-arn: ${{ secrets.AWS_DEV_ROLE_ARN }}
+      aws-prod-role-arn: ${{ secrets.AWS_PROD_ROLE_ARN }}
+```
+
+Store the role ARNs (from the Terraform outputs above) as repo or organization
+secrets:
+
+- `AWS_DEV_ROLE_ARN` — `gha-lambda-builder-dev` role from the dev account
+- `AWS_PROD_ROLE_ARN` — `gha-lambda-builder-prod` role from the prod account
+
+## Per-Lambda manifest
+
+Each consumer repo defines a `lambdas.toml` at its root:
+
+```toml
+[[lambda]]
+logical_name      = "app"
+source_dir        = "src/app"
+requirements_lock = "src/app/requirements.${arch}.lock"
+runtime           = "python3.13"
+arch              = "arm64"
+handler           = "app.lambda_handler"
+region            = "eu-west-1"
+package_manager   = "pip"
+lambda_at_edge    = false
+hash_extra        = ""
+
+[builder]
+base_image_python = "public.ecr.aws/lambda/python:3.13@sha256:<pinned-digest>"
+include_patterns  = ["**/*.py", "**/*.json"]
+exclude_patterns  = [".venv/**", "__pycache__/**", "*.pyc", ".git/**", ".env*"]
+```
+
+Pin the `base_image_python` to a specific digest with `docker pull <image> &&
+docker inspect --format='{{index .RepoDigests 0}}' <image>` — never use a
+floating tag in production.
+
+## Terraform consumer — `s3_existing_package`
+
+In the Terraform that creates your Lambda function, point at the artifact in
+S3 instead of building inline:
+
+```hcl
+locals {
+  lambda_manifest = jsondecode(file("${path.module}/builds/catalog.json"))
+}
+
+module "lambda_app" {
+  source  = "terraform-aws-modules/lambda/aws"
+  version = "~> 8.0"
+
+  function_name = "my-app"
+  runtime       = "python3.13"
+  architectures = ["arm64"]
+  handler       = "app.lambda_handler"
+  publish       = true
+
+  s3_existing_package = {
+    bucket         = "${var.env}-my-lambda-artifacts"
+    key            = "lambdas/app/${local.lambda_manifest.lambdas.app.current}.zip"
+    object_version = null
+  }
+}
+```
+
+For Lambda@Edge, point at the `-us-east-1` bucket and set `lambda_at_edge = true`
+in the Terraform module.
+
+## Smoke test
+
+After applying the bootstrap Terraform and configuring CI secrets:
+
+```bash
+# In your consumer repo
+gh workflow run build-lambdas.yml
+# Wait for completion, then check that the artifact landed
+aws s3 ls s3://dev-my-lambda-artifacts/lambdas/app/
+```
+
+The first PR after migration should show a Terraform plan whose only diff is the
+`s3_key` change. If you see `last_modified`, `qualified_arn`, `version`,
+`local_file.archive_plan`, or `null_resource.archive` mentioned, the migration
+is incomplete — review your Lambda module call and remove the legacy build
+attributes (`source_path`, `build_in_docker`, `trigger_on_package_timestamp`,
+`ignore_source_code_hash`, `hash_extra`, `local_existing_package`,
+`store_on_s3`).
+
+## Troubleshooting
+
+- **`403 AccessDenied` on upload**: the OIDC role doesn't have `s3:PutObject` on
+  the bucket. Check the inline policy resources include both the bucket ARN and
+  `${bucket_arn}/*`.
+- **`PreconditionFailed` on every upload**: the artifact already exists with
+  that sha. This is the expected cache-hit behavior; `repro-lambda` treats it
+  as success.
+- **AWS CLI multipart upload fails with 403**: bucket policy denies multipart
+  parts. Pin the multipart threshold above your Lambda size cap:
+  `aws configure set s3.multipart_threshold 300MB`.
+- **Plan still shows noisy diff after migration**: verify the consumer Terraform
+  removed every legacy attribute and that the catalog sha read by `jsondecode`
+  matches the sha in the S3 key. The plan diff should be exactly `~ s3_key =
+  "<old>.zip" -> "<new>.zip"` and nothing else.
+
+## Node.js (npm) Lambdas
+
+`repro-lambda` v0.2 adds Node.js Lambda packaging. The build runs `npm ci` in
+the digest-pinned Node base image, then packs the resulting `pkg/` directory
+inside the digest-pinned Python base image (Python is the only language with
+deterministic-zip tooling pre-installed in the AWS Lambda runtime images, so
+its zlib is the only deflate implementation invoked - macOS arm64 hosts and
+Linux x86_64 CI produce byte-identical output).
+
+### Manifest fields for npm specs
+
+```toml
+[[lambda]]
+logical_name      = "api"
+source_dir        = "src/api"
+requirements_lock = "src/api/package-lock.json"   # npm lockfile
+package_json      = "src/api/package.json"        # REQUIRED for npm specs
+runtime           = "nodejs22.x"                  # or "nodejs20.x"
+arch              = "x86_64"                      # or "arm64"
+handler           = "index.handler"
+region            = "eu-west-1"
+package_manager   = "npm"
+lambda_at_edge    = false
+hash_extra        = ""
+
+[builder]
+base_image_python = "public.ecr.aws/lambda/python:3.13@sha256:<pinned-digest>"
+base_image_nodejs = "public.ecr.aws/lambda/nodejs:22@sha256:<pinned-digest>"
+include_patterns  = ["**/*.js", "**/*.json"]
+exclude_patterns  = [".git/**", "node_modules/**", "*.md", "LICENSE*", "CHANGELOG*"]
+```
+
+Pin both base images by digest:
+
+```bash
+docker pull public.ecr.aws/lambda/nodejs:22
+docker inspect --format='{{index .RepoDigests 0}}' public.ecr.aws/lambda/nodejs:22
+```
+
+### Lockfile regeneration
+
+`repro-lambda lock` only regenerates per-arch Python lockfiles via `uv pip
+compile`. For npm specs it prints `skip <name>: npm uses package-lock.json
+directly`. Regenerate the npm lockfile upstream with:
+
+```bash
+cd src/api
+npm install --package-lock-only
+git add package-lock.json
+```
+
+The lockfile and `package.json` both contribute to the artifact content hash;
+editing either bumps the S3 key.
+
+## Lambda@Edge example
+
+Lambda@Edge functions must be deployed to `us-east-1`, regardless of where the
+CloudFront distribution serves traffic. Set `region = "us-east-1"` and
+`lambda_at_edge = true` in the manifest; `repro-lambda` will upload to the
+`*-us-east-1` artifact bucket automatically.
+
+```toml
+[[lambda]]
+logical_name      = "edge"
+source_dir        = "src/edge"
+requirements_lock = "src/edge/package-lock.json"
+package_json      = "src/edge/package.json"
+runtime           = "nodejs22.x"
+arch              = "x86_64"               # L@E currently requires x86_64
+handler           = "index.handler"
+region            = "us-east-1"
+package_manager   = "npm"
+lambda_at_edge    = true
+```
+
+Consumer Terraform points at the us-east-1 bucket:
+
+```hcl
+module "lambda_edge" {
+  source  = "terraform-aws-modules/lambda/aws"
+  version = "~> 8.0"
+  providers = { aws = aws.us_east_1 }
+
+  function_name  = "my-edge"
+  runtime        = "nodejs22.x"
+  architectures  = ["x86_64"]
+  handler        = "index.handler"
+  publish        = true
+  lambda_at_edge = true
+
+  s3_existing_package = {
+    bucket = "${var.env}-my-lambda-artifacts-us-east-1"
+    key    = "lambdas/edge/${local.lambda_manifest.lambdas.edge.current}.zip"
+  }
+}
+```
+
+## Caveats
+
+- **No npm workspaces.** v0.2 supports a single `package.json` per Lambda. If
+  your repo uses workspaces, copy the published package into a single-package
+  layout per Lambda before invoking `repro-lambda`.
+- **Native dependencies need `optionalDependencies` arms.** `npm ci --cpu=${arch}
+  --os=linux` cannot cross-compile native modules. A dep with native code must
+  ship a `linux-${arch}` binary via its `package-lock.json`
+  `optionalDependencies` arm (the lockfile-v3 standard mechanism). If it
+  doesn't, the build runs on the host arch and may produce a non-portable
+  artifact.
+- **Symlinks in source are skipped.** `pack_directory` skips symlinks and
+  prints a stderr warning; the resulting zip cannot preserve link semantics.
+  If your build relies on symlinks (e.g. monorepo references), replace them
+  with the file contents.

{repro_lambda-0.1.0 → repro_lambda-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "repro-lambda"
-version = "0.1.0"
+version = "0.2.1"
 description = "Build reproducible AWS Lambda packages outside Terraform, optimized for terraform-aws-lambda by serverless.tf."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -56,6 +56,10 @@ target-version = "py311"
 [tool.ruff.lint]
 select = ["E", "F", "I", "B", "UP", "SIM"]
 
+[tool.ruff.lint.per-file-ignores]
+# Shell-script string literals inside docker_runner cannot be line-wrapped.
+"src/repro_lambda/docker_runner.py" = ["E501"]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "-ra --strict-markers"

{repro_lambda-0.1.0 → repro_lambda-0.2.1}/src/repro_lambda/__init__.py

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