feat: install generator (#72)

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Install generator — `rails generate solid_stack_web:install` creates `config/initializers/solid_stack_web.rb` with every config option documented inline and injects the mount line into `config/routes.rb`
+
 ## [0.8.0] - 2026-05-26
 
 ### Added

ROADMAP.md

@@ -10,8 +10,7 @@ The path to v1.0.0 is staged: first achieve feature parity with `solid_queue_das
 
 > _Make it easy to adopt and easy to contribute to._
 
-### Added
-- **Install generator** — `rails generate solid_stack_web:install` creates the initializer with all config options documented inline
+### Remaining
 - **Configurable mount path helper** — engine-aware path helpers that respect whatever `at:` the host app chose
 - **Accessibility pass** — keyboard navigation, ARIA labels on interactive elements, sufficient colour contrast in both themes
 - **Query optimisation** — eliminate N+1 queries across all list views; add covering indexes to the dummy app schema

lib/generators/solid_stack_web/install/install_generator.rb

@@ -0,0 +1,19 @@
+require "rails/generators/base"
+
+module SolidStackWeb
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a SolidStackWeb initializer and mounts the engine in routes.rb"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/solid_stack_web.rb"
+      end
+
+      def mount_engine
+        route 'mount SolidStackWeb::Engine, at: "/solid_stack"'
+      end
+    end
+  end
+end

lib/generators/solid_stack_web/install/templates/initializer.rb

@@ -0,0 +1,44 @@
+SolidStackWeb.configure do |config|
+  # Authentication — block runs in controller context.
+  # Return a truthy value to allow access; falsy falls back to HTTP Basic auth.
+  # If omitted entirely, the dashboard is open to anyone.
+  #
+  #   config.authenticate do
+  #     current_user&.admin?
+  #   end
+
+  # Number of records shown per paginated page (default: 25).
+  # config.page_size = 25
+
+  # Database connection — pass a connects_to hash when Solid Queue / Cache / Cable
+  # live on a separate database from your primary.
+  #
+  #   config.connects_to = { database: { writing: :queue, reading: :queue } }
+
+  # Slow-job threshold in seconds (default: nil — stat hidden).
+  # When set, the dashboard shows a "Slow (24h)" count on the overview card
+  # for finished jobs whose wall time exceeded this value.
+  # config.slow_job_threshold = 30
+
+  # Auto-refresh intervals in milliseconds.
+  # config.dashboard_refresh_interval = 5_000   # overview dashboard
+  # config.default_refresh_interval   = 10_000  # jobs, processes, history
+
+  # Maximum number of results returned by the search feature (default: 25).
+  # config.search_results_limit = 25
+
+  # Show the raw serialised value on the cache entry detail page (default: false).
+  # Disable for stores that contain sensitive data.
+  # config.allow_value_preview = false
+
+  # Alert webhook — POST to this URL when a threshold is breached.
+  # Delivery failures are silently swallowed; configure a cooldown to avoid storms.
+  #
+  # config.alert_webhook_url       = "https://hooks.example.com/my-alert"
+  # config.alert_failure_threshold = 10      # fire when failed jobs >= this
+  # config.alert_queue_thresholds  = {       # fire when a queue's ready depth >= value
+  #   "critical" => 50,
+  #   "default"  => 500
+  # }
+  # config.alert_webhook_cooldown  = 3600   # seconds between repeat alerts
+end

spec/generators/solid_stack_web/install_generator_spec.rb

@@ -0,0 +1,66 @@
+require "rails_helper"
+require "rails/generators"
+require "rails/generators/testing/assertions"
+require "rails/generators/testing/setup_and_teardown"
+require "rails/generators/testing/behavior"
+require "generators/solid_stack_web/install/install_generator"
+
+RSpec.describe SolidStackWeb::Generators::InstallGenerator do
+  include Rails::Generators::Testing::Behavior
+  include Rails::Generators::Testing::Assertions
+  include FileUtils
+
+  tests SolidStackWeb::Generators::InstallGenerator
+  destination File.expand_path("../../../tmp/generator_test", __dir__)
+
+  before do
+    prepare_destination
+    mkdir_p File.join(destination_root, "config")
+    File.write(File.join(destination_root, "config/routes.rb"), <<~RUBY)
+      Rails.application.routes.draw do
+      end
+    RUBY
+  end
+
+  describe "initializer" do
+    before { run_generator }
+
+    it "creates the initializer file" do
+      assert_file "config/initializers/solid_stack_web.rb"
+    end
+
+    it "includes the configure block" do
+      assert_file "config/initializers/solid_stack_web.rb",
+                  /SolidStackWeb\.configure do \|config\|/
+    end
+
+    it "documents the authenticate option" do
+      assert_file "config/initializers/solid_stack_web.rb", /config\.authenticate/
+    end
+
+    it "documents the page_size option" do
+      assert_file "config/initializers/solid_stack_web.rb", /config\.page_size/
+    end
+
+    it "documents the slow_job_threshold option" do
+      assert_file "config/initializers/solid_stack_web.rb", /config\.slow_job_threshold/
+    end
+
+    it "documents the alert_webhook_url option" do
+      assert_file "config/initializers/solid_stack_web.rb", /config\.alert_webhook_url/
+    end
+
+    it "documents the allow_value_preview option" do
+      assert_file "config/initializers/solid_stack_web.rb", /config\.allow_value_preview/
+    end
+  end
+
+  describe "routes" do
+    before { run_generator }
+
+    it "injects the mount line into routes.rb" do
+      assert_file "config/routes.rb",
+                  /mount SolidStackWeb::Engine, at: "\/solid_stack"/
+    end
+  end
+end

spec/spec_helper.rb

@@ -9,6 +9,7 @@
 SimpleCov.start "rails" do
   add_filter "/spec/"
   add_filter "/lib/solid_stack_web/version.rb"
+  add_filter "/lib/generators/"
 
   add_group "Controllers", "app/controllers"
   add_group "Helpers",     "app/helpers"