build(ci): add containers, contract checks, and smoke automation

Intent: make the relaunch operable by default for local work, CI, and release verification.

Goals: standardize the dev container workflow, move quality gates into automation, and make browser and container smoke checks part of delivery.

Changes: add the devcontainer and compose setup, replace legacy workflows with the new CI pipeline, wire OpenAPI and smoke verification into tooling, and document the agent-facing workflow.

Author: gildesmarais

.devcontainer/Dockerfile

@@ -0,0 +1,34 @@
+FROM ruby:4.0.1-alpine3.23
+
+SHELL ["/bin/sh", "-o", "pipefail", "-c"]
+
+RUN apk add --no-cache \
+    bash \
+    build-base \
+    curl \
+    git \
+    libxml2-dev \
+    libxslt-dev \
+    nodejs \
+    npm \
+    openssl-dev \
+    python3 \
+    tzdata
+
+ARG USER=vscode
+ARG UID=1000
+ARG GID=1000
+
+RUN addgroup -g "$GID" "$USER" \
+  && adduser -D -G "$USER" -u "$UID" "$USER"
+
+WORKDIR /workspace
+RUN chown -R "$USER":"$USER" /workspace
+
+ENV BUNDLE_PATH=/usr/local/bundle
+
+USER "$USER"
+
+EXPOSE 4000
+
+CMD ["sleep", "infinity"]

.devcontainer/README.md

@@ -0,0 +1,49 @@
+# Dev Container Workflow
+
+This repository ships a single Dev Container for development. Open the project in VS Code (Dev
+Containers extension) or GitHub Codespaces and use that environment for all work.
+
+## What gets created
+
+The devcontainer starts one service named `app` and exposes:
+
+- **Port 4000:** Ruby app
+- **Port 4001:** Astro dev server
+
+The repo is mounted at `/workspace`. Bundler gems are cached in a Docker volume to speed up
+future launches.
+
+## Bootstrap
+
+On first open, the Dev Container runs:
+
+```
+make setup
+```
+
+This installs Ruby and frontend dependencies inside the container.
+
+If setup fails due to missing network access (e.g., GitHub DNS), rerun `make setup` once
+network access is available.
+
+## Common commands (run inside the container)
+
+```
+make dev          # Ruby + Astro
+make dev-ruby     # Ruby only
+make dev-frontend # Astro only
+make test         # Ruby + frontend tests
+make ready        # RuboCop + RSpec (pre-commit gate)
+```
+
+## Lint and tests
+
+```
+bundle exec rubocop -F
+bundle exec rspec
+```
+
+## Notes
+
+- All commands are expected to run inside the Dev Container.
+- The default service command is `sleep infinity`; use the Make targets above to start servers.

.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/prettier.config.js",
+        "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": [4000, 4001],
   "portsAttributes": {
-    "3000": {
-      "label": "html2rss-web",
+    "4000": {
+      "label": "Ruby App",
       "onAutoForward": "notify"
+    },
+    "4001": {
+      "label": "Astro Dev Server",
+      "onAutoForward": "silent"
     }
   },
+  "postCreateCommand": "bash -lc \"make setup || (echo 'make setup failed; rerun once network access is available.' && exit 0)\"",
   "remoteUser": "vscode"
 }

.devcontainer/docker-compose.yml

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

.github/copilot-instructions.md

@@ -3,36 +3,57 @@
 ## Overview
 
 - Ruby web app that converts websites into RSS 2.0 feeds.
-- Built with **Roda**, using the **html2rss** gem (+ `html2rss-configs`).
-- **Principle:** _All features must work without JavaScript._ JS is only progressive enhancement.
+- Built with **Roda** backend + **Preact** frontend, using the **html2rss** gem (+ `html2rss-configs`).
+- **Frontend:** Vite-built Preact UI, served alongside Ruby backend.
+
+## Documentation website of core dependencies
+
+Search these pages before using them. Find examples, plugins, UI components, and configuration options.
+
+### Roda
+
+1. https://roda.jeremyevans.net/documentation.html
+
+### Preact & Vite
+
+1. https://preactjs.com/guide/v10/getting-started/
+2. https://vite.dev/guide/
+
+### html2rss
+
+1. If available, find source locally in: `../html2rss`.
+2. source code on github: https://github.com/html2rss/html2rss
+
+### Test and Linters
+
+1. https://docs.rubocop.org/rubocop/cops.html
+2. https://docs.rubocop.org/rubocop-rspec/cops_rspec.html
+3. https://rspec.info/features/3-13/rspec-expectations/built-in-matchers/
+4. https://www.betterspecs.org/
+
+Fix rubocop `RSpec/MultipleExpectations` adding rspec tag `:aggregate_failures`.
 
 ## Core Rules
 
-- ✅ Use **Roda routing with `hash_branch`**. Keep routes small.
-- ✅ Put logic into `helpers/` or `app/`, not inline in routes.
+- ✅ Organise Roda routes via dedicated modules (e.g. `Html2rss::Web::Routes::*`), keeping the main app class thin.
+- ✅ Keep helper modules minimal: define entrypoints with `class << self` and push implementation helpers under `private`; avoid `module_function` unless mirroring existing conventions.
 - ✅ 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.
-
-## Don’t
+- ✅ **Frontend**: Use Preact components in `frontend/src/`. Keep it simple.
+- ✅ **CSS**: Use the app-owned frontend styles in `frontend/src/styles/`.
+- ✅ **Specs**: RSpec for Ruby, build tests for frontend.
+- ✅ When a spec needs to tweak environment variables, wrap the example in `ClimateControl.modify` so state is restored automatically.
 
-- ❌ 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
 
-## 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
-- `public/` – static assets (CSS/JS, minimal)
-- `config/feeds.yml` – feed definitions
-- `spec/` – RSpec tests + VCR cassettes
+- ❌ Don't use Ruby's URI class or addressable gem directly. Strictly use `Html2rss::Url` only.
+- ❌ 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 reach into private API with `send(...)`; expose what you need at the module level instead.
+- ❌ Don't modify `frontend/dist/` - it's generated by build process.
+- ❌ NEVER expose the auth token a user provides.
 
 ## Environment
 
@@ -41,6 +62,12 @@
 - `HEALTH_CHECK_USERNAME`, `HEALTH_CHECK_PASSWORD`
 - `SENTRY_DSN` (optional)
 
+### Verification Steps
+
+- Run `ruby -c app.rb` to check syntax
+- Run `bundle exec rspec` to verify tests
+- Check `bundle install` removes unused dependencies
+
 ## Style
 
 - Add `# frozen_string_literal: true`