feat(openemr-cmd): pass HOST_UID/HOST_GID through compose to openemr container (#840)

## Summary

Completes the cross-repo HOST_UID story started in openemr/openemr#12642
(entrypoint side, already merged + new flex image SHA pinned via
dependabot #12644). This PR wires the openemr-devops side:
`wt_write_override` emits `HOST_UID`/`HOST_GID` env vars in the openemr
service block, sourced from `id -u` / `id -g` at worktree-add / regen
time.

## Result

For **non-uid=1000 hosts** (CI runners at uid=1001, multi-user dev
boxes, distros that start uids at 1001+, macOS via Docker Desktop):
apache inside the container now writes bind-mount files with the host's
uid. Host-side writes (`git commit`, IDE edits, `worktree regen`,
`worktree set-env`) work without any chown dance. The uid-mismatch class
of bugs that dominated #833 / #836 / #838 review cycles is eliminated
end-to-end.

For **uid=1000 hosts** (most Linux desktop developers): zero functional
change. The env vars are emitted unconditionally because the entrypoint
adoption block is a sub-millisecond no-op on uid=1000 and the consistent
behavior across hosts is worth more than the savings.

**Backwards compatible:** pre-HOST_UID-aware images silently ignore the
env vars.

## CI workarounds removed (now obsolete)

Both `sudo chown -R "$(id -u):$(id -g)"` steps in
`test-bats-openemr-cmd-real-docker.yml`:
1. **`worktree-lifecycle-e2e`** "One-shot chown back to runner (enables
host-side regen + set-env)" — added in #834
2. **`prek-workflow-e2e`** "One-shot chown back to runner (enables
host-side writes + git commits)" — added in #836

Both replaced with `NOTE:` comments documenting what used to live there
and why the chown is no longer needed — for archaeology by future
contributors.

## Kept as back-compat shim

The `#833` auto-chown block in `cmd_worktree_remove` stays in place.
Inline comment updated to reflect its new status (no-op when the image
honors HOST_UID; still useful for users on pre-HOST_UID images and for
any drift the entrypoint adoption might miss).

## Tests

New bats file `tests/bats/openemr-cmd/host_uid_compose.bats` pins three
behaviors:
1. `wt_write_override` emits `HOST_UID` and `HOST_GID` env vars in the
override file
2. Values match `id -u` / `id -g` at write time
3. Env vars are correctly nested under `services.openemr.environment`
(structural check via yaml.safe_load)
4. Emitted for all three env variants (easy / easy-light / easy-redis)

## Test plan

- [ ] BATS openemr-cmd (ubuntu-22.04 + macos-14) pass — new tests +
existing suite
- [ ] e2e — full worktree lifecycle: passes WITHOUT the sudo chown step
(proves apache now adopts runner uid; regen + set-env writes work as
runner)
- [ ] e2e — prek install + real git commit: passes WITHOUT the sudo
chown step (proves `git commit` from the worktree works as runner)
- [ ] Other e2e jobs unchanged
- [ ] FUNCS_END drift sentinel still passes (no new function added —
wt_write_override grew inline, last function still at line 1882)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Generated OpenEMR docker-compose override files now include the
current host user and group IDs (`HOST_UID`/`HOST_GID`) in the container
environment.
* **Bug Fixes**
* Worktree lifecycle and pre-install commit workflows no longer require
host-side ownership adjustment before regeneration and environment
setup.
* Permission recovery/chown behavior is more consistent, with
backward-compatible fallback for older images or ownership drift.
* **Tests**
* Added BATS coverage validating `HOST_UID`/`HOST_GID` emission and
stability of golden comparisons by masking host-specific values.
  * Improved BATS harness sourcing for hermetic function-only execution.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: bradymiller

.github/workflows/test-bats-openemr-cmd-real-docker.yml

@@ -339,16 +339,12 @@ jobs:
           grep -E '^test-e2e[[:space:]]+.*[[:space:]]none[[:space:]]' <<< "${out}" \
               || { echo "FAIL: 'test-e2e' not listed with status=none"; exit 1; }
 
-      - name: One-shot chown back to runner (enables host-side regen + set-env)
-        run: |
-          # openemr's container startup chowned the whole bind mount to
-          # apache during install, so host-side host-uid operations
-          # (regen writing .env, set-env creating new env dir files)
-          # would fail with EACCES. Chown back to runner once now (stack
-          # is down, no race). The auto-chown step on the eventual
-          # `worktree remove` (when stack is back up) will handle any
-          # further apache-writes between then and now.
-          sudo chown -R "$(id -u):$(id -g)" "${{ github.workspace }}/openemr-wt-test-e2e"
+      # NOTE: a `sudo chown -R "$(id -u):$(id -g)" .../openemr-wt-test-e2e`
+      # step used to live here to recover from apache (uid=1000) chowning
+      # the bind mount during install. With HOST_UID passthrough now in
+      # wt_write_override, apache adopts the runner's uid at boot and the
+      # bind mount stays runner-owned — host-side regen + set-env writes
+      # work without any chown dance.
 
       - name: "worktree regen: rewrites a stomped .env back to canonical contents"
         working-directory: openemr
@@ -1241,21 +1237,12 @@ jobs:
           docker logs "${cname}" --tail 500
           exit 1
 
-      - name: One-shot chown back to runner (enables host-side writes + git commits)
-        run: |
-          # openemr's container startup chowns the whole webroot bind
-          # mount to apache (uid=1000), but `git commit` runs as the
-          # runner (different uid) and needs to write into the working
-          # tree (probe file) and update .git/worktrees/prek-e2e/index
-          # via `git add`. Chown back now that healthy confirms apache
-          # is done with its setup pass. Apache may log a few EACCES
-          # warnings on subsequent /meta/health/readyz probes, but the
-          # prek tests below don't depend on apache continuing to
-          # serve — only on the container being reachable for
-          # `docker exec` (which runs as root, sidestepping the
-          # bind-mount uid mismatch). The eventual `worktree remove`
-          # auto-chown handles the symmetric case for teardown.
-          sudo chown -R "$(id -u):$(id -g)" "${{ github.workspace }}/openemr-wt-prek-e2e"
+      # NOTE: a `sudo chown -R "$(id -u):$(id -g)" .../openemr-wt-prek-e2e`
+      # step used to live here to recover from apache (uid=1000) chowning
+      # the bind mount during install. With HOST_UID passthrough now in
+      # wt_write_override, apache adopts the runner's uid at boot and the
+      # bind mount stays runner-owned — `git commit` from the worktree
+      # works without any chown dance.
 
       - name: openemr-cmd prek-install (writes shim hooks to shared .git/hooks)
         working-directory: openemr-wt-prek-e2e

tests/bats/openemr-cmd/copy_base_env.bats

@@ -31,11 +31,11 @@ teardown() {
 oc_run_in_funcs() {
     local snippet=$1
     local script_path=$2
-    local funcs_end=$3
-    local tmp_root=$4
+    local tmp_root=$3
     run env OPENEMR_ROOT="${tmp_root}" bash -c "
         set -euo pipefail
-        eval \"\$(head -n ${funcs_end} '${script_path}')\"
+        __OPENEMR_CMD_SOURCE_FUNCS_ONLY=1
+        source '${script_path}'
         ${snippet}
     "
 }
@@ -52,7 +52,7 @@ oc_file_mode() {
 
 @test "wt_copy_base_env: no-op when source .env is missing" {
     oc_run_in_funcs "wt_copy_base_env '${PRIMARY}' '${DEST}'" \
-        "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+        "$SCRIPT" "$TMP_ROOT"
     assert_success
     [[ ! -e "${DEST}/.env" ]]
 }
@@ -62,7 +62,7 @@ oc_file_mode() {
     echo "EVIL=1" > "${TMP_ROOT}/outside"
     ln -s "${TMP_ROOT}/outside" "${PRIMARY}/.env"
     oc_run_in_funcs "wt_copy_base_env '${PRIMARY}' '${DEST}'" \
-        "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+        "$SCRIPT" "$TMP_ROOT"
     assert_success
     [[ ! -e "${DEST}/.env" ]]
 }
@@ -71,7 +71,7 @@ oc_file_mode() {
     printf 'OPENEMR__ENVIRONMENT=dev\n' > "${PRIMARY}/.env"
     chmod 600 "${PRIMARY}/.env"
     oc_run_in_funcs "wt_copy_base_env '${PRIMARY}' '${DEST}'" \
-        "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+        "$SCRIPT" "$TMP_ROOT"
     assert_success
     assert_output --partial "Copied base .env"
     [[ -f "${DEST}/.env" ]]
@@ -84,7 +84,7 @@ oc_file_mode() {
     printf 'NEW=1\n' > "${PRIMARY}/.env"
     printf 'OLD=1\n' > "${DEST}/.env"
     oc_run_in_funcs "wt_copy_base_env '${PRIMARY}' '${DEST}'" \
-        "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+        "$SCRIPT" "$TMP_ROOT"
     assert_success
     refute_output --partial "Copied base .env"
     grep -q "^OLD=1$" "${DEST}/.env"
@@ -97,7 +97,7 @@ oc_file_mode() {
     printf 'NEW=1\n' > "${PRIMARY}/.env"
     ln -s "${TMP_ROOT}/should-not-exist" "${DEST}/.env"
     oc_run_in_funcs "wt_copy_base_env '${PRIMARY}' '${DEST}'" \
-        "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+        "$SCRIPT" "$TMP_ROOT"
     assert_success
     refute_output --partial "Copied base .env"
     [[ -L "${DEST}/.env" ]]

tests/bats/openemr-cmd/goldens/easy-light/override.yml

@@ -27,6 +27,9 @@ volumes:
 
 services:
   openemr:
+    environment:
+      HOST_UID: "__HOST_UID__"
+      HOST_GID: "__HOST_GID__"
     volumes:
       - "__TMP_PARENT__/primary/.git:__TMP_PARENT__/primary/.git:rw"
 

tests/bats/openemr-cmd/goldens/easy-redis/override.yml

@@ -29,6 +29,9 @@ volumes:
 
 services:
   openemr:
+    environment:
+      HOST_UID: "__HOST_UID__"
+      HOST_GID: "__HOST_GID__"
     volumes:
       - "__TMP_PARENT__/primary/.git:__TMP_PARENT__/primary/.git:rw"
       - "__TMP_PARENT__/openemr-wt-golden-easy-redis/docker/development-easy-redis/php.ini:/usr/local/etc/php/php.ini:ro"

tests/bats/openemr-cmd/goldens/easy/override.yml

@@ -29,6 +29,9 @@ volumes:
 
 services:
   openemr:
+    environment:
+      HOST_UID: "__HOST_UID__"
+      HOST_GID: "__HOST_GID__"
     volumes:
       - "__TMP_PARENT__/primary/.git:__TMP_PARENT__/primary/.git:rw"
 

tests/bats/openemr-cmd/helpers.bash

@@ -72,30 +72,25 @@ STUB
     echo "${d}"
 }
 
-# Line number that marks the end of function definitions in the script
-# (the last '}' before USAGE_EXIT_CODE=13 and the dispatch logic). Sourcing
-# only the first OC_SCRIPT_FUNCS_END lines gives us a library-like view of
-# the script: every function defined, no main-line dispatch executed.
-# If the script is restructured, bump this constant — the test
-# 'OC_SCRIPT_FUNCS_END points at end of function defs' in helpers_pure.bats
-# will fail loudly when it drifts.
-OC_SCRIPT_FUNCS_END=1882
-
 # Source ONLY the function definitions of openemr-cmd into the current shell.
 # Caller is responsible for setting OPENEMR_ROOT (and WT_STATE_FILE / others
 # as needed) BEFORE calling, since the script's top-level OPENEMR_ROOT
 # assignment runs while sourcing.
 #
+# Mechanism: set __OPENEMR_CMD_SOURCE_FUNCS_ONLY=1 before sourcing. The
+# script has a guard right after the last function definition that
+# `return 0`s when the flag is set, short-circuiting the dispatch /
+# top-level statements. Replaces an earlier head -n N approach that
+# required a magic line-number constant kept in sync with end-of-
+# functions via a drift sentinel — broke on every refactor.
+#
 # Usage (inside a 'bash -c' inside @test):
 #   oc_source_funcs
 #   wt_slug feature/foo
 oc_source_funcs() {
     local script
     script=$(oc_script_path) || return 1
-    # eval, not 'source <(...)': process substitution is broken under macOS
-    # system bash 3.2, where <() fails to define the sourced functions.
-    # shellcheck disable=SC2312
-    eval "$(head -n "${OC_SCRIPT_FUNCS_END}" "${script}")"
+    __OPENEMR_CMD_SOURCE_FUNCS_ONLY=1 source "${script}"
 }
 
 # Initialize $1 as a real git repo with one commit, so commands like

tests/bats/openemr-cmd/helpers_pure.bats

@@ -30,45 +30,46 @@ oc_run_in_funcs() {
         set -euo pipefail
         # eval, not 'source <(...)': process substitution is broken under
         # macOS system bash 3.2, where <() fails to define the functions.
-        eval \"\$(head -n ${funcs_end} '${script_path}')\"
+        __OPENEMR_CMD_SOURCE_FUNCS_ONLY=1
+        source '${script_path}'
         ${snippet}
     "
 }
 
 # --- wt_slug -----------------------------------------------------------------
 
 @test "wt_slug: slash becomes dash" {
-    oc_run_in_funcs 'wt_slug feature/foo' "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+    oc_run_in_funcs 'wt_slug feature/foo' "$SCRIPT" "$TMP_ROOT"
     assert_success
     assert_output "feature-foo"
 }
 
 @test "wt_slug: uppercase is lowercased" {
-    oc_run_in_funcs 'wt_slug UPPER' "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+    oc_run_in_funcs 'wt_slug UPPER' "$SCRIPT" "$TMP_ROOT"
     assert_success
     assert_output "upper"
 }
 
 @test "wt_slug: spaces and special chars are stripped" {
-    oc_run_in_funcs "wt_slug 'with spaces!'" "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+    oc_run_in_funcs "wt_slug 'with spaces!'" "$SCRIPT" "$TMP_ROOT"
     assert_success
     assert_output "withspaces"
 }
 
 @test "wt_slug: mixed case + slash + special chars" {
-    oc_run_in_funcs "wt_slug 'Feature/My-Thing!'" "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+    oc_run_in_funcs "wt_slug 'Feature/My-Thing!'" "$SCRIPT" "$TMP_ROOT"
     assert_success
     assert_output "feature-my-thing"
 }
 
 @test "wt_slug: empty input -> empty output (deterministic, not an error)" {
-    oc_run_in_funcs "wt_slug ''" "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+    oc_run_in_funcs "wt_slug ''" "$SCRIPT" "$TMP_ROOT"
     assert_success
     assert_output ""
 }
 
 @test "wt_slug: non-ASCII chars stripped, surrounding ASCII survives" {
-    oc_run_in_funcs "wt_slug 'résumé'" "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+    oc_run_in_funcs "wt_slug 'résumé'" "$SCRIPT" "$TMP_ROOT"
     assert_success
     # `tr -cd 'a-zA-Z0-9_-'` operates byte-by-byte; the 2-byte UTF-8
     # sequences for é (0xc3 0xa9) get dropped, leaving the ASCII letters
@@ -77,7 +78,7 @@ oc_run_in_funcs() {
 }
 
 @test "wt_slug: non-ASCII alongside ASCII keeps only the ASCII alnum/_/-" {
-    oc_run_in_funcs "wt_slug 'foo-bär-baz'" "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+    oc_run_in_funcs "wt_slug 'foo-bär-baz'" "$SCRIPT" "$TMP_ROOT"
     assert_success
     # The ä is dropped; foo and baz survive with dashes intact.
     assert_output "foo-br-baz"
@@ -87,78 +88,108 @@ oc_run_in_funcs() {
     # tr -cd '[a-zA-Z0-9_-]' allows '-' anywhere including as the first char.
     # This test pins the current behavior so anyone trying to harden it
     # (e.g., refuse slugs starting with -) updates this test deliberately.
-    oc_run_in_funcs "wt_slug '-evil'" "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+    oc_run_in_funcs "wt_slug '-evil'" "$SCRIPT" "$TMP_ROOT"
     assert_success
     assert_output "-evil"
 }
 
 @test "wt_slug: long input is passed through unchanged (no truncation)" {
     local long
     long="aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
-    oc_run_in_funcs "wt_slug '${long}'" "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+    oc_run_in_funcs "wt_slug '${long}'" "$SCRIPT" "$TMP_ROOT"
     assert_success
     assert_output "${long}"
 }
 
 # --- wt_compose_subdir -------------------------------------------------------
 
 @test "wt_compose_subdir: easy" {
-    oc_run_in_funcs 'wt_compose_subdir easy' "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+    oc_run_in_funcs 'wt_compose_subdir easy' "$SCRIPT" "$TMP_ROOT"
     assert_success
     assert_output "docker/development-easy"
 }
 
 @test "wt_compose_subdir: easy-light" {
-    oc_run_in_funcs 'wt_compose_subdir easy-light' "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+    oc_run_in_funcs 'wt_compose_subdir easy-light' "$SCRIPT" "$TMP_ROOT"
     assert_success
     assert_output "docker/development-easy-light"
 }
 
 @test "wt_compose_subdir: easy-redis" {
-    oc_run_in_funcs 'wt_compose_subdir easy-redis' "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+    oc_run_in_funcs 'wt_compose_subdir easy-redis' "$SCRIPT" "$TMP_ROOT"
     assert_success
     assert_output "docker/development-easy-redis"
 }
 
 # --- wt_validate_env ---------------------------------------------------------
 
 @test "wt_validate_env: accepts easy" {
-    oc_run_in_funcs 'wt_validate_env easy && echo ok' "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+    oc_run_in_funcs 'wt_validate_env easy && echo ok' "$SCRIPT" "$TMP_ROOT"
     assert_success
     assert_output "ok"
 }
 
 @test "wt_validate_env: accepts easy-light" {
-    oc_run_in_funcs 'wt_validate_env easy-light && echo ok' "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+    oc_run_in_funcs 'wt_validate_env easy-light && echo ok' "$SCRIPT" "$TMP_ROOT"
     assert_success
     assert_output "ok"
 }
 
 @test "wt_validate_env: accepts easy-redis" {
-    oc_run_in_funcs 'wt_validate_env easy-redis && echo ok' "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+    oc_run_in_funcs 'wt_validate_env easy-redis && echo ok' "$SCRIPT" "$TMP_ROOT"
     assert_success
     assert_output "ok"
 }
 
 @test "wt_validate_env: rejects bogus env with error message" {
-    oc_run_in_funcs 'wt_validate_env bogus 2>&1' "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+    oc_run_in_funcs 'wt_validate_env bogus 2>&1' "$SCRIPT" "$TMP_ROOT"
     assert_failure
     assert_output --partial "Invalid env 'bogus'"
 }
 
 @test "wt_validate_env: rejects empty env" {
-    oc_run_in_funcs "wt_validate_env '' 2>&1" "$SCRIPT" "${OC_SCRIPT_FUNCS_END}" "$TMP_ROOT"
+    oc_run_in_funcs "wt_validate_env '' 2>&1" "$SCRIPT" "$TMP_ROOT"
     assert_failure
 }
 
-# --- oc_funcs_source_line is current ----------------------------------------
-# If someone restructures openemr-cmd and our OC_SCRIPT_FUNCS_END constant
-# drifts (e.g. someone adds another function above the dispatch), this test
-# catches it loudly: line OC_SCRIPT_FUNCS_END+1 must be 'USAGE_EXIT_CODE=13'
-# or very close to it, signalling the end of the function-defs section.
-
-@test "OC_SCRIPT_FUNCS_END points at end of function defs (USAGE_EXIT_CODE follows)" {
-    run sed -n "$((OC_SCRIPT_FUNCS_END+1)),$((OC_SCRIPT_FUNCS_END+3))p" "$SCRIPT"
+# --- source guard for functions-only sourcing -------------------------------
+# Replaces the previous OC_SCRIPT_FUNCS_END line-counter drift sentinel.
+# The script now has a __OPENEMR_CMD_SOURCE_FUNCS_ONLY=1 guard right
+# after the last function def that returns from sourcing before any
+# dispatch runs. This test pins both ends of the contract: the guard
+# is present in the script AND it actually short-circuits sourcing.
+
+@test "source-funcs-only guard: sourcing with the flag set defines functions but skips dispatch" {
+    # Sourcing the script with the flag set should define wt_slug
+    # (a function) without printing the version banner / running any
+    # other dispatch-side output. Confirm by capturing the return-
+    # from-source state: wt_slug works; the script didn't run main
+    # dispatch (no USAGE_EXIT_CODE print, no docker probe, etc.).
+    run env OPENEMR_ROOT="${TMP_ROOT:-/tmp}" bash -c "
+        set -euo pipefail
+        __OPENEMR_CMD_SOURCE_FUNCS_ONLY=1
+        source '$SCRIPT'
+        # Sourcing returned cleanly; wt_slug defined and callable.
+        wt_slug 'feature/foo'
+    "
     assert_success
-    assert_output --partial "USAGE_EXIT_CODE="
+    assert_output "feature-foo"
+}
+
+@test "source-funcs-only guard: direct execution is unaffected by the flag (script runs normally)" {
+    # Without the env var, direct execution must work as before:
+    # --version exits with VERSION_EXIT_CODE (14) and prints the
+    # canonical "openemr-cmd <ver>" banner.
+    #
+    # Note: the script's docker-availability check (DOCKER_CODE=16)
+    # runs BEFORE --version parsing — macOS GH-hosted runners don't
+    # have docker installed, so we stub it via the same helper the
+    # other hermetic tests use. The stub satisfies `command -v docker`
+    # without invoking real docker.
+    local stub_dir
+    stub_dir=$(oc_make_docker_stub_dir)
+    run env PATH="${stub_dir}:${PATH}" "$SCRIPT" --version
+    rm -rf "${stub_dir}"
+    [[ "${status}" -eq 14 ]] || fail "expected exit 14 (VERSION_EXIT_CODE), got ${status}"
+    [[ "${output}" =~ ^openemr-cmd[[:space:]] ]] || fail "expected version banner, got: ${output}"
 }