feat: simplify feed creation contract & backend error handling (#962)

## Summary
- simplify feed creation around auto-source and remove strategy from
create payload/result
- add structured backend error metadata and feed empty-extraction
handling
- clean token/access internals, Sentry breadcrumbs, OpenAPI/types, and
related docs

## Validation
- make setup && make ready inside devcontainer image
- make ready inside devcontainer image
- make openapi-verify && make openapi-lint inside devcontainer image
with host gitdir mounted

## Slice notes
- Source branch: preact-router @ 3b1e647
- Backup branch: backup/preact-router-3b1e647
- Excludes frontend routed workflow and result UX/tooling polish for
later slices

Author: gildesmarais

Gemfile

@@ -4,14 +4,15 @@ source 'https://rubygems.org'
 
 git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
-gem 'html2rss', '~> 0.18'
-# gem 'html2rss', github: 'html2rss/html2rss', branch: :master
+# gem 'html2rss', '~> 0.18'
+gem 'html2rss', github: 'html2rss/html2rss', branch: 'codex-pr-auto-fallback-pipeline'
 gem 'html2rss-configs', github: 'html2rss/html2rss-configs'
 
 # Use these instead of the two above (uncomment them) when developing locally:
 # gem 'html2rss', path: '../html2rss'
 # gem 'html2rss-configs', path: '../html2rss-configs'
 
+gem 'concurrent-ruby'
 gem 'parallel'
 gem 'rack-cache'
 gem 'rack-timeout'
@@ -21,7 +22,6 @@ gem 'zeitwerk'
 gem 'puma', require: false
 
 group :development do
-  gem 'byebug'
   gem 'irb', require: false
   gem 'rake', require: false
   gem 'rubocop', require: false

Gemfile.lock

@@ -1,3 +1,28 @@
+GIT
+  remote: https://github.com/html2rss/html2rss
+  revision: 54f6f53482352932b69621f1df989f83cd285c72
+  branch: codex-pr-auto-fallback-pipeline
+  specs:
+    html2rss (0.18.0)
+      addressable (~> 2.7)
+      brotli
+      dry-validation
+      faraday (> 2.0.1, < 3.0)
+      faraday-follow_redirects
+      faraday-gzip (~> 3)
+      kramdown
+      mime-types (> 3.0)
+      nokogiri (>= 1.10, < 2.0)
+      parallel
+      puppeteer-ruby
+      regexp_parser
+      reverse_markdown (~> 3.0)
+      rss
+      sanitize
+      thor
+      tzinfo
+      zeitwerk
+
 GIT
   remote: https://github.com/html2rss/html2rss-configs
   revision: 71981aff28d88e4553c206d78bf54d5633bcdd19
@@ -68,8 +93,6 @@ GEM
     bigdecimal (4.1.2)
     brotli (0.8.0)
     builder (3.3.0)
-    byebug (13.0.0)
-      reline (>= 0.6.0)
     climate_control (1.2.0)
     concurrent-ruby (1.3.6)
     connection_pool (3.0.2)
@@ -138,25 +161,6 @@ GEM
       fiber-storage
     fiber-storage (1.0.1)
     hashdiff (1.2.1)
-    html2rss (0.18.0)
-      addressable (~> 2.7)
-      brotli
-      dry-validation
-      faraday (> 2.0.1, < 3.0)
-      faraday-follow_redirects
-      faraday-gzip (~> 3)
-      kramdown
-      mime-types (> 3.0)
-      nokogiri (>= 1.10, < 2.0)
-      parallel
-      puppeteer-ruby
-      regexp_parser
-      reverse_markdown (~> 3.0)
-      rss
-      sanitize
-      thor
-      tzinfo
-      zeitwerk
     i18n (1.14.8)
       concurrent-ruby (~> 1.0)
     io-console (0.8.2)
@@ -371,9 +375,9 @@ PLATFORMS
   x86_64-linux-musl
 
 DEPENDENCIES
-  byebug
   climate_control
-  html2rss (~> 0.18)
+  concurrent-ruby
+  html2rss!
   html2rss-configs!
   irb
   parallel
@@ -413,7 +417,6 @@ CHECKSUMS
   bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
   brotli (0.8.0) sha256=0c5a42046b3b603fb109656881147fd76064c034b7d19c1b4fcc32a093a4d55d
   builder (3.3.0) sha256=497918d2f9dca528fdca4b88d84e4ef4387256d984b8154e9d5d3fe5a9c8835f
-  byebug (13.0.0) sha256=d2263efe751941ca520fa29744b71972d39cbc41839496706f5d9b22e92ae05d
   climate_control (1.2.0) sha256=36b21896193fa8c8536fa1cd843a07cf8ddbd03aaba43665e26c53ec1bd70aa5
   concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
   connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a
@@ -442,7 +445,7 @@ CHECKSUMS
   fiber-local (1.1.0) sha256=c885f94f210fb9b05737de65d511136ea602e00c5105953748aa0f8793489f06
   fiber-storage (1.0.1) sha256=f48e5b6d8b0be96dac486332b55cee82240057065dc761c1ea692b2e719240e1
   hashdiff (1.2.1) sha256=9c079dbc513dfc8833ab59c0c2d8f230fa28499cc5efb4b8dd276cf931457cd1
-  html2rss (0.18.0) sha256=83e9dd0388d65f1992df4afc9d345cbfd84e8c740be3756815b5e840ac71cf54
+  html2rss (0.18.0)
   html2rss-configs (0.2.0)
   i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc

app.rb

@@ -13,6 +13,21 @@
 
 module Html2rss
   module Web
+    DEFAULT_HEADERS = {
+      'X-Content-Type-Options' => 'nosniff',
+      'X-XSS-Protection' => '1; mode=block',
+      'X-Frame-Options' => 'SAMEORIGIN',
+      'X-Permitted-Cross-Domain-Policies' => 'none',
+      'Referrer-Policy' => 'strict-origin-when-cross-origin',
+      'Permissions-Policy' => 'geolocation=(), microphone=(), camera=()',
+      'Strict-Transport-Security' => 'max-age=31536000; includeSubDomains; preload',
+      'Cross-Origin-Embedder-Policy' => 'require-corp',
+      'Cross-Origin-Opener-Policy' => 'same-origin',
+      'Cross-Origin-Resource-Policy' => 'same-origin',
+      'X-DNS-Prefetch-Control' => 'off',
+      'X-Download-Options' => 'noopen'
+    }.freeze
+
     ##
     # Roda app serving RSS feeds via html2rss
     class App < Roda
@@ -32,7 +47,8 @@ class App < Roda
         </html>
       HTML
       FRONTEND_DIST_PATH = 'frontend/dist'
-      FRONTEND_INDEX_PATH = File.join(FRONTEND_DIST_PATH, 'index.html')
+      FRONTEND_DIST_INDEX_PATH = File.join(FRONTEND_DIST_PATH, 'index.html')
+      FRONTEND_SOURCE_INDEX_PATH = 'frontend/index.html'
       def self.development? = EnvironmentValidator.development?
 
       def development? = self.class.development?
@@ -43,7 +59,7 @@ def development? = self.class.development?
 
       plugin :content_security_policy do |csp|
         csp.default_src :none
-        csp.style_src :self, "'unsafe-inline'"
+        csp.style_src :self
         csp.script_src :self
         csp.connect_src :self
         csp.img_src :self
@@ -65,21 +81,7 @@ def development? = self.class.development?
         csp.block_all_mixed_content
         csp.upgrade_insecure_requests
       end
-
-      plugin :default_headers, {
-        'X-Content-Type-Options' => 'nosniff',
-        'X-XSS-Protection' => '1; mode=block',
-        'X-Frame-Options' => 'SAMEORIGIN',
-        'X-Permitted-Cross-Domain-Policies' => 'none',
-        'Referrer-Policy' => 'strict-origin-when-cross-origin',
-        'Permissions-Policy' => 'geolocation=(), microphone=(), camera=()',
-        'Strict-Transport-Security' => 'max-age=31536000; includeSubDomains; preload',
-        'Cross-Origin-Embedder-Policy' => 'require-corp',
-        'Cross-Origin-Opener-Policy' => 'same-origin',
-        'Cross-Origin-Resource-Policy' => 'same-origin',
-        'X-DNS-Prefetch-Control' => 'off',
-        'X-Download-Options' => 'noopen'
-      }
+      plugin :default_headers, DEFAULT_HEADERS
 
       plugin :json_parser
       plugin :static,
@@ -91,7 +93,7 @@ def development? = self.class.development?
       plugin :not_allowed
       plugin :exception_page
       plugin :error_handler do |error|
-        next exception_page(error) if development?
+        next exception_page(error) if development? && !error.is_a?(HttpError)
 
         ErrorResponder.respond(request: request, response: response, error: error)
       end
@@ -107,7 +109,16 @@ def development? = self.class.development?
 
       def render_index_page(router)
         router.response['Content-Type'] = 'text/html'
-        File.exist?(FRONTEND_INDEX_PATH) ? File.read(FRONTEND_INDEX_PATH) : FALLBACK_HTML
+        index_path = index_page_path
+        return File.read(index_path) if index_path
+
+        FALLBACK_HTML
+      end
+
+      def index_page_path
+        return FRONTEND_DIST_INDEX_PATH if File.exist?(FRONTEND_DIST_INDEX_PATH)
+
+        FRONTEND_SOURCE_INDEX_PATH if development? && File.exist?(FRONTEND_SOURCE_INDEX_PATH)
       end
     end
   end