chore: use per-synth builder containers

Author: eoinsha

.github/copilot-instructions.md

@@ -0,0 +1,32 @@
+# uv-python-lambda Copilot Instructions
+
+## Build, test, and lint
+
+- Install dependencies with `yarn install --check-files` (matches CI).
+- Build with `npx projen build`.
+- Run the full test suite with `npx projen test`.
+- Run a single test file with `npx jest test/function.test.ts`.
+- Run a single test case with `npx jest test/function.test.ts -t "Create a function from basic_app"`.
+- Lint/format checks use Biome: `npx biome check`.
+- To check a specific file with Biome, run `npx biome check src/function.ts`.
+
+## High-level architecture
+
+- This repository is a **projen-managed jsii CDK construct library**. The human-authored sources are mainly in `src/`, `test/`, `resources/`, and `.projenrc.ts`. Generated project files such as `package.json`, GitHub workflows, and packaging config should be changed via `.projenrc.ts` and then regenerated with `npx projen`.
+- The public API is exported from `src/index.ts`. The main construct is `PythonFunction` in `src/function.ts`, which extends `aws-cdk-lib/aws-lambda.Function`.
+- `PythonFunction` is a thin orchestration layer: it resolves the Lambda handler name from `index` + `handler`, enforces a Python runtime, defaults to `Architecture.ARM_64` and `Runtime.PYTHON_3_12`, and delegates packaging to `Bundling.bundle(...)`.
+- `src/bundling.ts` owns packaging. It creates a Docker builder image from `resources/`, caches long-lived builder containers by a hash of runtime/architecture/build args/root dir, and returns Lambda code through `Code.fromCustomCommand(...)` so CDK can stage the packaged asset.
+- The Docker-side build flow lives in `resources/entrypoint.sh` and `resources/export.sh`:
+  - `entrypoint.sh` starts the builder container, mounts an overlay filesystem over `/src`, creates a uv virtualenv, runs `uv sync --no-dev --frozen --no-editable`, touches a lock file, and then stays alive.
+  - `export.sh` runs later via `docker exec`; it waits for that lock file, optionally scopes to `--package <workspace>`, exports requirements, and installs dependencies into the requested asset output directory.
+- `workspacePackage` is the key monorepo/workspace feature: it tells bundling to treat a specific uv workspace package as the Lambda entry package while still resolving dependencies from the workspace root.
+- Tests in `test/function.test.ts` are integration-style CDK packaging tests, not isolated unit tests. They create real CDK apps/stacks, require Docker, use fixture uv projects from `test/resources/`, and inspect the staged asset contents through the custom metadata key `uv-python-lambda:asset-path`.
+
+## Key conventions
+
+- **Do not hand-edit generated project files.** `package.json` explicitly says it is generated by projen, and the workflows under `.github/workflows/` are generated from `.projenrc.ts`.
+- **Keep changes aligned with Biome formatting/import ordering.** The repo uses Biome instead of ESLint/Prettier, with single quotes and organize-imports enabled.
+- **Preserve jsii-friendly public types.** Public configuration is expressed as exported TypeScript interfaces (`PythonFunctionProps`, `BundlingOptions`, `ICommandHooks`) because this library is packaged for TypeScript and Python consumers.
+- **Bundling assumes Docker-based execution.** There is no parallel local packager path; changes to packaging behavior usually involve `src/bundling.ts` plus the shell scripts in `resources/`.
+- **Be careful with architecture defaults.** Production code defaults Lambda functions to ARM64, while tests intentionally detect the Docker host architecture to avoid slow QEMU emulation on GitHub runners.
+- **Asset metadata is intentional.** `PythonFunction` writes `uv-python-lambda:asset-path` metadata so tests and downstream CDK asset inspection can find the staged bundle.

.projen/deps.json

@@ -21,17 +21,20 @@ const project = new awscdk.AwsCdkConstructLibrary({
   },
   // cdkVersion: '2.1.0',    /* CDK version to use. */
   // cdkDependencies: [],     /* CDK dependencies of this module. */
-  bundledDeps: ['object-hash', 'atomic-sleep'],                /* Dependencies which should be bundled in the package. */
+  bundledDeps: [
+    'object-hash',
+  ] /* Dependencies which should be bundled in the package. */,
   // deps: [],                /* Runtime dependencies of this module. */
   // description: undefined,  /* The description is just a string that helps people understand the purpose of the package. */
-  devDeps: ['@biomejs/biome', '@types/object-hash', '@types/atomic-sleep'] /* Build dependencies for this module. */,
+  devDeps: [
+    '@biomejs/biome',
+    '@types/object-hash',
+  ] /* Build dependencies for this module. */,
   // packageName: undefined,  /* The "name" in package.json. */
   jestOptions: {
     extraCliOptions: ['--testTimeout=300000'],
   },
-  gitignore: [
-    ".vscode/",
-  ],
+  gitignore: ['.vscode/'],
   eslint: false,
 });
 

.projen/tasks.json

@@ -7,5 +7,6 @@ FROM ${BUNDLING_IMAGE}
 # FROM public.ecr.aws/lambda/python:3.12-$IMAGE_ARCH
 COPY --from=uv /uv /uvx /bin/
 COPY *.sh /root
+RUN chmod +x /root/*.sh
 WORKDIR /root
-ENTRYPOINT [ "/root/entrypoint.sh" ]
+ENTRYPOINT [ "/root/entrypoint.sh" ]

.projenrc.ts

@@ -1,38 +1,24 @@
 #!/bin/bash
 
-# /uvbuild is the working directory for things like cache and staged outputs
-# /src is the project root, where the top-level pyproject.toml/uv.lock exists
+# /uvbuild is the working directory for caches and staged outputs.
+# /src is the project root mounted from the host.
 
 set -euo pipefail
 
 export LOCK_FILE=/uvbuild/uv-python-lambda.lock
+export UV_LINK_MODE=copy
+export UV_NO_INSTALLER_METADATA=1
 
-rm -f $LOCK_FILE
+rm -f "$LOCK_FILE"
 
-# Changing the default UV_LINK_MODE silences warnings about not being able to use hard links
-# since the cache and sync target may be on separate file systems.
-export UV_LINK_MODE=copy
 mkdir -p /uvbuild/uvcache
 mkdir -p /root/.cache
 ln -sf /uvbuild/uvcache /root/.cache/uv
 
-# Set up overlay filesystem
-mkdir -p /tmp/overlay
-mount -t tmpfs tmpfs /tmp/overlay
-mkdir -p /tmp/overlay/{upper,work,merged}
-mount -t overlay overlay -o rw,lowerdir=/src,upperdir=/tmp/overlay/upper,workdir=/tmp/overlay/work /tmp/overlay/merged
-
-echo Overlay has been set up
-
-cd /tmp/overlay/merged
-rm -rf .venv  # Remove (hide) any host system venv from the overlay filesystem
-
-uv venv --python-preference=only-system
-uv sync --compile-bytecode --no-dev --frozen --no-editable
-
-touch $LOCK_FILE
+touch "$LOCK_FILE"
 
 echo Builder container is ready and waiting
+
 while true; do
     sleep 1
-done
+done