test-infra: `_make_docker_stub` unquoted heredoc in `preflight-docker-desktop.bats` is a future-caller footgun

[yasinBursali]

Bug Report

Severity: Trivial (footgun documented inline; current tests pass clean strings)
Category: Test infrastructure quoting
Platforms: Linux + macOS (BATS); Windows-WSL2 same as Linux
Confidence: Confirmed (static)

Description

_make_docker_stub() in dream-server/tests/bats-tests/preflight-docker-desktop.bats (added by PR Light-Heart-Labs#1102) uses an unquoted <<MOCK heredoc, which means $message is shell-expanded into the stub script at write time:

_make_docker_stub() {
    local message="$1"
    local exit_code="$2"
    # NOTE: unquoted heredoc — $message is shell-expanded into the stub at
    # write time; pass only literal strings (no $, backticks, or backslashes)
    # or the substitution will run in this shell rather than the stub.
    cat > "$STUB_BIN/docker" <<MOCK
#!/bin/bash
echo "$message" >&2
exit $exit_code
MOCK
}

The 3-line inline NOTE flags this; current tests honor the constraint by passing only literal strings without shell metacharacters. A future test case that passes $/backticks/\\ in message would silently fail because the metacharacters expand in the calling shell rather than at stub-execution time.

Affected Files

• dream-server/tests/bats-tests/preflight-docker-desktop.bats — _make_docker_stub() definition (around line 41 of PR test: behavioral host-agent install poll + bats resolver/preflight + pre-commit shellcheck Light-Heart-Labs/DreamServer#1102).

Suggested Approach

Two valid mechanics:

Option A (preferred): Change to <<'MOCK' (single-quoted) and inject the message via positional arg:

_make_docker_stub() {
    local message="$1"
    local exit_code="$2"
    cat > "$STUB_BIN/docker" <<'MOCK'
#!/bin/bash
echo "$DOCKER_STUB_MESSAGE" >&2
exit "$DOCKER_STUB_EXIT_CODE"
MOCK
    chmod +x "$STUB_BIN/docker"
    export DOCKER_STUB_MESSAGE="$message"
    export DOCKER_STUB_EXIT_CODE="$exit_code"
}

Option B: Templated sed substitution after writing the literal heredoc — also works, slightly more code.

Surfaced by

PR-X (test: behavioral host-agent install poll + bats resolver/preflight + pre-commit shellcheck, upstream PR Light-Heart-Labs#1102) — CG review noted the constraint; operator declined to apply the fix during the polish round (the inline NOTE is sufficient for current callers). Tracked for follow-up.

Test environment

• Reproduction: Add a BATS case calling _make_docker_stub 'error: $unknown_var failed' 1 — $unknown_var resolves to empty in the test shell, the stub writes error: failed to stderr at runtime. Caller fooled.