feat: astro frontend

Author: gildesmarais

.devcontainer/Dockerfile

@@ -0,0 +1,38 @@
+FROM mcr.microsoft.com/devcontainers/ruby:3.4-bullseye
+
+# Install Node.js 20
+RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+  && apt-get install -y nodejs
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+  build-essential \
+  git \
+  curl \
+  && rm -rf /var/lib/apt/lists/*
+
+# Install development gems
+RUN gem install rubocop
+
+# Install global npm packages
+RUN npm install -g prettier
+
+# Create vscode user
+RUN groupadd --gid 1000 vscode \
+  && useradd --uid 1000 --gid vscode --shell /bin/bash --create-home vscode
+
+# Set up workspace
+WORKDIR /workspace
+RUN chown -R vscode:vscode /workspace
+
+# Switch to vscode user
+USER vscode
+
+# Set up environment
+RUN echo 'export BUNDLE_PATH="/usr/local/bundle"' >> ~/.bashrc
+
+# Expose port
+EXPOSE 3000
+
+# Keep container running
+CMD ["sleep", "infinity"]

.devcontainer/devcontainer.json

@@ -1,41 +1,43 @@
 {
   "name": "html2rss-web",
-  "image": "mcr.microsoft.com/devcontainers/ruby:3.4",
-  "features": {
-    "ghcr.io/devcontainers/features/git:1": {},
-    "ghcr.io/devcontainers/features/github-cli:1": {}
-  },
+  "dockerComposeFile": "docker-compose.yml",
+  "service": "app",
+  "workspaceFolder": "/workspace",
+  "shutdownAction": "stopCompose",
   "customizations": {
     "vscode": {
       "extensions": [
-        "redhat.vscode-yaml",
-        "esbenp.prettier-vscode",
-        "github.copilot",
-        "github.copilot-chat",
-        "shopify.ruby-lsp"
+        "rebornix.ruby",
+        "astro-build.astro-vscode",
+        "esbenp.prettier-vscode"
       ],
       "settings": {
-        "ruby.rubocop.executePath": "bundle exec",
-        "ruby.format": "rubocop",
-        "ruby.lint": {
-          "rubocop": true
-        },
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "esbenp.prettier-vscode",
         "files.associations": {
-          "*.erb": "erb"
-        }
+          "*.astro": "astro"
+        },
+        "prettier.configPath": "./frontend/.prettierrc",
+        "ruby.format": "rubocop",
+        "ruby.lint": { "rubocop": true },
+        "editor.tabSize": 2,
+        "editor.insertSpaces": true,
+        "files.trimTrailingWhitespace": true,
+        "files.insertFinalNewline": true
       }
     }
   },
-  "postCreateCommand": "make setup",
-  "postStartCommand": "echo '🚀 html2rss-web Development Environment Ready!' && echo '' && echo '📋 Quick Start Commands:' && echo '  make dev         # Start development server' && echo '  make test        # Run tests' && echo '  make lint        # Run linter' && echo '  make fix         # Auto-fix linting issues' && echo '  make help        # Show all commands' && echo '' && echo '🌐 Server will be available at: http://localhost:3000' && echo '📁 Project files are in: /workspaces/html2rss-web' && echo '' && echo '💡 Tip: Use Ctrl+C to stop the development server' && echo ''",
-  "forwardPorts": [
-    3000
-  ],
+  "forwardPorts": [3000, 4321],
   "portsAttributes": {
     "3000": {
-      "label": "html2rss-web",
+      "label": "Ruby App",
       "onAutoForward": "notify"
+    },
+    "4321": {
+      "label": "Astro Dev Server",
+      "onAutoForward": "silent"
     }
   },
+  "postCreateCommand": "make setup",
   "remoteUser": "vscode"
 }

.devcontainer/docker-compose.yml

@@ -0,0 +1,21 @@
+version: '3.8'
+
+services:
+  app:
+    build:
+      context: ..
+      dockerfile: .devcontainer/Dockerfile
+    volumes:
+      - ../:/workspace:cached
+      - bundle-cache:/usr/local/bundle
+    ports:
+      - "3000:3000"
+    environment:
+      - RACK_ENV=development
+      - BUNDLE_PATH=/usr/local/bundle
+    command: sleep infinity
+    user: vscode
+    working_dir: /workspace
+
+volumes:
+  bundle-cache:

.devcontainer/scripts/setup.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+set -e
+
+echo "Setting up html2rss-web development environment..."
+
+# Install dependencies
+bundle install
+cd frontend && npm install && cd ..
+
+# Create .env if missing
+if [ ! -f .env ]; then
+  cat >.env <<EOF
+RACK_ENV=development
+HEALTH_CHECK_USERNAME=dev
+HEALTH_CHECK_PASSWORD=dev
+AUTO_SOURCE_ENABLED=true
+AUTO_SOURCE_USERNAME=dev
+AUTO_SOURCE_PASSWORD=dev
+AUTO_SOURCE_ALLOWED_ORIGINS=localhost:3000
+EOF
+fi
+
+# Create directories
+mkdir -p tmp/rack-cache-body tmp/rack-cache-meta
+
+# Build frontend
+cd frontend && npm run build && cd ..
+
+echo "Setup complete! Run 'make dev' to start the server."

.github/copilot-instructions.md

@@ -3,8 +3,9 @@
 ## Overview
 
 - Ruby web app that converts websites into RSS 2.0 feeds.
-- Built with **Roda**, using the **html2rss** gem (+ `html2rss-configs`).
+- Built with **Roda** backend + **Astro** frontend, using the **html2rss** gem (+ `html2rss-configs`).
 - **Principle:** _All features must work without JavaScript._ JS is only progressive enhancement.
+- **Frontend:** Modern Astro-based UI with component architecture, served alongside Ruby backend.
 
 ## Core Rules
 
@@ -13,24 +14,33 @@
 - ✅ Validate all inputs. Pass outbound requests through **SSRF filter**.
 - ✅ Add caching headers where appropriate (`Rack::Cache`).
 - ✅ Errors: friendly messages for users, detailed logging internally.
-- ✅ CSS: Water.css + small overrides in `public/styles.css`.
-- ✅ Specs: RSpec, unit + integration, use VCR for external requests.
+- ✅ **Frontend**: Use Astro components in `frontend/src/`. Keep it simple.
+- ✅ **CSS**: Use frontend styles in `frontend/public/styles.css`. Water.css for fallback.
+- ✅ **Specs**: RSpec for Ruby, build tests for frontend.
 
-## Don’t
+## Don't
 
-- ❌ Don’t depend on JS for core flows.
-- ❌ Don’t bypass SSRF filter or weaken CSP.
-- ❌ Don’t add databases, ORMs, or background jobs.
-- ❌ Don’t leak stack traces or secrets in responses.
+- ❌ Don't depend on JS for core flows.
+- ❌ Don't bypass SSRF filter or weaken CSP.
+- ❌ Don't add databases, ORMs, or background jobs.
+- ❌ Don't leak stack traces or secrets in responses.
+- ❌ Don't add complex frontend frameworks (React, Vue, etc.). Keep Astro simple.
+- ❌ Don't modify `frontend/dist/` - it's generated by build process.
 
 ## Project Structure
 
 - `app.rb` – main Roda app
 - `app/` – core modules (config, cache, ssrf, health)
 - `routes/` – route handlers (`hash_branch`)
 - `helpers/` – pure helper modules (`module_function`)
-- `views/` – ERB templates
+- `views/` – ERB templates (fallback)
 - `public/` – static assets (CSS/JS, minimal)
+- `frontend/` – Astro frontend application
+  - `src/pages/` – Astro pages (index.astro, gallery.astro)
+  - `src/layouts/` – Astro layouts (Layout.astro)
+  - `public/` – frontend static assets
+  - `package.json` – Node.js dependencies
+  - `astro.config.mjs` – Astro configuration
 - `config/feeds.yml` – feed definitions
 - `spec/` – RSpec tests + VCR cassettes
 

.github/workflows/bundle-update.yml

@@ -0,0 +1,74 @@
+name: Frontend CI
+
+on:
+  push:
+    paths:
+      - "frontend/**"
+  pull_request:
+    paths:
+      - "frontend/**"
+
+jobs:
+  frontend-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: |
+          cd frontend
+          npm ci
+
+      - name: Check code formatting
+        run: |
+          cd frontend
+          npm run format:check
+
+      - name: Build frontend
+        run: |
+          cd frontend
+          npm run build
+
+      - name: Verify build output
+        run: |
+          ls -la frontend/dist/
+          test -f frontend/dist/index.html
+          test -f frontend/dist/gallery/index.html
+          test -f frontend/dist/styles.css
+
+  frontend-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: |
+          cd frontend
+          npm ci
+
+      - name: Check for vulnerabilities
+        run: |
+          cd frontend
+          npm audit --audit-level=moderate
+
+      - name: Build and verify
+        run: |
+          cd frontend
+          npm run build
+          # Verify the built HTML is valid
+          grep -q "html2rss-web" dist/index.html
+          grep -q "Feed Gallery" dist/gallery/index.html

.github/workflows/frontend.yml

@@ -21,6 +21,34 @@ jobs:
       - run: bundle exec rubocop -F
       - run: bundle exec yard doc --fail-on-warning --no-output
 
+  frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install frontend dependencies
+        run: |
+          cd frontend
+          npm ci
+
+      - name: Build frontend
+        run: |
+          cd frontend
+          npm run build
+
+      - name: Verify build output
+        run: |
+          ls -la frontend/dist/
+          test -f frontend/dist/index.html
+          test -f frontend/dist/gallery/index.html
+
   rspec:
     runs-on: ubuntu-latest
     steps:
@@ -33,13 +61,27 @@ jobs:
       - run: bundle exec rspec
 
   docker-test:
-    needs: hadolint
+    needs: [hadolint, frontend]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
       - uses: ruby/setup-ruby@v1
         with:
           bundler-cache: true
+      - name: Setup Node.js for Docker build
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+      - name: Install frontend dependencies
+        run: |
+          cd frontend
+          npm ci
+      - name: Build frontend
+        run: |
+          cd frontend
+          npm run build
       - run: |
           bundle exec rake
 
@@ -49,6 +91,7 @@ jobs:
       - docker-test
       - hadolint
       - ruby
+      - frontend
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -60,6 +103,23 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v5
 
+      - name: Setup Node.js for Docker build
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install frontend dependencies
+        run: |
+          cd frontend
+          npm ci
+
+      - name: Build frontend
+        run: |
+          cd frontend
+          npm run build
+
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3