Refactor templates and examples layout

Author: mparkachov

AGENTS.md

@@ -30,12 +30,16 @@ The runtime is packaged as a Lambda Layer and is intended to be consumed directl
   - package_layer.sh
   - smoke_test.sh
 - docker/Dockerfile
-- runtime-tutorial/
+- examples/
   - function.sh
   - README.md
-- docs/
-  - USAGE.md
-  - DEVELOPMENT.md
+- template/
+  - template.yaml
+  - template-arm64.yaml
+  - template-amd64.yaml
+  - aws-setup.yaml
+- USAGE.md
+- DEVELOPMENT.md
 - dist/
 - Makefile
 - README.md

docs/DEVELOPMENT.md DEVELOPMENT.mddocs/DEVELOPMENT.md renamed to DEVELOPMENT.md

@@ -27,15 +27,20 @@ The Docker build uses `curl-minimal` to keep dependencies small. If you need ful
 
 This produces `dist/lambda-shell-runtime-<arch>.zip` with `bootstrap`, `bin/`, `aws-cli/`, and `lib/` at the zip
 root, plus a versioned artifact named `dist/lambda-shell-runtime-<arch>-<aws-cli-version>.zip`. The script also
-updates the `SemanticVersion` in `template.yaml`, `template-arm64.yaml`, and `template-amd64.yaml` to match the
-bundled AWS CLI v2 version.
+generates `dist/template-*.yaml` with `SemanticVersion` set to the bundled AWS CLI v2 version and `ContentUri`
+pointing at the packaged zips.
+The source `template*.yaml` files remain static; publishing uses the generated templates.
 
 To package both architectures:
 
 ```sh
 ARCH=all ./scripts/package_layer.sh
 ```
 
+Template generation overrides:
+- `TEMPLATE_VERSION` (override the `SemanticVersion` written into `dist/template-*.yaml`; defaults to the bundled AWS CLI v2 version)
+- `TEMPLATE_OUTPUT_DIR` (output directory for generated templates; default: `dist`)
+
 ## Smoke test
 
 ```sh
@@ -64,15 +69,15 @@ make test
 All shell scripts are written for POSIX `sh` and should pass `shellcheck`.
 
 ```sh
-shellcheck runtime/bootstrap scripts/*.sh runtime-tutorial/function.sh
+shellcheck runtime/bootstrap scripts/*.sh examples/function.sh
 ```
 
 ## AWS configuration
 
 Project defaults live in `scripts/aws_env.sh`. It pins the AWS region to `us-east-1` and sets default names
 for the S3 bucket, setup stack, SAR applications, and the S3 prefix used for SAR artifacts. These defaults
 are used by `make aws-check`, `make aws-setup`, and `make release`.
-`./scripts/package_layer.sh` keeps the SAR application names in the templates aligned with these defaults; rerun it after changing the app name settings.
+`./scripts/package_layer.sh` renders `dist/template-*.yaml` with SAR application names aligned with these defaults; rerun it after changing the app name settings.
 Set `ENV=dev` to switch to the dev defaults (the `*_DEV` values).
 
 Override any of the defaults by exporting:
@@ -100,11 +105,10 @@ S3_BUCKET=your-bucket make release
 
 It:
 - builds and packages both architectures
-- updates the templates' `SemanticVersion` to the bundled AWS CLI v2 version
+- generates `dist/template-*.yaml` with `SemanticVersion` set to the bundled AWS CLI v2 version
 - checks for an existing Git tag
-- if missing, commits the templates, tags the repo, and creates a GitHub release with versioned artifacts
 - publishes the SAR applications with `sam package`/`sam publish`
-- updates `template.yaml` with the arm64/amd64 ApplicationIds and publishes the wrapper application
+- renders the wrapper template with the arm64/amd64 ApplicationIds and publishes the wrapper application
 - uploads SAR artifacts under `S3_PREFIX/<version>/<arch>`
 
 To check whether a release is needed without building anything, run:
@@ -189,7 +193,7 @@ To run in GitHub: Actions -> Release -> Run workflow.
 
 Manual fallback:
 1. Ensure `ARCH=all ./scripts/package_layer.sh` has been run so the versioned artifacts are created.
-2. Tag the release in Git. Use the AWS CLI version as the tag to match the templates' `SemanticVersion`.
+2. Tag the release in Git. Use the AWS CLI version as the tag to match the generated templates' `SemanticVersion`.
 
 ## Publish to SAR
 
@@ -208,17 +212,17 @@ To publish all three SAR applications (arm64, amd64, wrapper) in order:
 make publish-all
 ```
 
-`publish-all` requires the wrapper ApplicationIds to be populated in `template.yaml`.
+`make publish-wrapper` and `make publish-all` generate the wrapper template with the correct ApplicationIds automatically.
 
-To publish the wrapper application after updating the ApplicationIds, run:
+To publish the wrapper application, run:
 
 ```sh
 make publish-wrapper
 ```
 
-If you want the raw SAM commands instead:
+If you want the raw SAM commands for the per-arch apps:
 
-1. Build and package the layer (this updates the templates' `SemanticVersion` to match the bundled AWS CLI version):
+1. Build and package the layer (this generates `dist/template-*.yaml` with `SemanticVersion` set to the bundled AWS CLI version):
 
 ```sh
 ./scripts/build_layer.sh
@@ -229,53 +233,35 @@ If you want the raw SAM commands instead:
 
 ```sh
 sam package \
-  --template-file template-arm64.yaml \
+  --template-file dist/template-arm64.yaml \
   --s3-bucket "$S3_BUCKET" \
   --s3-prefix "sar/<version>/arm64" \
-  --output-template-file packaged-arm64.yaml
+  --output-template-file dist/packaged-arm64.yaml
 
 sam package \
-  --template-file template-amd64.yaml \
+  --template-file dist/template-amd64.yaml \
   --s3-bucket "$S3_BUCKET" \
   --s3-prefix "sar/<version>/amd64" \
-  --output-template-file packaged-amd64.yaml
+  --output-template-file dist/packaged-amd64.yaml
 ```
 
 3. Publish to SAR:
 
 ```sh
-sam publish --template packaged-arm64.yaml
-sam publish --template packaged-amd64.yaml
+sam publish --template dist/packaged-arm64.yaml
+sam publish --template dist/packaged-amd64.yaml
 ```
 
-4. Update the wrapper template with the architecture application IDs and publish it:
+4. Publish the wrapper application (it is rendered with the architecture application IDs):
 
 ```sh
-ARM64_APP_ID=$(aws serverlessrepo list-applications \
-  --query "Applications[?Name=='lambda-shell-runtime-arm64'].ApplicationId | [0]" \
-  --output text)
-AMD64_APP_ID=$(aws serverlessrepo list-applications \
-  --query "Applications[?Name=='lambda-shell-runtime-amd64'].ApplicationId | [0]" \
-  --output text)
-
-sed -i.bak \
-  -e "s|__APP_ID_ARM64__|$ARM64_APP_ID|g" \
-  -e "s|__APP_ID_AMD64__|$AMD64_APP_ID|g" \
-  template.yaml
-
-sam package \
-  --template-file template.yaml \
-  --s3-bucket "$S3_BUCKET" \
-  --s3-prefix "sar/<version>/wrapper" \
-  --output-template-file packaged.yaml
-
-sam publish --template packaged.yaml
+make publish-wrapper
 ```
 
 ## AWS setup
 
 Use `make aws-setup` to bootstrap the S3 bucket and create the SAR applications if they do not exist.
-CloudFormation cannot create SAR applications directly, so the target creates the bucket via `aws-setup.yaml`
+CloudFormation cannot create SAR applications directly, so the target creates the bucket via `template/aws-setup.yaml`
 and then runs `sam publish` to create the first SAR version if needed.
 
 ```sh

README.md

@@ -17,11 +17,14 @@
 - `layer/opt`: staged layer contents for the host architecture
 - `scripts/`: build, package, and smoke test scripts
 - `docker/Dockerfile`: build image for Amazon Linux 2023 (arm64, x86_64)
-- `template.yaml`: SAR wrapper application (arm64 + amd64)
-- `template-arm64.yaml`, `template-amd64.yaml`: SAR application templates (SAM)
+- `template/template.yaml`: source SAR wrapper template (arm64 + amd64)
+- `template/template-arm64.yaml`, `template/template-amd64.yaml`: source SAR application templates (SAM)
+- `template/aws-setup.yaml`: CloudFormation stack for SAR setup
+- `dist/template-*.yaml`: generated publish/release templates (ignored in git)
+- `USAGE.md`: runtime contract and manual publishing
+- `DEVELOPMENT.md`: build and release workflow
 - `SAR_README.md`: SAR application README shown to end users
-- `runtime-tutorial/`: minimal handler example
-- `docs/`: usage and development notes
+- `examples/`: minimal handler example
 
 ## Build the layer
 
@@ -39,7 +42,9 @@ The build image uses `curl-minimal` to keep dependencies small. If the AWS CLI d
 
 The outputs are `dist/lambda-shell-runtime-arm64.zip` and `dist/lambda-shell-runtime-amd64.zip`, each containing
 `bootstrap`, `bin/`, `aws-cli/`, and `lib/` at the zip root (Lambda mounts them under `/opt`).
-`./scripts/package_layer.sh` also writes versioned artifacts named `dist/lambda-shell-runtime-<arch>-<aws-cli-version>.zip` and updates the `SemanticVersion` in both templates to match the bundled AWS CLI v2 version.
+`./scripts/package_layer.sh` also writes versioned artifacts named `dist/lambda-shell-runtime-<arch>-<aws-cli-version>.zip`
+and generates `dist/template-*.yaml` with `SemanticVersion` set to the bundled AWS CLI v2 version and `ContentUri` pointing
+at the packaged zips.
 
 ## Smoke test
 
@@ -53,7 +58,7 @@ The outputs are `dist/lambda-shell-runtime-arm64.zip` and `dist/lambda-shell-run
 - Architecture: `arm64` or `x86_64`
 - Handler: `function.handler` (script stored as `function.sh` in your function package)
 
-See [SAR_README.md](SAR_README.md) for end-user SAR installation and quick start, [docs/USAGE.md](docs/USAGE.md) for manual publishing and the runtime contract, [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for build and release workflow, and [runtime-tutorial/README.md](runtime-tutorial/README.md) for a deployable example.
+See [SAR_README.md](SAR_README.md) for end-user SAR installation and quick start, [USAGE.md](USAGE.md) for manual publishing and the runtime contract, [DEVELOPMENT.md](DEVELOPMENT.md) for build and release workflow, and [examples/README.md](examples/README.md) for a deployable example.
 
 ## Publish to SAR
 
@@ -66,22 +71,22 @@ Set `S3_BUCKET` to an S3 bucket in your account and run:
 
 ```sh
 sam package \
-  --template-file template-arm64.yaml \
+  --template-file dist/template-arm64.yaml \
   --s3-bucket "$S3_BUCKET" \
   --s3-prefix "sar" \
-  --output-template-file packaged-arm64.yaml
+  --output-template-file dist/packaged-arm64.yaml
 
-sam publish --template packaged-arm64.yaml
+sam publish --template dist/packaged-arm64.yaml
 
 sam package \
-  --template-file template-amd64.yaml \
+  --template-file dist/template-amd64.yaml \
   --s3-bucket "$S3_BUCKET" \
   --s3-prefix "sar" \
-  --output-template-file packaged-amd64.yaml
+  --output-template-file dist/packaged-amd64.yaml
 
-sam publish --template packaged-amd64.yaml
+sam publish --template dist/packaged-amd64.yaml
 ```
 
 Each SAR application publishes a single layer output (`LayerVersionArn`) for its architecture.
-`./scripts/package_layer.sh` updates the templates' `SemanticVersion` to match the bundled AWS CLI v2 version; review and commit the change for each release.
-The wrapper application in `template.yaml` references both architecture-specific apps; `make release` and `make aws-setup` publish it after the per-arch apps.
+Generated templates live under `dist/` and are not committed; the source templates stay static.
+The wrapper application is rendered at publish time with the current per-arch ApplicationIds; `make release` and `make aws-setup` publish it after the per-arch apps.

docs/USAGE.md USAGE.mddocs/USAGE.md renamed to USAGE.md

@@ -1,4 +1,4 @@
-# Runtime Tutorial
+# Examples
 
 This example mirrors the AWS custom runtime tutorial layout while using the runtime from the layer. It defines a
 minimal handler function that reads JSON from the first argument and writes JSON to STDOUT. It also calls
@@ -16,7 +16,7 @@ The layer zips will be created at `dist/lambda-shell-runtime-arm64.zip` and `dis
 ## Package the function
 
 ```sh
-cd runtime-tutorial
+cd examples
 zip -r ../dist/hello-function.zip function.sh
 ```
 

runtime-tutorial/README.md examples/README.mdruntime-tutorial/README.md renamed to examples/README.md

@@ -3,6 +3,7 @@ set -eu
 
 root=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
 . "$root/scripts/aws_env.sh"
+. "$root/scripts/template_utils.sh"
 
 require_cmd() {
   if ! command -v "$1" >/dev/null 2>&1; then
@@ -243,25 +244,36 @@ resolve_version() {
     return 0
   fi
 
-  template_path="$root/template-$arch.yaml"
-  if [ ! -f "$template_path" ]; then
-    printf '%s\n' "Template not found at $template_path" >&2
-    exit 1
+  if [ -n "${RELEASE_VERSION:-}" ]; then
+    printf '%s\n' "$RELEASE_VERSION"
+    return 0
   fi
-  version=$(awk -F': *' '/^[[:space:]]*SemanticVersion:/ {print $2; exit}' "$template_path")
-  case "$version" in
-    ''|*[!0-9.]*|*.*.*.*)
-      printf '%s\n' "Unable to parse SemanticVersion from $template_path: $version" >&2
-      exit 1
-      ;;
-    *.*.*)
-      ;;
-    *)
-      printf '%s\n' "Unable to parse SemanticVersion from $template_path: $version" >&2
-      exit 1
-      ;;
-  esac
-  printf '%s\n' "$version"
+
+  if [ -n "${LSR_SAR_VERSION:-}" ]; then
+    printf '%s\n' "$LSR_SAR_VERSION"
+    return 0
+  fi
+
+  if [ -n "${AWSCLI_VERSION:-}" ]; then
+    printf '%s\n' "$AWSCLI_VERSION"
+    return 0
+  fi
+
+  template_path=$(template_output_path "$arch")
+  if [ -f "$template_path" ]; then
+    template_semantic_version "$template_path"
+    return 0
+  fi
+
+  template_path=$(template_source_path "$arch")
+  if [ -f "$template_path" ]; then
+    printf '%s\n' "Using version from source template: $template_path" >&2
+    template_semantic_version "$template_path"
+    return 0
+  fi
+
+  printf '%s\n' "Template not found for $arch." >&2
+  exit 1
 }
 
 check_s3_rw() {