feat: stabilize public http interface & slimmer docker (#882)

This pull request restructures how the frontend assets and OpenAPI
specification are built, served, and referenced throughout the
application. The changes standardize the output locations, improve
Docker and CI integration, and update documentation and code references
to reflect these new conventions. The most important changes are grouped
below.

**Frontend build and serving changes:**

- The frontend build output is now placed in `frontend/dist` instead of
`public/frontend`, and the app serves static assets from this new
directory at the root path (`/`). This affects the Docker build, static
file serving configuration, and bookmarklet logic.
(`[[1]](diffhunk://#diff-dd2c0eb6ea5cfc6c4bd4eac30934e2d5746747af48fef6da689e85b752f39557L96-R96)`,
`[[2]](diffhunk://#diff-f965f92b425fb2f75d38b491b2625fe21b8af20b7666217546bce8a42b198ea4R34-R35)`,
`[[3]](diffhunk://#diff-f965f92b425fb2f75d38b491b2625fe21b8af20b7666217546bce8a42b198ea4R85-R88)`,
`[[4]](diffhunk://#diff-f965f92b425fb2f75d38b491b2625fe21b8af20b7666217546bce8a42b198ea4L103-R110)`,
`[[5]](diffhunk://#diff-97c6e2c429ec483132c584137a18a1ade2ff6c3f4f6485f4a83db604d0323d7cR5)`,
`[[6]](diffhunk://#diff-97c6e2c429ec483132c584137a18a1ade2ff6c3f4f6485f4a83db604d0323d7cL22-R23)`,
`[[7]](diffhunk://#diff-7252f6c43b3cf192bd50ce66192ddce81eca27815a4b99eb57366d25e3715f07L9-R9)`,
`[[8]](diffhunk://#diff-1f633b86af4bf00bbb33177b2e1a51a960711d1bb9901ce853b34e53d6bd7d14L275-R281)`,
`[[9]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L104-R104)`,
`[[10]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L23-R23)`,
`README.md`, `docs/README.md`)

**OpenAPI specification changes:**

- The OpenAPI YAML file is now generated to and served from
`public/openapi.yaml` instead of `docs/api/v1/openapi.yaml`. All
references, build scripts, and tests have been updated accordingly. The
versioned API route `/api/v1/openapi.yaml` now redirects to
`/openapi.yaml`.
(`[[1]](diffhunk://#diff-76ed074a9305c04054cdebb9e9aad2d818052b07091de1f20cad0bbac34ffb52L105-R124)`,
`[[2]](diffhunk://#diff-ee98e028c59b193d58fde56ab4daf54d43c486ae674e63d50ddf300b07943e0fL99-R106)`,
`[[3]](diffhunk://#diff-74d6d27981dace9acd4886bdcdc2fb9776477f7b22557e92832eb4cf46fb98cdL18-R18)`,
`[[4]](diffhunk://#diff-28a08a74a84f026c2e107160e332d32db8c8338eaf53cf6c7930f6ff00afe952L26-R26)`,
`[[5]](diffhunk://#diff-28a08a74a84f026c2e107160e332d32db8c8338eaf53cf6c7930f6ff00afe952L58-L80)`,
`[[6]](diffhunk://#diff-da6498268e99511d9ba0df3c13e439d10556a812881c9d03955b2ef7c6c1c655L14-R15)`,
`[[7]](diffhunk://#diff-0f9368690552ac79a208dde6e3f09cf9f4e350e910d0de10c35dc2cc235479b1L85-R85)`,
`[[8]](diffhunk://#diff-1f633b86af4bf00bbb33177b2e1a51a960711d1bb9901ce853b34e53d6bd7d14L56-R56)`,
`[[9]](diffhunk://#diff-347625202f0133fd177c976e7499085afcda2d709947a82294435a16276bd228L12-R12)`,
`[[10]](diffhunk://#diff-7725db5f3a9f3b853587e27b2462cf1b84ead50477855af692f72bb6e159cca5L452-L466)`,
`[[11]](diffhunk://#diff-39eaafdff54bffed770574d0dd758902acc94553d5bb2fb5eab86903fc2efff5L117-R117)`,
`[[12]](diffhunk://#diff-39eaafdff54bffed770574d0dd758902acc94553d5bb2fb5eab86903fc2efff5L142-R147)`,
`[[13]](diffhunk://#diff-0b5ca119d2be595aa307d34512d9679e49186307ef94201e4b3dfa079aa89938L7-R12)`,
`[[14]](diffhunk://#diff-0b5ca119d2be595aa307d34512d9679e49186307ef94201e4b3dfa079aa89938L58-R58)`,
`README.md`, `docs/README.md`)

**Continuous Integration and Docker improvements:**

- The CI workflow now installs frontend dependencies and verifies both
the OpenAPI spec and client generation in a single step using `make
openapi-verify`. Node dependencies are cached for faster builds, and the
Docker build uses the new frontend output path.
(`[[1]](diffhunk://#diff-b803fcb7f17ed9235f1e5cb1fcd2f5d3b2838429d4368ae4c57ce4436577f03fR61-R69)`,
`[[2]](diffhunk://#diff-b803fcb7f17ed9235f1e5cb1fcd2f5d3b2838429d4368ae4c57ce4436577f03fL86-L88)`,
`[[3]](diffhunk://#diff-dd2c0eb6ea5cfc6c4bd4eac30934e2d5746747af48fef6da689e85b752f39557L96-R96)`,
`.dockerignore`)

**Documentation and tests:**

- All documentation, helper text, and tests have been updated to match
the new asset and OpenAPI spec locations, ensuring consistency and
preventing confusion for contributors. (`README.md`, `docs/README.md`,
`frontend/package.json`, `frontend/src/__tests__`,
`spec/html2rss/web/api/v1_spec.rb`)

**Miscellaneous:**

- The frontend favicon is now referenced as `/favicon.ico` instead of an
inline SVG.
(`[frontend/index.htmlL11-R11](diffhunk://#diff-959f9cada636604db33bc1ba82fed347457dcb032c37ac195b4343c5f0ea6e72L11-R11)`)

Author: gildesmarais

.dockerignore

@@ -20,3 +20,4 @@ renovate.json
 spec/
 tmp/
 work/
+frontend/dist/

.github/workflows/ci.yml

@@ -58,9 +58,15 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version-file: ".tool-versions"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install frontend dependencies for OpenAPI client verification
+        run: npm ci
+        working-directory: frontend
 
-      - name: Verify generated OpenAPI is up to date
-        run: bundle exec rake openapi:verify
+      - name: Verify generated OpenAPI spec and client are up to date
+        run: make openapi-verify
 
       - name: Lint OpenAPI contract
         run: make openapi-lint
@@ -83,9 +89,6 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Verify generated OpenAPI client is up to date
-        run: npm run openapi:verify
-
       - name: Typecheck frontend
         run: npm run typecheck
 

.gitignore

@@ -39,7 +39,6 @@
 # Ignore frontend build output and tooling caches
 /frontend/dist/
 /frontend/node_modules/
-/public/frontend
 /frontend/playwright-report/
 /frontend/test-results/
 

Dockerfile

@@ -93,6 +93,6 @@ COPY --chown=$USER:$USER Gemfile Gemfile.lock app.rb config.ru ./
 COPY --chown=$USER:$USER app ./app
 COPY --chown=$USER:$USER config ./config
 COPY --chown=$USER:$USER public ./public
-COPY --from=frontend-builder --chown=$USER:$USER /app/public/frontend ./public/frontend
+COPY --from=frontend-builder --chown=$USER:$USER /app/frontend/dist ./frontend/dist
 
 CMD ["bundle", "exec", "puma", "-C", "./config/puma.rb"]

Makefile

@@ -102,26 +102,26 @@ ready: ## Pre-commit gate (quick checks + RSpec)
 yard-verify-public-docs: ## Verify essential YARD docs for all public methods in app/
 	bundle exec rake yard:verify_public_docs
 
-openapi: ## Regenerate docs/api/v1/openapi.yaml from request specs
+openapi: ## Regenerate public/openapi.yaml from request specs
 	bundle exec rake openapi:generate
 
-openapi-verify: ## Regenerate OpenAPI and fail if docs/api/v1/openapi.yaml or frontend client is stale
+openapi-verify: ## Regenerate OpenAPI and fail if public/openapi.yaml or frontend client is stale
 	bundle exec rake openapi:verify
 	$(MAKE) openapi-client-verify
 
-openapi-client: ## Generate frontend OpenAPI client/types from docs/api/v1/openapi.yaml
+openapi-client: ## Generate frontend OpenAPI client/types from public/openapi.yaml
 	@cd frontend && npm run openapi:generate
 
 openapi-client-verify: ## Generate frontend OpenAPI client and fail if generated files are stale
 	@cd frontend && npm run openapi:verify
 
-openapi-lint: openapi-lint-redocly openapi-lint-spectral ## Lint docs/api/v1/openapi.yaml with Redocly and Spectral
+openapi-lint: openapi-lint-redocly openapi-lint-spectral ## Lint public/openapi.yaml with Redocly and Spectral
 
 openapi-lint-redocly: ## Lint OpenAPI using Redocly recommended rules
-	npx --yes @redocly/cli lint --config .redocly.yaml docs/api/v1/openapi.yaml
+	npx --yes @redocly/cli lint --config .redocly.yaml public/openapi.yaml
 
 openapi-lint-spectral: ## Lint OpenAPI using Spectral OAS rules
-	npx --yes @stoplight/spectral-cli lint --ruleset .spectral.yaml docs/api/v1/openapi.yaml
+	npx --yes @stoplight/spectral-cli lint --ruleset .spectral.yaml public/openapi.yaml
 
 openai-lint-spectral: openapi-lint-spectral ## Alias for openapi-lint-spectral
 

README.md

@@ -20,7 +20,7 @@ html2rss-web converts arbitrary websites into RSS 2.0 feeds with a slim Ruby bac
 ## Architecture
 
 - **Backend:** Ruby + Roda, backed by the `html2rss` gem for extraction.
-- **Frontend:** Preact app built with Vite into `public/frontend`.
+- **Frontend:** Preact app built with Vite into `frontend/dist` and served at `/`.
 - **Distribution:** Docker Compose by default; other deployments require manual wiring.
 - [Project notes](docs/README.md)
 
@@ -85,7 +85,7 @@ For contributors and AI agents changing backend structure, follow the rules in [
 | `make lint`                    | Run all linters.                                           |
 | `make lintfix`                 | Auto-fix lint warnings where possible.                     |
 | `make yard-verify-public-docs` | Enforce typed YARD docs for public methods in `app/`.      |
-| `make openapi`                 | Regenerate `docs/api/v1/openapi.yaml` from request specs.  |
+| `make openapi`                 | Regenerate `public/openapi.yaml` from request specs.       |
 | `make openapi-verify`          | Regenerate + fail if OpenAPI file is stale.                |
 | `make clean`                   | Remove build artefacts.                                    |
 
@@ -101,7 +101,7 @@ The OpenAPI file is generated from Ruby request specs only.
 | Command                 | Purpose                                      |
 | ----------------------- | -------------------------------------------- |
 | `npm run dev`           | Vite dev server with hot reload (port 4001). |
-| `npm run build`         | Build static assets into `public/frontend`.  |
+| `npm run build`         | Build static assets into `frontend/dist/`.   |
 | `npm run test:run`      | Unit tests (Vitest).                         |
 | `npm run test:contract` | Contract tests with MSW.                     |
 

Rakefile

@@ -96,14 +96,14 @@ end
 namespace :openapi do
   desc 'Generate OpenAPI YAML from request specs'
   task :generate do
-    FileUtils.mkdir_p('docs/api/v1')
-    FileUtils.rm_f('docs/api/v1/openapi.yaml')
+    FileUtils.mkdir_p('public')
+    FileUtils.rm_f('public/openapi.yaml')
     sh({ 'OPENAPI' => '1' }, 'bundle exec rspec spec/html2rss/web/api/v1_spec.rb --order defined')
   end
 
   desc 'Verify generated OpenAPI YAML is up to date'
   task verify: :generate do
-    sh 'git diff --exit-code -- docs/api/v1/openapi.yaml'
+    sh 'git diff --exit-code -- public/openapi.yaml'
   end
 end
 

app.rb

@@ -31,6 +31,8 @@ class App < Roda
           </body>
         </html>
       HTML
+      FRONTEND_DIST_PATH = 'frontend/dist'
+      FRONTEND_INDEX_PATH = File.join(FRONTEND_DIST_PATH, 'index.html')
       def self.development? = EnvironmentValidator.development?
 
       def development? = self.class.development?
@@ -80,6 +82,10 @@ def development? = self.class.development?
       }
 
       plugin :json_parser
+      plugin :static,
+             ['/assets'],
+             root: FRONTEND_DIST_PATH,
+             headers: { 'Cache-Control' => 'public, max-age=31536000, immutable' }
       plugin :public
       plugin :head
       plugin :not_allowed
@@ -100,9 +106,8 @@ def development? = self.class.development?
       private
 
       def render_index_page(router)
-        index_path = 'public/frontend/index.html'
         router.response['Content-Type'] = 'text/html'
-        File.exist?(index_path) ? File.read(index_path) : FALLBACK_HTML
+        File.exist?(FRONTEND_INDEX_PATH) ? File.read(FRONTEND_INDEX_PATH) : FALLBACK_HTML
       end
     end
   end

app/web/api/v1/root_metadata.rb

@@ -15,7 +15,7 @@ def build(router)
                 api: {
                   name: 'html2rss-web API',
                   description: 'RESTful API for converting websites to RSS feeds',
-                  openapi_url: "#{router.base_url}/api/v1/openapi.yaml"
+                  openapi_url: "#{router.base_url}/openapi.yaml"
                 },
                 instance: instance_payload(router)
               }

app/web/routes/api_v1/metadata_routes.rb

@@ -23,8 +23,7 @@ def call(router)
             def mount_openapi_spec(router)
               router.on 'openapi.yaml' do
                 router.get do
-                  router.response['Content-Type'] = 'application/yaml'
-                  openapi_spec_contents
+                  router.redirect '/openapi.yaml', 301
                 end
               end
             end
@@ -55,29 +54,11 @@ def mount_root(router)
               end
             end
 
-            # @return [String]
-            def openapi_spec_path
-              File.expand_path('../../../../docs/api/v1/openapi.yaml', __dir__)
-            end
-
             # @param router [Roda::RodaRequest]
             # @return [String]
             def render_root_metadata(router)
               JSON.generate(Api::V1::Response.success(data: Api::V1::RootMetadata.build(router)))
             end
-
-            # @return [String]
-            def openapi_spec_contents
-              return File.read(openapi_spec_path) if File.exist?(openapi_spec_path)
-
-              <<~YAML
-                openapi: 3.0.3
-                info:
-                  title: html2rss-web API
-                  version: 1.0.0
-                paths: {}
-              YAML
-            end
           end
         end
       end