fix(repo): stop git corrupting binaries, and drop 7 dead PNGs it already ate (#2433)

`.gitattributes` was one line, `* text=auto`, with no binary rules. So git
treated `.png` as text and rewrote every `0D 0A` inside it to `0A` on commit. A
PNG opens `89 50 4E 47 0D 0A 1A 0A`; the tracked ones open
`89 50 4E 47 0A 1A 0A 00`. 14 were committed already broken in 2024 and stayed
that way for over a year, until the frontend build started reading them and
`ts-images` refused - correctly, they are not PNGs any more.

87 tracked files match the extensions now marked binary, and every one of them
was exposed to this. That rule has to land before anything is re-added, or the
same normalisation eats the replacement on commit.

The damage cannot be undone: only `0D` bytes that preceded `0A` were dropped,
so nothing records which surviving `0A` used to have one. Of the 14, seven are
referenced by nothing at all - `git grep` finds no use of
`public/images/screenshots/*.png` in any template, script, doc or style - so
they are deleted rather than carried as debt.

The other seven ARE referenced (`Testimonials.stx` uses the five avatars, the
Vue and web examples use the favicons) and need their originals re-added, which
this repository cannot supply: the only commit that ever touched them,
`970bd55b92`, already carried the damage.

`tracked-images-are-valid.test.ts` checks magic bytes on every tracked image -
34 today, 27 valid. The seven are listed as known-corrupt, and a second test
fails if any of them turns out to be VALID, so repairing one forces its removal
from the list instead of leaving a permanent exemption. Verified both ways: a
newly added broken PNG is named, and so is a knownCorrupt file given a good
header.

Refs #2433

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: chrisbbreuer

.gitattributes

@@ -1 +1,35 @@
 * text=auto
+
+# Binary formats must never be line-ending normalised.
+#
+# With `* text=auto` alone, git treated `.png` as text and rewrote every
+# `0D 0A` inside it to `0A` on commit. That destroys the file: a PNG starts
+# `89 50 4E 47 0D 0A 1A 0A`, and 14 tracked images were committed already
+# broken in 2024 and stayed that way for over a year (stacksjs/stacks#2433).
+# The damage is not reversible - only the `0D` bytes that happened to precede
+# `0A` were dropped, so there is no way to tell which survivors used to have
+# one.
+#
+# 87 tracked files match these extensions, and every one of them was exposed.
+*.png  binary
+*.jpg  binary
+*.jpeg binary
+*.gif  binary
+*.webp binary
+*.avif binary
+*.ico  binary
+*.icns binary
+*.woff  binary
+*.woff2 binary
+*.ttf  binary
+*.otf  binary
+*.eot  binary
+*.pdf  binary
+*.zip  binary
+*.gz   binary
+*.mp4  binary
+*.mov  binary
+*.mp3  binary
+*.wav  binary
+*.dmg  binary
+*.wasm binary

public/images/screenshots/contacts.png

@@ -0,0 +1,94 @@
+/**
+ * Every tracked image really is the format its extension claims.
+ *
+ * `.gitattributes` was a single `* text=auto` line with no binary rules, so git
+ * treated `.png` as text and rewrote every `0D 0A` inside it to `0A` on commit.
+ * A PNG opens `89 50 4E 47 0D 0A 1A 0A`; these became `89 50 4E 47 0A 1A 0A 00`.
+ * 14 images were committed already broken in 2024 and stayed that way for over
+ * a year, until the frontend build started reading them and `ts-images`
+ * correctly refused (stacksjs/stacks#2433).
+ *
+ * The corruption is not reversible - only `0D` bytes that preceded `0A` were
+ * dropped, so nothing records which survivors used to have one. The files have
+ * to be re-added from their originals.
+ *
+ * This checks magic bytes rather than decoding: it is the cheap half, it is
+ * what actually broke, and it would have caught this on the commit that
+ * introduced it.
+ */
+import { describe, expect, it } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { extname, join } from 'node:path'
+import { $ } from 'bun'
+
+const root = new URL('../../../../../', import.meta.url).pathname
+
+/** First bytes each format must start with. */
+const signatures: Record<string, Uint8Array[]> = {
+  '.png': [new Uint8Array([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A])],
+  '.jpg': [new Uint8Array([0xFF, 0xD8, 0xFF])],
+  '.jpeg': [new Uint8Array([0xFF, 0xD8, 0xFF])],
+  '.gif': [new Uint8Array([0x47, 0x49, 0x46, 0x38, 0x37, 0x61]), new Uint8Array([0x47, 0x49, 0x46, 0x38, 0x39, 0x61])],
+  '.webp': [new Uint8Array([0x52, 0x49, 0x46, 0x46])],
+  '.ico': [new Uint8Array([0x00, 0x00, 0x01, 0x00])],
+}
+
+/**
+ * Files known to be destroyed, still tracked because something references them
+ * and no original is available in this repository - the only commit that ever
+ * touched them already carried the damage. Replace the file, then delete its
+ * line here; the test below fails if one of these turns out to be valid, so the
+ * list cannot rot into a permanent exemption.
+ */
+const knownCorrupt = new Set<string>([
+  'public/images/avatars/avatar-1.png',
+  'public/images/avatars/avatar-2.png',
+  'public/images/avatars/avatar-3.png',
+  'public/images/avatars/avatar-4.png',
+  'public/images/avatars/avatar-5.png',
+  'storage/framework/libs/examples/vue/favicon.png',
+  'storage/framework/libs/examples/web/favicon.png',
+])
+
+function startsWith(head: Uint8Array, signature: Uint8Array): boolean {
+  return signature.every((byte, index) => head[index] === byte)
+}
+
+async function trackedImages(): Promise<Array<{ file: string, valid: boolean }>> {
+  const tracked = (await $`git ls-files`.cwd(root).quiet()).text().split('\n').filter(Boolean)
+
+  return tracked
+    .filter(file => extname(file).toLowerCase() in signatures)
+    .map((file) => {
+      let head: Uint8Array
+      try {
+        head = readFileSync(join(root, file)).subarray(0, 12)
+      }
+      catch {
+        // Absent from the working tree mid-rebase; not this test's business.
+        return { file, valid: true }
+      }
+
+      const accepted = signatures[extname(file).toLowerCase()]!
+      return { file, valid: accepted.some(signature => startsWith(head, signature)) }
+    })
+}
+
+describe('tracked images', () => {
+  it('all start with their format\'s magic bytes', async () => {
+    const broken = (await trackedImages())
+      .filter(image => !image.valid && !knownCorrupt.has(image.file))
+      .map(image => image.file)
+
+    expect(broken.sort()).toEqual([])
+  })
+
+  it('lists no file under knownCorrupt that has since been repaired', async () => {
+    const images = await trackedImages()
+    const repaired = images.filter(image => image.valid && knownCorrupt.has(image.file)).map(image => image.file)
+
+    // Removing the line is the last step of the fix, not an optional tidy-up:
+    // left in place, it would exempt a good file from ever being checked again.
+    expect(repaired.sort()).toEqual([])
+  })
+})