feat: migrate to zeitwerk

Gemfile

@@ -17,12 +17,12 @@ gem 'rack-cache'
 gem 'rack-timeout'
 gem 'roda'
 gem 'ssrf_filter'
+gem 'zeitwerk'
 
 gem 'puma', require: false
 
 group :development do
   gem 'byebug'
-  gem 'rack-unreloader'
   gem 'rake', require: false
   gem 'rubocop', require: false
   gem 'rubocop-performance', require: false

Gemfile.lock

@@ -246,7 +246,6 @@ GEM
     rack-test (2.2.0)
       rack (>= 1.3)
     rack-timeout (0.7.0)
-    rack-unreloader (2.1.0)
     rails-dom-testing (2.3.0)
       activesupport (>= 5.0.0)
       minitest
@@ -375,7 +374,6 @@ DEPENDENCIES
   rack-cache
   rack-test
   rack-timeout
-  rack-unreloader
   rake
   roda
   rspec
@@ -393,6 +391,7 @@ DEPENDENCIES
   vcr
   webmock
   yard
+  zeitwerk
 
 CHECKSUMS
   actionpack (8.1.2) sha256=ced74147a1f0daafaa4bab7f677513fd4d3add574c7839958f7b4f1de44f8423
@@ -483,7 +482,6 @@ CHECKSUMS
   rack-session (2.1.1) sha256=0b6dc07dea7e4b583f58a48e8b806d4c9f1c6c9214ebc202ec94562cbea2e4e9
   rack-test (2.2.0) sha256=005a36692c306ac0b4a9350355ee080fd09ddef1148a5f8b2ac636c720f5c463
   rack-timeout (0.7.0) sha256=757337e9793cca999bb73a61fe2a7d4280aa9eefbaf787ce3b98d860749c87d9
-  rack-unreloader (2.1.0) sha256=18879cf2ced8ca21a01836bca706f65cce6ebe3f7d9d8a5157ce68ca62c7263a
   rails-dom-testing (2.3.0) sha256=8acc7953a7b911ca44588bf08737bc16719f431a1cc3091a292bca7317925c1d
   rails-html-sanitizer (1.7.0) sha256=28b145cceaf9cc214a9874feaa183c3acba036c9592b19886e0e45efc62b1e89
   rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a

Makefile

@@ -58,6 +58,8 @@ lint: lint-ruby lint-js ## Run all linters (Ruby + Frontend) - errors when issue
 lint-ruby: ## Run Ruby linter (RuboCop) - errors when issues found
 	@echo "Running RuboCop linting..."
 	bundle exec rubocop
+	@echo "Running Zeitwerk eager-load check..."
+	bundle exec rake zeitwerk:verify
 	@echo "Running YARD public-method docs check..."
 	bundle exec rake yard:verify_public_docs
 	@echo "Ruby linting complete!"

README.md

@@ -66,6 +66,10 @@ make openapi
 
 Dev URLs: Ruby app at `http://localhost:4000`, frontend dev server at `http://localhost:4001`.
 
+Backend code under the `Html2rss::Web` namespace now lives under `app/web/**`, so Zeitwerk can mirror constant paths directly instead of relying on directory-specific namespace wiring.
+`make ready` also runs `rake zeitwerk:verify`, which eager-loads the app and fails on loader drift early.
+For contributors and AI agents changing backend structure, follow the placement rules in [docs/ai-agent-app-web.md](docs/ai-agent-app-web.md).
+
 ## Make Targets
 
 | Command              | Purpose                                                 |

Rakefile

@@ -139,3 +139,14 @@ namespace :yard do
     puts 'YARD public method documentation check passed.'
   end
 end
+
+namespace :zeitwerk do
+  desc 'Fail when Zeitwerk cannot eager load the app tree cleanly'
+  task :verify do
+    ENV['RACK_ENV'] ||= 'test'
+    require_relative 'app'
+
+    Html2rss::Web::Boot.eager_load!
+    puts 'Zeitwerk eager load check passed.'
+  end
+end

app.rb

@@ -6,7 +6,10 @@
 require 'base64'
 
 require 'html2rss'
-Dir[File.join(__dir__, 'app/**/*.rb')].each { |file| require file }
+require_relative 'app/web/boot'
+
+Html2rss::Web::Boot.setup!(reloadable: ENV['RACK_ENV'] == 'development')
+Html2rss::Web::Boot::Setup.call!
 
 module Html2rss
   module Web
@@ -31,13 +34,6 @@ class App < Roda
       def self.development? = EnvironmentValidator.development?
 
       def development? = self.class.development?
-      EnvironmentValidator.validate_environment!
-      EnvironmentValidator.validate_production_security!
-      Flags.validate!
-
-      Html2rss::RequestService.register_strategy(:ssrf_filter, SsrfFilterStrategy)
-      Html2rss::RequestService.default_strategy_name = :ssrf_filter
-      Html2rss::RequestService.unregister_strategy(:faraday)
       opts.merge!(check_dynamic_arity: false, check_arity: :warn)
       use RequestContextMiddleware
       use Rack::Cache, metastore: 'file:./tmp/rack-cache-meta', entitystore: 'file:./tmp/rack-cache-body',
@@ -85,6 +81,8 @@ def development? = self.class.development?
 
       plugin :json_parser
       plugin :public
+      plugin :head
+      plugin :not_allowed
       plugin :exception_page
       plugin :error_handler do |error|
         next exception_page(error) if development?