Merge pull request #327 from FirefoxCSS-Store/improve-automation

Improve automation

Author: Neikon

.devcontainer/devcontainer.json

@@ -0,0 +1,25 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/javascript-node
+{
+	"name": "Node.js",
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	"image": "mcr.microsoft.com/devcontainers/javascript-node:4-24-trixie",
+	"features": {
+		"ghcr.io/devcontainers-extra/features/npm-package:1": {}
+	},
+
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	"postCreateCommand": "bash .devcontainer/post-create.sh",
+
+	// Configure tool-specific properties.
+	// "customizations": {},
+
+	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "root"
+}

.devcontainer/post-create.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if ! command -v jq >/dev/null 2>&1; then
+	sudo apt-get update
+	sudo apt-get install -y jq
+fi
+
+if ! command -v nu >/dev/null 2>&1; then
+	npm install -g nushell
+fi
+
+npm ci

.github/dependabot.yml

@@ -0,0 +1,12 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for more information:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+# https://containers.dev/guide/dependabot
+
+version: 2
+updates:
+ - package-ecosystem: "devcontainers"
+   directory: "/"
+   schedule:
+     interval: weekly

.github/workflows/build.yml

@@ -1,29 +1,57 @@
-name: Build
+name: Build And Publish Docs
 
 on:
-  workflow_dispatch
+  push:
+    branches:
+      - main
+    paths:
+      - 'dev/**'
+      - 'images/**'
+      - 'themes.json'
+      - 'gulpfile.js'
+      - 'gulpconfig.js'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'dev/config/**'
+  workflow_dispatch:
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+permissions:
+  contents: write
+
+concurrency:
+  group: build-and-publish-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v6
         with:
-          persist-credentials: false
           fetch-depth: 0
-      - uses: actions/setup-node@v1
+
+      - uses: actions/setup-node@v6
         with:
-          node-version: 14
-      - run: npm i
+          node-version: 24
+          cache: npm
+
+      - run: npm ci
+      - run: npm test
       - run: npm run build
-      - name: Commit files
+
+      - name: Commit generated docs
+        shell: bash
         run: |
+          if git diff --quiet -- docs; then
+            echo "No generated docs changes to commit."
+            exit 0
+          fi
+
           git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git config --local user.name "github-actions[bot]"
-          git add .
-          git commit -m "ci(build): compile and deploy" -a
-      - name: Push changes
-        uses: ad-m/github-push-action@master
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          branch: ${{ github.ref }}
+          git add docs
+          git commit -m "ci(build): compile and deploy"
+          git push

.github/workflows/check-themes.yml

@@ -1,18 +1,33 @@
-name: Check themes.json
+name: Validate Site
 
 on:
   pull_request:
     branches: [ main ]
     paths:
+      - 'dev/**'
+      - 'images/**'
       - 'themes.json'
+      - 'gulpfile.js'
+      - 'gulpconfig.js'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'dev/config/**'
+      - '.github/workflows/**'
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
 
 jobs:
-  test_pull_requests:
+  validate_pull_requests:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v1
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
         with:
-          node-version: 14
-      - run: npm i
+          node-version: 24
+          cache: npm
+
+      - run: npm ci
       - run: npm test
+      - run: npm run build

.gitignore

@@ -42,6 +42,9 @@ Icon?
 # JetBrains IDEs
 .idea/
 
+# Codex local workspace data
+.codex
+
 # Build output
 /dist/
 /build/
@@ -60,4 +63,3 @@ coverage/
 # Misc
 *.sublime-workspace
 *.sublime-project
-

AGENTS.md

@@ -0,0 +1,21 @@
+# AGENTS
+
+This repository uses this file as the entry point for future coding agents.
+
+Before starting work:
+
+1. Read [MEMORY.md](./MEMORY.md).
+2. Use that file as persistent project context across conversations.
+3. Keep `MEMORY.md` updated manually after any relevant change, decision, blocker, or workflow update.
+
+Operational notes:
+
+- Prefer minimal, reversible changes.
+- Validate with `npm test` for `themes.json` checks.
+- Use `npm run build` when touching generated site assets or source files under `dev/`.
+- When automation changes are introduced, document the intent and impact in `MEMORY.md`.
+- Use English for repository-facing output by default, including code, comments, commit messages, pull request text, documentation, workflow messages, and user-facing project strings unless the repository already requires another language in a specific place.
+- In chat, always reply in the same language used by the user.
+- After implementing relevant changes or new functionality, create a commit and push it so work remains traceable and easy to roll back if needed.
+- Never perform a merge without explicit user authorization.
+- Never take actions that could affect the repository's production main branch without explicit user authorization.

MEMORY.md

@@ -0,0 +1,77 @@
+# Persistent Memory
+
+This file stores durable project context so future conversations can resume work with less re-discovery.
+
+## Project Summary
+
+- Repository: `FirefoxCSS-Store.github.io`
+- Purpose: static site that catalogs Firefox `userChrome.css` themes
+- Main data source: `themes.json`
+- Site source: `dev/`
+- Generated site output: `docs/`
+
+## Tooling And Validation
+
+- Package manager: `npm`
+- Build command: `npm run build`
+- Test command: `npm test`
+- Build system: `gulp`
+- Theme validation script: `tests/themes.check.js`
+- Theme metadata refresh script: `scripts/sort_themes.nu`
+- Dev container config: `.devcontainer/devcontainer.json`
+- Devcontainer bootstrap script: `.devcontainer/post-create.sh`
+- Devcontainer automation now runs `.devcontainer/post-create.sh` from `postCreateCommand` to ensure `jq`, `nu`, and project dependencies are installed after container creation/rebuild
+- The build toolchain now runs cleanly on Node 24 with `gulp@5`, `gulp-sass@6`, `gulp-terser`, and a custom `sharp`-based WebP conversion step
+- `npm audit` is currently clean after adding targeted `overrides` for `markdown-it` and `@parcel/watcher` transitive dependencies
+
+## Automation Context
+
+- Active working branch created for automation improvements: `improve-automation`
+- Existing GitHub Actions:
+- `.github/workflows/build.yml`
+- `.github/workflows/check-themes.yml`
+- CI now uses current `actions/checkout@v4` and `actions/setup-node@v4` on Node 24
+- CI workflows now opt into Node 24 for JavaScript actions explicitly and use `actions/checkout@v6` plus `actions/setup-node@v6`
+- Build workflow now runs automatically on pushes to `main` that affect site/build inputs and commits regenerated `docs/` output back to the branch
+- PR validation now runs `npm test` and `npm run build` for site-related changes instead of only checking `themes.json`
+- The build workflow syntax also requires `workflow_dispatch:` with a trailing colon; missing it makes GitHub mark the workflow file as invalid even if other checks still pass
+
+## Repo Notes
+
+- Local `.codex` file is ignored in `.gitignore`
+- Build workflow currently commits generated files back to the branch after `npm run build`
+- Pull requests touching `themes.json` trigger validation via `npm test`
+- Site pages are generated from Pug in `dev/pug/`
+- Client behavior is implemented in `dev/js/main.js`
+- Styles are authored in SCSS under `dev/scss/`
+- Published site assets live in committed `docs/`
+- Local containerized development is configured to install Node, npm, `jq`, and Nushell
+- The devcontainer also runs `npm ci` automatically, so rebuilds recreate `node_modules` without manual setup
+- `gulpfile.js` now lazy-loads ESM-only Gulp plugins and skips optional directories like `dev/fonts/` when they are absent
+- Hidden config generation now filters non-`.txt` files explicitly so builds do not create stray files like `docs/.robots`
+- Theme entries that depended on fragile remote screenshots have been localized into `images/themes/remote-*` and now build into committed assets under `docs/assets/img/themes/`
+- Binary copies for static images now use `fs.promises.copyFile` instead of `gulp.src().pipe(dest())` because the stream path was corrupting some `.webp` assets in `docs/`
+- Project-facing text should be written in English by default; chat replies should mirror the user's language
+
+## Architecture Snapshot
+
+- `themes.json` is the single catalog source used by the client and copied to `docs/themes.json` during build
+- The frontend is a mostly static site with a small client-side app that fetches `themes.json`, sorts, filters, and renders cards in the browser
+- Gulp handles Pug compilation, SCSS compilation, Babel transpilation, JS minification with Terser, image conversion/copy with Sharp, and config file copying
+- Images from `images/` are emitted to `docs/assets/img/`; many local screenshots are converted to WebP
+- `scripts/sort_themes.nu` enriches theme entries with `pushed_at`, `stargazers_count`, and `avatar` using GitHub/GitLab/Codeberg APIs or git cloning fallback
+
+## Known Technical Risks
+
+- Theme rendering is intentionally throttled with `444ms` per card, which scales poorly for a catalog of 100+ entries
+- Search/filter logic depends on client-side fetch and has no visible loading or error handling
+- Test coverage is narrow: `tests/themes.check.js` validates only basic key order/types and not richer schema or link/image integrity
+
+## Working Agreement For Future Sessions
+
+- Read this file before making assumptions about project state
+- Update this file manually when there are relevant decisions, branch changes, automation updates, or persistent blockers
+- Keep entries concise and durable; avoid transient noise
+- Future agents should create a commit and push after implementing relevant changes or new functionality so work stays traceable and reversible
+- Future agents must not merge without explicit user authorization
+- Future agents must not take actions that could affect the production main branch without explicit user authorization

dev/config/robots.txt

@@ -1,2 +1,2 @@
 User-agent: *
-Disallow: /
+Allow: /

dev/js/main.js

@@ -53,10 +53,19 @@ class Card {
 }
 
 
-const removeLightbox = () => document.body.getElementsById('lightbox').remove()
+function removeLightbox () {
+
+  const lightbox = document.getElementById('lightbox')
+
+  if (lightbox)
+    lightbox.remove()
+
+}
 
 function createLightbox (id) {
 
+  removeLightbox()
+
   const card = document.getElementById(`theme-${id}`)
   const themeTitle = card.querySelector('h3')
   const img = card.querySelector('img')
@@ -65,7 +74,7 @@ function createLightbox (id) {
   <div id="lightbox" onclick="this.remove()">
     <h2>${themeTitle.innerText}</h2>
     <img src="${img.src}">
-    <button type="button" class="btn btn-close-lightbox" onClick="removeLightbox"><i class="fas fa-times-circle"></i> Close</button>
+    <button type="button" class="btn btn-close-lightbox" onClick="removeLightbox()"><i class="fas fa-times-circle"></i> Close</button>
   </div>
   `