Add Copier migration support and update template docs

.gitattributes

@@ -1,5 +1,6 @@
 infra/** linguist-vendored
-cookiecutter/** linguist-vendored
+template/** linguist-vendored
+copier/** linguist-vendored
 *.bib -linguist-detectable
 *.tex -linguist-detectable
 papers/* linguist-documentation

.github/workflows/catch2_exemplar_test.yml

@@ -17,12 +17,12 @@ jobs:
         uses: actions/checkout@v6
       - name: Test catch2 exemplar
         run: |
-          cd cookiecutter
-          source ./check_cookiecutter.sh
-          cookiecutter_venv_path=$(mktemp --directory --dry-run)
-          setup_venv "$cookiecutter_venv_path"
-          stamp "$PWD" "./catch2_exemplar" "catch2" "true"
-          cd catch2_exemplar/exemplar
+          cd copier
+          source ./check_copier.sh
+          copier_venv_path=$(mktemp --directory --dry-run)
+          setup_venv "$copier_venv_path"
+          stamp "$repo_root" "./catch2_exemplar" "catch2" "true"
+          cd catch2_exemplar
           cmake -B build -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=./infra/cmake/use-fetch-content.cmake -DCMAKE_CXX_STANDARD=20 -DCMAKE_INSTALL_PREFIX=$PWD/dist
           cmake --build build
           ctest --test-dir build

.github/workflows/ci_tests.yml

@@ -19,6 +19,61 @@ jobs:
   beman-submodule-check:
     uses: bemanproject/infra-workflows/.github/workflows/reusable-beman-submodule-check.yml@1.7.4
 
+  copier-test:
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/bemanproject/infra-containers-gcc:latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        shell: bash
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+      - name: Test Copier Template Variants
+        shell: bash
+        env:
+          GITHUB_ACTIONS: true
+        # gcc-release will use GCC 15 which supports C++23 modules appropriately in this container
+        run: ./copier/test_standard_project.sh gcc-release
+
+  copier-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        shell: bash
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+      - name: Generated project self-lints cleanly
+        shell: bash
+        # Verify a freshly generated standard project passes its own
+        # pre-commit config (gersemi, clang-format, beman-tidy) on the first
+        # run, exercising copier/format_project.sh.
+        run: ./copier/lint_standard_project.sh my_project
+
+  copier-cmake-matrix:
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/bemanproject/infra-containers-gcc:latest
+    strategy:
+      fail-fast: false
+      matrix:
+        cmake_version: ["3.30.9", "3.31.10", "4.0.3", "4.1.3", "4.2.3", "4.3.2", "4.4.2"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        shell: bash
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+      - name: Test Copier Template Variants Matrix
+        shell: bash
+        env:
+          GITHUB_ACTIONS: true
+        # Run across our experimental boundaries
+        run: ./copier/test_cmake_matrix.sh gcc-release ${{ matrix.cmake_version }}
   preset-test:
     uses: bemanproject/infra-workflows/.github/workflows/reusable-beman-preset-test.yml@1.7.4
     with:

.github/workflows/cookiecutter_test.yml → .github/workflows/copier_test.yml

@@ -1,19 +1,23 @@
 # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
-name: Cookiecutter Test
+name: Copier Test
 on:
   push:
     branches:
       - main
   pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
 
 jobs:
-  cookiecutter-test:
+  copier-test:
     runs-on: ubuntu-latest
-    name: "Check cookiecutter for consistency"
+    name: "Check copier for consistency"
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-      - name: beman cookiecutter consistency check
+      - name: beman copier consistency check
         run: |
-          ./cookiecutter/check_cookiecutter.sh
+          ./copier/check_copier.sh

.github/workflows/todo_exemplar_test.yml

@@ -17,12 +17,12 @@ jobs:
         uses: actions/checkout@v6
       - name: Test static exemplar
         run: |
-          cd cookiecutter
-          source ./check_cookiecutter.sh
-          cookiecutter_venv_path=$(mktemp --directory --dry-run)
-          setup_venv "$cookiecutter_venv_path"
-          stamp "$PWD" "./static_exemplar" "gtest" "false"
-          cd static_exemplar/exemplar
+          cd copier
+          source ./check_copier.sh
+          copier_venv_path=$(mktemp --directory --dry-run)
+          setup_venv "$copier_venv_path"
+          stamp "$repo_root" "./static_exemplar" "gtest" "false"
+          cd static_exemplar
           grep -r 'identity' . && exit 1
           find . -name '*identity*' | grep . && exit 1
           cmake -B build -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=./infra/cmake/use-fetch-content.cmake -DCMAKE_CXX_STANDARD=20 -DCMAKE_INSTALL_PREFIX=$PWD/dist

.pre-commit-config.yaml

@@ -40,4 +40,4 @@ repos:
     hooks:
       - id: codespell
 
-exclude: 'cookiecutter/|infra/|port/'
+exclude: 'template/|copier/|infra/|port/'

CONTRIBUTING.md

@@ -106,6 +106,47 @@ ctest --test-dir build
 The file `./lockfile.json` configures the list of dependencies and versions that will be
 acquired by FetchContent.
 
+## Developing The Copier Template
+
+This repository doubles as both the exemplar library and the Copier template used to stamp
+new Beman libraries.
+
+The template workflow is organized as follows:
+
+* `copier.yml` defines the Copier questions, defaults, validation rules, and post-copy
+  tasks.
+* `template/` contains the files rendered into generated projects.
+* `stamp.sh` is the user-facing wrapper for stamping a forked exemplar repository into a
+  new project.
+* `./copier/check_copier.sh` validates that exemplar regenerates cleanly and that a
+  non-exemplar project does not leak exemplar-specific names like `identity`.
+
+When testing local template changes, do not render directly from the Git checkout. The
+Copier helper scripts intentionally render from a temporary snapshot with `.git`, `build`,
+and `.venv` excluded so that validation uses the current worktree contents.
+
+Run the template checks with:
+
+```shell
+./copier/check_copier.sh
+```
+
+If you need to smoke-test generated projects manually, start from the same validated flow:
+
+```shell
+tmpdir=$(mktemp -d)
+python3 -m venv "$tmpdir/venv"
+"$tmpdir/venv/bin/python3" -m pip install copier
+src=$(mktemp -d)
+rsync -a --exclude .git --exclude build --exclude .venv ./ "$src/"
+"$tmpdir/venv/bin/copier" copy --trust --defaults \
+  -d template_src_path=https://github.com/bemanproject/exemplar.git \
+  -d template_commit="$(git rev-parse HEAD)" \
+  "$src" "$tmpdir/project"
+```
+
+Then configure and build the generated project as usual.
+
 ## Project-specific configure arguments
 
 Project-specific options are prefixed with `BEMAN_EXEMPLAR`.