feat: build large projects faster with persistent container

.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.