A large file pasted as a heredoc lands with broken newlines and an early EOF

Symptom

A 100-plus-line file was exported into chat as a cat > file <<'EOF' block and the operator pasted it into an SSH session. The live copy was overwritten with a syntactically broken file and every call through that path died. Chapter 01's heredoc-emoji entry is the encoding layer; this is the layer where the paste itself breaks newlines and EOF.

Cause

Pasting is not copying a file.

• Terminals and SSH clients stream long input line by line and insert auto-newlines and line-ending conversions. Some auto-align brackets or smart-convert quotes.
• If the body contains a token that resembles the delimiter, EOF is caught early.
• The longer the file, the higher the odds. A method that worked on short snippets betrays you on a big one.

Fix — download, check, swap atomically

cp app.php app.php.bak.$(date +%F-%H%M)        # 1) back up first
curl -fsSL -H "Authorization: token $TOKEN" \
     -H "Accept: application/vnd.github.raw" \
     "https://api.github.com/repos/<org>/<repo>/contents/<path>?ref=main" \
     -o app.php.new                              # 2) raw + token, into .new
php -l app.php.new                               # 3) only if the syntax check passes
mv app.php.new app.php                           # 4) mv = atomic swap

• A private repo needs the token; the bare raw URL returns 404.
• Download into .new so that the current file survives an interrupted transfer.
• mv is atomic on the same filesystem, so there is no instant where a half-written file is served. Rollback is mv from the .bak.

Same root, second incident — the replacement invented its secret loading

The replacement uploaded to clean up the heredoc incident killed the relay again. Not syntax this time: the key. The replacement read the key with getenv(); the original read it from a secrets file above the docroot. Shared-hosting PHP cannot see a shell export — an environment variable set in SSH does not exist in the web request process.

The blind spot: "I couldn't see the current file, so I rewrote it from the protocol contract." Request and response shapes were documented, but secret loading, paths and side logic are outside the contract, and those blanks got filled in plausibly. Plausible is invented.

• Never write a replacement from the protocol contract alone. A contract is an interface, not an implementation.
• Secrets, paths and side logic only after measuring the original. If you can't see it, ask for one line: grep -n 'getenv\|secret' <file>. If it can't be measured, leave that part blank and say so.
• A syntax check cannot catch invented secret loading. Add a key-loading grep to the deploy gate.

Verification

php -l passes, the key-loading grep matches the original, and one real call on live gets through authentication.

★ The delivery mechanism is part of the design. Correct content moved the wrong way still breaks live. "Print the whole file into chat" is for a human to read, not for a machine to transcribe — a machine gets a link and a verification procedure. Backing up first is not a cost; it's insurance.

---

---