doc: tidy up and add more examples to README

Author: eoinsha

.projen/deps.json

@@ -1,12 +1,14 @@
 import { awscdk } from 'projen';
 import { JobPermission } from 'projen/lib/github/workflows-model';
+// import { NodePackageManager } from 'projen/lib/javascript';
 const project = new awscdk.AwsCdkConstructLibrary({
   author: 'Eoin Shanaghy',
   authorAddress: 'eoin.shanaghy@fourtheorem.com',
+  // packageManager: NodePackageManager.YARN_CLASSIC,
   cdkVersion: '2.161.1',
   constructsVersion: '10.3.0',
   defaultReleaseBranch: 'main',
-  jsiiVersion: '~5.5.0',
+  jsiiVersion: '~5.9.0',
   name: 'uv-python-lambda',
   projenrcTs: true,
   repositoryUrl: 'https://github.com/fourTheorem/uv-python-lambda',

.projenrc.ts

@@ -0,0 +1,3 @@
+# ~~ Generated by projen. To modify, edit .projenrc.ts and run "yarn projen".
+
+{}

.yarnrc.yml

@@ -0,0 +1,65 @@
+# Agent Instructions
+
+## Build, test, and lint
+
+- Install dependencies with `yarn install --check-files` to match CI.
+- Build with `npx projen build`.
+- Run the full test suite with `npx projen test`.
+- Run one test file with `npx jest test/function.test.ts`.
+- Run one test case with `npx jest test/function.test.ts -t "Create a function from basic_app"`.
+- Run lint and formatting checks with `npx biome check`.
+- Check a specific file with `npx biome check src/function.ts`.
+
+## Project architecture
+
+- This repository is a projen-managed jsii CDK construct library.
+- Human-authored sources primarily live in `src/`, `test/`, `resources/`, and `.projenrc.ts`.
+- Generated files such as `package.json`, workflow files, and packaging config should be changed through `.projenrc.ts`, 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`.
+
+## Packaging model
+
+- `PythonFunction` is a thin orchestration layer.
+- It derives the Lambda handler name from `index` and `handler`.
+- It enforces a Python runtime.
+- It defaults to `Architecture.ARM_64` and `Runtime.PYTHON_3_12`.
+- It delegates packaging to `Bundling.bundle(...)`.
+
+- `src/bundling.ts` owns packaging.
+- It builds a Docker builder image from `resources/`.
+- It caches long-lived builder containers based on runtime, architecture, build args, and root dir.
+- It returns Lambda code through `Code.fromCustomCommand(...)` so CDK can stage the packaged asset.
+
+- The Docker-side 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`, creates a lock file, and stays alive.
+- `export.sh` runs later via `docker exec`, waits for the lock file, optionally scopes to `--package <workspace>`, exports requirements, and installs dependencies into the requested asset output directory.
+
+## Workspace behavior
+
+- `workspacePackage` is the key monorepo and workspace feature.
+- It lets bundling treat a specific uv workspace package as the Lambda entry package while still resolving dependencies from the workspace root.
+
+## Test model
+
+- Tests in `test/function.test.ts` are integration-style CDK packaging tests, not isolated unit tests.
+- They create real CDK apps and stacks.
+- They require Docker.
+- They use fixture uv projects from `test/resources/`.
+- They inspect staged asset contents through the `uv-python-lambda:asset-path` metadata key.
+
+## Conventions for agents
+
+- Do not hand-edit generated project files.
+- `package.json` is generated by projen.
+- Workflows under `.github/workflows/` are generated from `.projenrc.ts`.
+- Keep changes aligned with Biome formatting and import ordering.
+- The repo uses Biome instead of ESLint and Prettier, with single quotes and organized imports.
+- Preserve jsii-friendly public types.
+- Public configuration is expressed as exported TypeScript interfaces such as `PythonFunctionProps`, `BundlingOptions`, and `ICommandHooks` because the library is packaged for both TypeScript and Python consumers.
+- Bundling assumes Docker-based execution.
+- There is no parallel local packager path, so packaging changes usually involve `src/bundling.ts` plus shell scripts in `resources/`.
+- Be careful with architecture defaults.
+- Production code defaults Lambda functions to ARM64, while tests intentionally detect 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 locate the staged bundle.

AGENTS.md

@@ -1,52 +1,110 @@
 # uv-python-lambda
 
-CDK Construct for Python Lambda Functions using [uv](https://docs.astral.sh/uv/)
+CDK construct for packaging Python Lambda functions from `uv` projects.
 
-## Goals
+## Why use it
 
-- ⚡️ Package and deploy Lambda Functions faster with `uv`'s speed
-- 📦 Support workspaces in a monorepo with [uv workspaces](https://docs.astral.sh/uv/concepts/workspaces/)
+- Packages Lambda assets from a `uv` project.
+- Supports `uv` workspaces, so you can package one workspace package while resolving dependencies from the workspace root.
+- Keeps the usual CDK Lambda experience: `PythonFunction` extends `aws_lambda.Function`, derives the handler from `index` and `handler`
+- Reuses builder containers across compatible functions during synthesis to reduce repeated setup work.
 
-`uv-python-lambda` is based on [aws-lambda-python-alpha](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-lambda-python-alpha-readme.html) with some differences:
+☝️ NOTE: This construct defaults to Python 3.12 on **ARM64**.
 
-- It only supports `uv` for packaging - there is no Poetry or pip support
-- It supports workspaces so you can build multiple Lambda functions from different uv workspaces and have their dependencies included correctly. This is useful for, but not limited to, monorepos.
+This library is published for TypeScript/JavaScript and Python.
 
-## API
+## Install
 
-See [API.md](API.md)
+TypeScript / JavaScript:
 
-## Example
+```bash
+npm install uv-python-lambda aws-cdk-lib constructs
+```
+
+Python:
+
+```bash
+uv add uv-python-lambda aws-cdk-lib constructs
+```
+
+Docker is required for bundling.
+
+## Usage
+
+TypeScript:
+
+```ts
+import * as path from 'node:path';
+import { Stack, Duration } from 'aws-cdk-lib';
+import { PythonFunction } from 'uv-python-lambda';
+import type { Construct } from 'constructs';
+
+export class ExampleStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+
+    new PythonFunction(this, 'Fn', {
+      rootDir: path.join(__dirname, '..', '..', 'services', 'fetcher'),
+      index: 'handler.py',
+      handler: 'lambda_handler',
+      timeout: Duration.seconds(30),
+    });
+  }
+}
+```
+
+Python:
 
 ```python
-from uv_python_lambda import PythonFunction
-from constructs import Construct
+from pathlib import Path
 
-# The root path should be relative to your CDK source file
-root_path = Path(__file__).parent.parent.parent
+from aws_cdk import Duration, Stack
+from constructs import Construct
+from uv_python_lambda import PythonFunction
 
 
-class CdkStack(Stack):
+class ExampleStack(Stack):
     def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
         super().__init__(scope, construct_id, **kwargs)
 
-        fn = PythonFunction(
-          self,
-          "fn",
-          root_dir=str(root_path),
-          index="fetcher_lambda.py",
-          workspace_package="fetcher",  # Use a workspace package as the top-level Lambda entry point.
-          handler="handle_event",
-          bundling={
-              "asset_excludes": [
-                  ".venv/",
-                  "node_modules/",
-                  "cdk/",
-                  ".git/",
-                  ".idea/",
-                  "dist/",
-              ]
-          },
-          timeout=Duration.seconds(30),
+        root_dir = Path(__file__).resolve().parents[2] / "services" / "fetcher"
+
+        PythonFunction(
+            self,
+            "Fn",
+            root_dir=str(root_dir),
+            index="handler.py",
+            handler="lambda_handler",
+            timeout=Duration.seconds(30),
         )
-```
+```
+
+## Using workspaces
+
+Point `rootDir` or `root_dir` at the workspace root, then set `workspacePackage` or `workspace_package` to the package that contains the Lambda entrypoint.
+
+```ts
+new PythonFunction(this, 'WorkspaceFn', {
+  rootDir: path.join(__dirname, '..', '..'),
+  workspacePackage: 'fetcher',
+  index: 'fetcher_lambda.py',
+  handler: 'handle_event',
+});
+```
+
+```python
+PythonFunction(
+    self,
+    "WorkspaceFn",
+    root_dir=str(root_dir),
+    workspace_package="fetcher",
+    index="fetcher_lambda.py",
+    handler="handle_event",
+)
+```
+
+## Notes
+
+- `index` can be passed as `handler.py` or `handler`.
+- Use `bundling` to pass Docker environment variables, asset excludes, build args, or command hooks.
+- See [API.md](API.md) for the full API reference.

API.md

@@ -6,8 +6,11 @@
 set -euo pipefail
 
 export LOCK_FILE=/uvbuild/uv-python-lambda.lock
-export UV_LINK_MODE=copy
+export UV_LINK_MODE=hardlink
 export UV_NO_INSTALLER_METADATA=1
+export UV_PYTHON_LAMBDA_NOFILE_LIMIT="${UV_PYTHON_LAMBDA_NOFILE_LIMIT:-1048576}"
+
+ulimit -n "$UV_PYTHON_LAMBDA_NOFILE_LIMIT"
 
 rm -f "$LOCK_FILE"