Merge remote-tracking branch 'origin/main' into feature/copy-only-color-swatches-perf-docs

# Conflicts:
#	.gitea/workflows/ci.yml
#	.gitleaks.toml

.gitea/workflows/ci.yml

@@ -1,4 +1,5 @@
 ---
+# ci-sync: 2026-05-30T01:30:45Z
 # Homelab CI — Node/pages lane (git-ci-01) + secret scan (git-ci-02)
 name: CI
 
@@ -36,29 +37,12 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Node / static site CI
+      - name: npm ci
         run: |
-          set -e
-          if [ ! -f package.json ]; then
-            echo "No package.json — static/HTML repo; skip npm build pipeline"
-            if ls ./*.html >/dev/null 2>&1 || [ -f index.html ]; then
-              echo "Found HTML entrypoint(s) — OK for static site"
-            else
-              echo "No HTML files at repo root (advisory only)"
-            fi
-            exit 0
-          fi
-
-          if [ -f package-lock.json ]; then
-            if ! npm ci; then
-              echo "npm ci failed (lock file out of sync?) — falling back to npm install"
-              rm -rf node_modules
-              npm install
-            fi
-          else
-            npm install
-          fi
+          if [ -f package-lock.json ]; then npm ci; elif [ -f package.json ]; then npm install; else exit 0; fi
 
+      - name: Playwright browsers
+        run: |
           if [ -f playwright.config.ts ] || [ -f playwright.config.js ] || [ -f playwright.config.mjs ] \
              || grep -q '@playwright/test' package.json 2>/dev/null; then
             npx playwright install --with-deps chromium
@@ -66,21 +50,30 @@ jobs:
             echo "No Playwright — skip browser install"
           fi
 
-          npm run lint --if-present || echo "Lint failed (advisory — fix in follow-up)"
-          npm test --if-present || echo "Tests failed (advisory — fix in follow-up)"
+      - name: Lint
+        run: npm run lint --if-present
 
-          export CI=true
-          export NEXTAUTH_SECRET="${NEXTAUTH_SECRET:-ci-build-placeholder-not-for-production}"
-          export AUTH_SECRET="${AUTH_SECRET:-$NEXTAUTH_SECRET}"
-          export NEXTAUTH_URL="${NEXTAUTH_URL:-http://localhost:3000}"
-          export DATABASE_URL="${DATABASE_URL:-postgresql://ci:ci@127.0.0.1:5432/ci?schema=public}"
-          npm run build --if-present
-          npm audit --audit-level=high || true
+      - name: Test
+        run: npm test --if-present
+
+      - name: Build
         env:
           NEXTAUTH_SECRET: ${{ secrets.NEXTAUTH_SECRET }}
           NEXTAUTH_URL: ${{ secrets.NEXTAUTH_URL }}
           AUTH_SECRET: ${{ secrets.AUTH_SECRET }}
           DATABASE_URL: ${{ secrets.DATABASE_URL }}
+        run: |
+          export CI=true
+          # Placeholders so Next.js/NextAuth can compile in CI without real secrets.
+          # Override via Gitea repo Actions secrets when you need production-like builds.
+          export NEXTAUTH_SECRET="${NEXTAUTH_SECRET:-ci-build-placeholder-not-for-production}"
+          export AUTH_SECRET="${AUTH_SECRET:-$NEXTAUTH_SECRET}"
+          export NEXTAUTH_URL="${NEXTAUTH_URL:-http://localhost:3000}"
+          export DATABASE_URL="${DATABASE_URL:-postgresql://ci:ci@127.0.0.1:5432/ci?schema=public}"
+          npm run build --if-present
+
+      - name: npm audit (advisory)
+        run: npm audit --audit-level=high || true
 
   secret-scan:
     needs: skip-ci-check
@@ -92,9 +85,5 @@ jobs:
           fetch-depth: 0
       - name: Gitleaks
         run: |
-          extra=""
-          if [ -f .gitleaks.toml ]; then
-            extra="--config /repo/.gitleaks.toml"
-          fi
           docker run --rm -v "$PWD:/repo" ghcr.io/gitleaks/gitleaks:latest \
-            detect --source /repo --no-banner --redact ${extra}
+            detect --source /repo --no-banner --redact

.gitleaks.toml

@@ -2,7 +2,9 @@
 #
 # IMPORTANT: `useDefault = true` is required — without it gitleaks loads ONLY
 # this file (title + allowlist) with ZERO detection rules, so it would never
-# flag a real secret.
+# flag a real secret. Fixed 2026-07 (security-hardening track); if you're
+# re-pushing this template to a repo that already had the old version, that
+# repo's secret scanning was a no-op until this lands.
 title = "homelab gitea bootstrap"
 
 [extend]

scripts/git-hooks/install.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# One-time installer for the local pre-commit gitleaks hook.
+# Run once per clone: bash scripts/git-hooks/install.sh
+#
+# Respects `core.hooksPath` if you've set one (local or global) — some setups
+# point git at a hooks dir outside `.git/hooks/` (e.g. a machine-wide
+# `~/.git-hooks/`), and installing to `.git/hooks/` in that case would be a
+# silent no-op. If an existing hook is already at that path, this chains to
+# it so nothing already relying on it breaks.
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd "$REPO_ROOT"
+
+HOOKS_DIR="$(git config --get core.hooksPath || true)"
+if [ -z "$HOOKS_DIR" ]; then
+  HOOKS_DIR=".git/hooks"
+elif [[ "$HOOKS_DIR" != /* ]]; then
+  HOOKS_DIR="$REPO_ROOT/$HOOKS_DIR"
+fi
+mkdir -p "$HOOKS_DIR"
+
+TARGET="$HOOKS_DIR/pre-commit"
+if [ -f "$TARGET" ] && ! grep -q "gitleaks" "$TARGET" 2>/dev/null; then
+  echo "⚠️  Existing pre-commit hook found at $TARGET that isn't ours — chaining instead of overwriting."
+  CHAINED="$HOOKS_DIR/pre-commit.d-gitleaks"
+  cp scripts/git-hooks/pre-commit "$CHAINED"
+  chmod +x "$CHAINED"
+  if ! grep -q "pre-commit.d-gitleaks" "$TARGET" 2>/dev/null; then
+    printf '\n# Added by levkinops ansible repo (scripts/git-hooks/install.sh)\n"%s"\n' "$CHAINED" >> "$TARGET"
+  fi
+else
+  cp scripts/git-hooks/pre-commit "$TARGET"
+  chmod +x "$TARGET"
+fi
+
+echo "✓ Installed pre-commit gitleaks hook → $TARGET"
+if [ "$HOOKS_DIR" != ".git/hooks" ] && [ "$HOOKS_DIR" != "$REPO_ROOT/.git/hooks" ]; then
+  echo "  (using core.hooksPath=$HOOKS_DIR — applies to every repo that shares this hooksPath)"
+fi
+if ! command -v gitleaks >/dev/null 2>&1; then
+  echo "  Note: gitleaks isn't installed locally yet. Install it for the hook to actually run:"
+  echo "    macOS:  brew install gitleaks"
+  echo "    Linux:  see https://github.com/gitleaks/gitleaks#installing"
+  echo "  Until then this hook is a no-op locally (CI still scans every push)."
+fi

scripts/git-hooks/pre-commit

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Local pre-commit secret scan — mirrors the `secret-scanning` CI job (gitleaks)
+# so leaked secrets are caught before they ever leave your machine, not just at
+# CI time. Installed via `make install-git-hooks`.
+#
+# Uses the same .gitleaks.toml allowlist as CI. Only scans staged content.
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd "$REPO_ROOT"
+
+if ! command -v gitleaks >/dev/null 2>&1; then
+  echo "⚠️  gitleaks not installed locally — skipping local secret scan."
+  echo "    Install: brew install gitleaks   (CI will still catch it either way)"
+  exit 0
+fi
+
+echo "🔐 Running gitleaks on staged changes..."
+if ! gitleaks protect --staged --config .gitleaks.toml --no-banner --redact; then
+  echo ""
+  echo "❌ gitleaks found a potential secret in your staged changes."
+  echo "   Fix it, or if it's a false positive, add an allowlist entry to .gitleaks.toml."
+  echo "   Bypass (not recommended): git commit --no-verify"
+  exit 1
+fi
+
+echo "✓ gitleaks: no secrets found in staged changes"