P10: add quality guards and finish showcase

* fix: render historical snake segment colors

* fix: validate GIF output and create parent directory

* feat: add animation and artifact quality guards

* test: cover animation quality limits

* chore: keep deterministic test command

* ci: validate and regenerate snake on main updates

* docs: finish project showcase and architecture

Author: codelovingcat

.github/workflows/generate-snake.yml

@@ -2,6 +2,8 @@ name: Generate GitHub Snake
 
 on:
   workflow_dispatch:
+  push:
+    branches: [main]
   schedule:
     - cron: "17 3 * * 0"
 
@@ -24,10 +26,12 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 22
-          cache: npm
 
       - name: Install dependencies
-        run: npm ci
+        run: npm install --no-audit --no-fund
+
+      - name: Run tests
+        run: npm test
 
       - name: Generate snake
         env:
@@ -36,25 +40,24 @@ jobs:
         run: npm run generate
 
       - name: Publish generated artifact
-        env:
-          GH_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
+          mkdir -p output-branch
+
           if git ls-remote --exit-code --heads origin output >/dev/null 2>&1; then
             git fetch origin output
             git worktree add --detach output-branch origin/output
-            rm -f output-branch/snake.gif
           else
             git worktree add --detach output-branch
             git -C output-branch checkout --orphan output
             git -C output-branch rm -rf . >/dev/null 2>&1 || true
           fi
 
+          rm -f output-branch/snake.gif
           cp output/snake.gif output-branch/snake.gif
-          printf '%s\n' '<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"><rect width="1" height="1" fill="#0d1117"/></svg>' > output-branch/README.svg
-          git -C output-branch add snake.gif README.svg
+          git -C output-branch add snake.gif
           git -C output-branch commit -m "chore: publish snake artifact" || true
           git -C output-branch push origin HEAD:output

README.md

@@ -1,35 +1,54 @@
 # 🐍 GitHub Snake Remix
 
-A custom GitHub contribution snake animation built from scratch with **TypeScript + SVG**.
+A custom GitHub contribution snake animation built from scratch with **TypeScript + SVG**, then encoded to an animated GIF for profile embedding.
 
 This project is intentionally independent from the original profile-repository snake and does **not** use Platane/snk.
 
-## Current architecture
+## How it works
 
 ```text
-Contribution data
+GitHub GraphQL
       ↓
-Domain model
+Contribution calendar
       ↓
-Snake engine
+Deterministic grid
       ↓
-SVG renderer
+Custom snake path
       ↓
-snake.svg
+Growth + contribution colors
+      ↓
+Animation timeline
+      ↓
+SVG frame renderer
+      ↓
+Animated GIF
+      ↓
+output/snake.gif
 ```
 
-The core engine is GitHub-agnostic. GitHub API access and GitHub Actions publishing will be added separately.
+## Visual rules
 
-## Contribution colors
+The snake grows by one segment when it consumes a non-empty contribution cell.
 
-Non-empty contribution levels use four green shades:
+Each new segment keeps the contribution intensity it consumed:
 
 - Level 1 → light green
 - Level 2 → medium green
 - Level 3 → dark green
 - Level 4 → deepest green
 
-Empty cells use a dark GitHub-style background.
+The background follows GitHub's dark visual style.
+
+## Quality guards
+
+The generator rejects:
+
+- empty animation timelines
+- runaway frame counts above 500
+- invalid GIF headers
+- missing/empty artifacts
+- GIFs larger than 1.5 MB
+- unreasonable output dimensions
 
 ## Local development
 
@@ -39,21 +58,26 @@ npm test
 npm run build
 ```
 
-## Design principles
+To generate against real GitHub data locally:
+
+```bash
+CONTRIBUTION_TOKEN=... npm run generate
+```
+
+Keep the token in your shell environment or a secret manager. Never commit it.
+
+## GitHub Action
+
+The workflow supports manual dispatch, weekly regeneration and regeneration after changes land on `main`.
 
-- TypeScript with strict compiler settings.
-- Deterministic animation state.
-- SVG output rather than a browser-only animation.
-- No GitHub token in source code.
-- No dependency on the old profile repository.
-- Small, testable core before adding GitHub data and automation.
+The contribution calendar is read with `CONTRIBUTION_TOKEN`. The workflow's built-in `GITHUB_TOKEN` is used only for publishing the generated artifact.
 
 ## Profile output
 
-The generated animation is published to the `output` branch by GitHub Actions.
+The generated public artifact is published to the `output` branch:
 
 ```html
 <img src="https://raw.githubusercontent.com/codelovingcat/github-snake-remix/output/snake.gif" alt="GitHub contribution snake" />
 ```
 
-Set the repository secret `CONTRIBUTION_TOKEN` before running the workflow.
+Set the repository secret `CONTRIBUTION_TOKEN` before the first generation run.

src/gif-output.ts

@@ -1,17 +1,18 @@
 import fs from "node:fs/promises";
 import { createWriteStream } from "node:fs";
-import { Readable } from "node:stream";
 import GIFEncoder from "gif-encoder-2";
 import sharp from "sharp";
 import type { AnimationFrame } from "./animation-timeline.js";
 import { renderSvg } from "./svg-renderer.js";
+import { validateGifArtifact, validateAnimationFrameCount } from "./quality.js";
 
 export interface GifOptions {
   readonly width?: number;
   readonly height?: number;
   readonly delayMilliseconds?: number;
   readonly repeat?: number;
   readonly quality?: number;
+  readonly maxBytes?: number;
 }
 
 export async function renderAnimatedGif(
@@ -21,7 +22,11 @@ export async function renderAnimatedGif(
   outputPath: string,
   options: GifOptions = {}
 ): Promise<void> {
-  if (frames.length === 0) throw new Error("At least one animation frame is required.");
+  validateAnimationFrameCount(frames.length);
+
+  if (columns < 1 || rows < 1) {
+    throw new Error("GIF grid dimensions must be positive.");
+  }
 
   const cellSize = 12;
   const gap = 3;
@@ -31,53 +36,69 @@ export async function renderAnimatedGif(
   const repeat = options.repeat ?? 0;
   const quality = options.quality ?? 10;
 
-  if (width <= 0 || height <= 0 || delay <= 0 || quality < 1 || quality > 30) {
-    throw new Error("Invalid GIF output options.");
+  if (width <= 0 || height <= 0 || width > 1000 || height > 300 || delay <= 0 || quality < 1 || quality > 30) {
+    throw new Error("Invalid GIF output dimensions or encoding options.");
   }
 
+  await fs.mkdir(new URL(".", `file://${outputPath}`).pathname, { recursive: true });
+
   const encoder = new GIFEncoder(width, height);
   encoder.setRepeat(repeat);
   encoder.setDelay(delay);
   encoder.setQuality(quality);
 
   await new Promise<void>((resolve, reject) => {
     const output = createWriteStream(outputPath);
-    encoder.createReadStream().pipe(output);
     output.on("finish", resolve);
     output.on("error", reject);
-    encoder.start();
+
+    const stream = encoder.createReadStream();
+    stream.on("error", reject);
+    stream.pipe(output);
 
     void (async () => {
       try {
+        encoder.start();
+
         for (const frame of frames) {
           const svg = renderSvg(
-            frame.state.segments.map((segment) => ({
-              x: segment.position.x,
-              y: segment.position.y,
-              level: segment.level
-            })),
+            framesToCells(frame),
             frame.state,
             columns,
             rows
           );
-          const png = await sharp(Buffer.from(svg)).png().raw().toBuffer({ resolveWithObject: true });
+          const png = await sharp(Buffer.from(svg))
+            .png()
+            .raw()
+            .toBuffer({ resolveWithObject: true });
           encoder.addFrame(png.data);
         }
+
         encoder.finish();
       } catch (error) {
         encoder.abort();
         reject(error);
       }
     })();
   });
+
+  await validateGifArtifact(outputPath, options.maxBytes);
+}
+
+function framesToCells(frame: AnimationFrame) {
+  return frame.state.segments.map((segment) => ({
+    x: segment.position.x,
+    y: segment.position.y,
+    level: segment.level
+  }));
 }
 
 export async function writeAnimatedGif(
   frames: readonly AnimationFrame[],
   columns: number,
   rows: number,
-  outputPath: string
+  outputPath: string,
+  options: GifOptions = {}
 ): Promise<void> {
-  await fs.mkdir(new URL(".", `file://${outputPath}`).pathname, { recursive: true }).catch(() => undefined);
-  await renderAnimatedGif(frames, columns, rows, outputPath);
+  await renderAnimatedGif(frames, columns, rows, outputPath, options);
 }

src/quality.ts

@@ -0,0 +1,38 @@
+import fs from "node:fs/promises";
+
+export const MAX_ANIMATION_FRAMES = 500;
+export const MAX_GIF_BYTES = 1_500_000;
+
+export function validateAnimationFrameCount(frameCount: number): void {
+  if (!Number.isInteger(frameCount) || frameCount < 1 || frameCount > MAX_ANIMATION_FRAMES) {
+    throw new Error(`Animation frame count must be between 1 and ${MAX_ANIMATION_FRAMES}.`);
+  }
+}
+
+export async function validateGifArtifact(
+  filePath: string,
+  maxBytes = MAX_GIF_BYTES
+): Promise<void> {
+  const stat = await fs.stat(filePath);
+
+  if (!stat.isFile() || stat.size < 20) {
+    throw new Error("Generated GIF artifact is missing or empty.");
+  }
+
+  if (stat.size > maxBytes) {
+    throw new Error(`Generated GIF artifact exceeds the ${maxBytes}-byte limit.`);
+  }
+
+  const header = Buffer.alloc(6);
+  const handle = await fs.open(filePath, "r");
+  try {
+    await handle.read(header, 0, header.length, 0);
+  } finally {
+    await handle.close();
+  }
+
+  const signature = header.toString("ascii");
+  if (signature !== "GIF87a" && signature !== "GIF89a") {
+    throw new Error("Generated artifact is not a valid GIF.");
+  }
+}

src/svg-renderer.ts

@@ -1,11 +1,10 @@
-import { contributionColor } from "./colors.js";
 import type { Cell, Point, SnakeState } from "./domain.js";
+import { contributionColor } from "./colors.js";
 
 export interface SvgOptions {
   readonly cellSize?: number;
   readonly gap?: number;
   readonly background?: string;
-  readonly snakeColor?: string;
 }
 
 export function renderSvg(
@@ -22,7 +21,6 @@ export function renderSvg(
   const cellSize = options.cellSize ?? 12;
   const gap = options.gap ?? 3;
   const background = options.background ?? "#0d1117";
-  const snakeColor = options.snakeColor ?? "#f0f6fc";
   const width = columns * (cellSize + gap) + gap;
   const height = rows * (cellSize + gap) + gap;
 
@@ -33,10 +31,10 @@ export function renderSvg(
   }).join("");
 
   const snakeRects = snake.segments.map((segment, index) => {
-    const x = gap + segment.x * (cellSize + gap);
-    const y = gap + segment.y * (cellSize + gap);
-    const opacity = Math.max(0.45, 1 - index * 0.035);
-    return `<rect x="${x}" y="${y}" width="${cellSize}" height="${cellSize}" rx="3" fill="${snakeColor}" opacity="${opacity.toFixed(3)}"/>`;
+    const x = gap + segment.position.x * (cellSize + gap);
+    const y = gap + segment.position.y * (cellSize + gap);
+    const opacity = Math.max(0.55, 1 - index * 0.025);
+    return `<rect x="${x}" y="${y}" width="${cellSize}" height="${cellSize}" rx="3" fill="${segment.color}" opacity="${opacity.toFixed(3)}"/>`;
   }).join("");
 
   return [

tests/quality.test.ts

@@ -0,0 +1,14 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { MAX_ANIMATION_FRAMES, validateAnimationFrameCount } from "../src/quality.js";
+
+test("accepts normal animation frame counts", () => {
+  assert.doesNotThrow(() => validateAnimationFrameCount(371));
+});
+
+test("rejects runaway animation frame counts", () => {
+  assert.throws(
+    () => validateAnimationFrameCount(MAX_ANIMATION_FRAMES + 1),
+    /frame count must be between/
+  );
+});