source_monitor 0.1.1 → 0.1.2

data/lib/source_monitor/setup/prompter.rb

@@ -0,0 +1,34 @@
+require "thor"
+
+module SourceMonitor
+  module Setup
+    class Prompter
+      def initialize(shell: Thor::Shell::Basic.new, auto_yes: false)
+        @shell = shell
+        @auto_yes = auto_yes
+      end
+
+      def ask(question, default: nil)
+        return default if auto_yes
+
+        prompt = default ? "#{question} [#{default}]" : question
+        response = shell.ask(prompt).to_s.strip
+        response.empty? ? default : response
+      end
+
+      def yes?(question, default: true)
+        return default if auto_yes
+
+        suffix = default ? "Y/n" : "y/N"
+        response = shell.ask("#{question} (#{suffix})").to_s.strip.downcase
+        return default if response.empty?
+
+        %w[y yes].include?(response)
+      end
+
+      private
+
+      attr_reader :shell, :auto_yes
+    end
+  end
+end

data/lib/source_monitor/setup/requirements.rb

@@ -0,0 +1,51 @@
+module SourceMonitor
+  module Setup
+    module Requirements
+      class Version
+        attr_reader :requirement
+
+        def initialize(spec)
+          @requirement = Gem::Requirement.new(spec)
+        end
+
+        def expected
+          requirement.to_s
+        end
+
+        def normalize(value)
+          return if value.blank?
+
+          normalized = value.to_s.strip.sub(/^v/i, "")
+          Gem::Version.new(normalized)
+        rescue ArgumentError
+          nil
+        end
+
+        def satisfied?(value)
+          version = normalize(value)
+          return false unless version
+
+          requirement.satisfied_by?(version)
+        end
+      end
+
+      class Adapter
+        attr_reader :expected
+
+        def initialize(expected)
+          @expected = expected.to_s
+        end
+
+        def normalize(value)
+          value&.to_s
+        end
+
+        def satisfied?(value)
+          return false if value.blank?
+
+          value.to_s.casecmp(expected).zero?
+        end
+      end
+    end
+  end
+end

data/lib/source_monitor/setup/shell_runner.rb

@@ -0,0 +1,14 @@
+require "open3"
+
+module SourceMonitor
+  module Setup
+    class ShellRunner
+      def run(*command)
+        stdout, status = Open3.capture2e(*command)
+        status.success? ? stdout.strip : nil
+      rescue Errno::ENOENT
+        nil
+      end
+    end
+  end
+end

data/lib/source_monitor/setup/verification/action_cable_verifier.rb

@@ -0,0 +1,79 @@
+module SourceMonitor
+  module Setup
+    module Verification
+      class ActionCableVerifier
+        def initialize(config: SourceMonitor.config.realtime, cable_config: default_cable_config, connection: default_connection)
+          @config = config
+          @cable_config = cable_config
+          @connection = connection
+        end
+
+        def call
+          case adapter
+          when :solid_cable
+            verify_solid_cable
+          when :redis
+            verify_redis
+          else
+            warning_result("Realtime adapter #{adapter.inspect} is not recognized", "Set config.realtime.adapter to :solid_cable or :redis in the initializer")
+          end
+        rescue StandardError => e
+          error_result("Action Cable verification failed: #{e.message}", "Double-check Action Cable configuration and credentials")
+        end
+
+        private
+
+        attr_reader :config, :cable_config, :connection
+
+        def adapter
+          config.adapter
+        end
+
+        def default_cable_config
+          ActionCable.server.config.cable
+        rescue StandardError
+          {}
+        end
+
+        def default_connection
+          ActiveRecord::Base.connection
+        rescue StandardError
+          nil
+        end
+
+        def verify_solid_cable
+          unless defined?(SolidCable)
+            return error_result("Solid Cable gem is not loaded", "Add `solid_cable` to your Gemfile or switch to the Redis adapter")
+          end
+
+          unless connection&.table_exists?("solid_cable_messages")
+            return error_result("Solid Cable tables are missing", "Run `rails solid_cable:install` or copy the engine migration that creates solid_cable_messages")
+          end
+
+          ok_result("Solid Cable tables detected and the gem is loaded")
+        end
+
+        def verify_redis
+          url = config.redis_url.presence || cable_config[:url]
+          if url.blank?
+            return error_result("Redis adapter configured without a URL", "Set config.realtime.redis_url or supply :url in your cable.yml")
+          end
+
+          ok_result("Redis Action Cable configuration detected (#{url})")
+        end
+
+        def ok_result(details)
+          Result.new(key: :action_cable, name: "Action Cable", status: :ok, details: details)
+        end
+
+        def warning_result(details, remediation)
+          Result.new(key: :action_cable, name: "Action Cable", status: :warning, details: details, remediation: remediation)
+        end
+
+        def error_result(details, remediation)
+          Result.new(key: :action_cable, name: "Action Cable", status: :error, details: details, remediation: remediation)
+        end
+      end
+    end
+  end
+end

data/lib/source_monitor/setup/verification/printer.rb

@@ -0,0 +1,24 @@
+module SourceMonitor
+  module Setup
+    module Verification
+      class Printer
+        def initialize(shell: Thor::Shell::Basic.new)
+          @shell = shell
+        end
+
+        def print(summary)
+          shell.say("Verification summary (#{summary.overall_status.upcase}):")
+          summary.results.each do |result|
+            shell.say("- #{result.name}: #{result.status.upcase} - #{result.details}")
+            shell.say("  Remediation: #{result.remediation}") if result.remediation.present?
+          end
+          shell.say("JSON: #{summary.to_json}")
+        end
+
+        private
+
+        attr_reader :shell
+      end
+    end
+  end
+end

data/lib/source_monitor/setup/verification/result.rb

@@ -0,0 +1,68 @@
+require "json"
+
+module SourceMonitor
+  module Setup
+    module Verification
+      Result = Struct.new(
+        :key,
+        :name,
+        :status,
+        :details,
+        :remediation,
+        keyword_init: true
+      ) do
+        def ok?
+          status == :ok
+        end
+
+        def warning?
+          status == :warning
+        end
+
+        def error?
+          status == :error
+        end
+
+        def as_json(_options = nil)
+          {
+            key: key,
+            name: name,
+            status: status,
+            details: details,
+            remediation: remediation
+          }
+        end
+      end
+
+      class Summary
+        attr_reader :results
+
+        def initialize(results)
+          @results = results
+        end
+
+        def overall_status
+          return :error if results.any?(&:error?)
+          return :warning if results.any?(&:warning?)
+
+          :ok
+        end
+
+        def ok?
+          overall_status == :ok
+        end
+
+        def to_h
+          {
+            overall_status: overall_status,
+            results: results.map(&:as_json)
+          }
+        end
+
+        def to_json(*args)
+          to_h.to_json(*args)
+        end
+      end
+    end
+  end
+end

data/lib/source_monitor/setup/verification/runner.rb

@@ -0,0 +1,24 @@
+module SourceMonitor
+  module Setup
+    module Verification
+      class Runner
+        def initialize(verifiers: default_verifiers)
+          @verifiers = verifiers
+        end
+
+        def call
+          results = verifiers.map { |verifier| verifier.call }
+          Summary.new(results)
+        end
+
+        private
+
+        attr_reader :verifiers
+
+        def default_verifiers
+          [ SolidQueueVerifier.new, ActionCableVerifier.new ]
+        end
+      end
+    end
+  end
+end

data/lib/source_monitor/setup/verification/solid_queue_verifier.rb

@@ -0,0 +1,75 @@
+module SourceMonitor
+  module Setup
+    module Verification
+      class SolidQueueVerifier
+        DEFAULT_HEARTBEAT_THRESHOLD = 2.minutes
+
+        def initialize(process_relation: default_process_relation, connection: default_connection, clock: -> { Time.current })
+          @process_relation = process_relation
+          @connection = connection
+          @clock = clock
+        end
+
+        def call
+          return missing_gem_result unless process_relation
+          return missing_tables_result unless tables_present?
+
+          recent = recent_workers?
+
+          if recent
+            ok_result("Solid Queue workers are reporting heartbeats")
+          else
+            warning_result("No Solid Queue workers have reported in the last #{DEFAULT_HEARTBEAT_THRESHOLD.inspect}", "Start a Solid Queue worker with `bin/rails solid_queue:start` and ensure it stays running")
+          end
+        rescue StandardError => e
+          error_result("Solid Queue verification failed: #{e.message}", "Verify Solid Queue migrations are up to date and workers can access the database")
+        end
+
+        private
+
+        attr_reader :process_relation, :connection, :clock
+
+        def default_process_relation
+          SolidQueue::Process if defined?(SolidQueue::Process)
+        end
+
+        def default_connection
+          SolidQueue::Process.connection if defined?(SolidQueue::Process)
+        rescue StandardError
+          nil
+        end
+
+        def tables_present?
+          return false unless connection
+
+          connection.table_exists?(process_relation.table_name)
+        end
+
+        def recent_workers?
+          cutoff = clock.call - DEFAULT_HEARTBEAT_THRESHOLD
+          process_relation.where("last_heartbeat_at >= ?", cutoff).exists?
+        end
+
+        def missing_gem_result
+          error_result("Solid Queue gem is not available", "Add `solid_queue` to your Gemfile and bundle install")
+        end
+
+        def missing_tables_result
+          error_result("Solid Queue tables are missing", "Run `rails solid_queue:install` or copy the engine's Solid Queue migration")
+        end
+
+        def ok_result(details)
+          Result.new(key: :solid_queue, name: "Solid Queue", status: :ok, details: details)
+        end
+
+        def warning_result(details, remediation)
+          Result.new(key: :solid_queue, name: "Solid Queue", status: :warning, details: details, remediation: remediation)
+        end
+
+        def error_result(details, remediation)
+          Result.new(key: :solid_queue, name: "Solid Queue", status: :error, details: details, remediation: remediation)
+        end
+      end
+    end
+  end
+end

data/lib/source_monitor/setup/verification/telemetry_logger.rb

@@ -0,0 +1,33 @@
+require "fileutils"
+require "pathname"
+
+module SourceMonitor
+  module Setup
+    module Verification
+      class TelemetryLogger
+        def initialize(path: nil)
+          @path = Pathname.new(path || default_path)
+        end
+
+        def log(summary)
+          FileUtils.mkdir_p(path.dirname)
+          path.open("a") do |file|
+            file.puts({ timestamp: Time.current.iso8601, payload: summary.to_h }.to_json)
+          end
+        end
+
+        private
+
+        attr_reader :path
+
+        def default_path
+          if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+            Rails.root.join("log", "source_monitor_setup.log")
+          else
+            Pathname.new("log/source_monitor_setup.log")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/source_monitor/setup/workflow.rb

@@ -0,0 +1,99 @@
+require "pathname"
+
+module SourceMonitor
+  module Setup
+    class Workflow
+      DEFAULT_MOUNT_PATH = "/source_monitor".freeze
+
+      class RequirementError < StandardError
+        attr_reader :summary
+
+        def initialize(summary)
+          @summary = summary
+          super(build_message)
+        end
+
+        private
+
+        def build_message
+          messages = summary.errors.map do |result|
+            "#{result.name}: #{result.remediation}".strip
+          end
+          "Setup requirements failed. #{messages.join(' ')}"
+        end
+      end
+
+      def initialize(
+        dependency_checker: DependencyChecker.new,
+        prompter: Prompter.new,
+        gemfile_editor: GemfileEditor.new,
+        bundle_installer: BundleInstaller.new,
+        node_installer: NodeInstaller.new,
+        install_generator: InstallGenerator.new,
+        migration_installer: MigrationInstaller.new,
+        initializer_patcher: InitializerPatcher.new,
+        devise_detector: method(:default_devise_detector),
+        verifier: Verification::Runner.new
+      )
+        @dependency_checker = dependency_checker
+        @prompter = prompter
+        @gemfile_editor = gemfile_editor
+        @bundle_installer = bundle_installer
+        @node_installer = node_installer
+        @install_generator = install_generator
+        @migration_installer = migration_installer
+        @initializer_patcher = initializer_patcher
+        @devise_detector = devise_detector
+        @verifier = verifier
+      end
+
+      def run
+        summary = dependency_checker.call
+        raise RequirementError, summary if summary.errors?
+
+        mount_path = prompter.ask("Mount SourceMonitor at which path?", default: DEFAULT_MOUNT_PATH)
+
+        gemfile_editor.ensure_entry
+        bundle_installer.install
+        node_installer.install_if_needed
+        install_generator.run(mount_path: mount_path)
+        migration_installer.install
+        initializer_patcher.ensure_navigation_hint(mount_path: mount_path)
+
+        if devise_available? && prompter.yes?("Wire Devise authentication hooks into SourceMonitor?", default: true)
+          initializer_patcher.ensure_devise_hooks
+        end
+
+        verifier.call
+      end
+
+      private
+
+      attr_reader :dependency_checker,
+        :prompter,
+        :gemfile_editor,
+        :bundle_installer,
+        :node_installer,
+        :install_generator,
+        :migration_installer,
+        :initializer_patcher,
+        :devise_detector,
+        :verifier
+
+      def devise_available?
+        !!devise_detector.call
+      end
+
+      def default_devise_detector
+        Gem.loaded_specs.key?("devise") || gemfile_mentions_devise?
+      end
+
+      def gemfile_mentions_devise?
+        gemfile = Pathname.new("Gemfile")
+        gemfile.exist? && gemfile.read.include?("devise")
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/source_monitor/version.rb

@@ -1,3 +1,3 @@
 module SourceMonitor
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/source_monitor.rb

@@ -81,6 +81,25 @@ require "source_monitor/scheduler"
 require "source_monitor/items/item_creator"
 require "source_monitor/health"
 require "source_monitor/assets"
+require "source_monitor/setup/requirements"
+require "source_monitor/setup/shell_runner"
+require "source_monitor/setup/detectors"
+require "source_monitor/setup/dependency_checker"
+require "source_monitor/setup/prompter"
+require "source_monitor/setup/gemfile_editor"
+require "source_monitor/setup/bundle_installer"
+require "source_monitor/setup/node_installer"
+require "source_monitor/setup/install_generator"
+require "source_monitor/setup/migration_installer"
+require "source_monitor/setup/initializer_patcher"
+require "source_monitor/setup/verification/result"
+require "source_monitor/setup/verification/solid_queue_verifier"
+require "source_monitor/setup/verification/action_cable_verifier"
+require "source_monitor/setup/verification/runner"
+require "source_monitor/setup/verification/printer"
+require "source_monitor/setup/verification/telemetry_logger"
+require "source_monitor/setup/workflow"
+require "source_monitor/setup/cli"
 
 module SourceMonitor
   class << self

data/lib/tasks/source_monitor_setup.rake

@@ -0,0 +1,39 @@
+namespace :source_monitor do
+  namespace :setup do
+    desc "Verify host dependencies before running the guided SourceMonitor installer"
+    task check: :environment do
+      summary = SourceMonitor::Setup::DependencyChecker.new.call
+
+      puts "SourceMonitor dependency check:" # rubocop:disable Rails/Output
+      summary.results.each do |result|
+        status = result.status.to_s.upcase
+        current = result.current ? result.current.to_s : "missing"
+        expected = result.expected || "n/a"
+        puts "- #{result.name}: #{status} (current: #{current}, required: #{expected})" # rubocop:disable Rails/Output
+      end
+
+      if summary.errors?
+        messages = summary.errors.map do |result|
+          "#{result.name}: #{result.remediation}"
+        end
+
+        raise "SourceMonitor setup requirements failed. #{messages.join(' ')}"
+      end
+    end
+
+    desc "Verify queue workers, Action Cable, and telemetry hooks"
+    task verify: :environment do
+      summary = SourceMonitor::Setup::Verification::Runner.new.call
+      printer = SourceMonitor::Setup::Verification::Printer.new
+      printer.print(summary)
+
+      if ENV["SOURCE_MONITOR_SETUP_TELEMETRY"].present?
+        SourceMonitor::Setup::Verification::TelemetryLogger.new.log(summary)
+      end
+
+      unless summary.ok?
+        raise "SourceMonitor setup verification failed. See output above for remediation steps."
+      end
+    end
+  end
+end

data/tasks/prd-setup-workflow-streamlining.md

@@ -0,0 +1,68 @@
+# Streamlined Setup Workflow for SourceMonitor Engine
+
+## 1. Introduction / Overview
+Teams currently follow a long, error-prone checklist to integrate the SourceMonitor engine into either brand-new or existing Rails 8 hosts. Manual gem edits, generator invocations, migration copying, authentication wiring, and Solid Queue/Solid Cable verification create setup drift and delayed feedback when something fails. This PRD defines a streamlined workflow that combines authoritative checklists with guided automation (scripts/generators) so users can reliably install, mount, and validate the engine with minimal switching between docs and terminals. The primary goal is to reduce manual tasks and error risk when onboarding SourceMonitor into any Rails app that meets the core prerequisites.
+
+## 2. Goals
+- Reduce time-to-first-successful SourceMonitor dashboard load (including background job + Action Cable verification) to under 15 minutes for both new and existing hosts.
+- Provide a single guided setup command (or task) that performs/coordinates all feasible installation steps while surfacing next actions inline.
+- Deliver updated documentation/checklists that stay in sync with the guided workflow and clearly call out remaining manual steps.
+- Ensure Solid Queue/Solid Cable (with optional Redis Action Cable fallback) are validated automatically before marking setup complete.
+- Instrument the workflow to capture pass/fail telemetry for each step (stored locally/logged) to aid support and future improvements.
+
+## 3. User Stories
+- **New Rails app maintainer:** “As a developer bootstrapping a fresh Rails 8.0.2.1+ app, I want a single command that adds SourceMonitor, runs the install generator, copies migrations, and verifies Solid Queue so I can start monitoring feeds without memorizing every prerequisite.”
+- **Existing app maintainer:** “As a developer integrating SourceMonitor into an established Rails codebase, I want the installer to detect what’s already configured (Devise, Solid Queue migrations, Action Cable adapter) and only prompt me for missing pieces.”
+- **Release engineer:** “As the person responsible for the release checklist, I want deterministic logs from the setup workflow so I can confirm every environment (staging, prod) passes the same validation steps.”
+
+## 4. Functional Requirements
+1. Provide a new CLI entry point (rails source_monitor:setup`) that orchestrates the onboarding steps end-to-end, supporting both fresh and existing hosts.
+2. The setup command must:
+   - Detect prerequisite versions (Ruby ≥ 3.4.4, Rails ≥ 8.0.2.1, PostgreSQL, Node ≥ 18) and halt with actionable remediation steps when mismatched.
+   - Offer to append the `source_monitor` gem declaration if missing, then run `bundle install` (respecting rbenv) with progress output.
+   - Run `npm install` only if the host manages node tooling and dependencies changed.
+   - Invoke `source_monitor:install` with a user-confirmed mount path (default `/source_monitor`) and confirm the engine route is reachable.
+   - Copy migrations via `railties:install:migrations FROM=source_monitor`, deduplicate Solid Queue tables if already present, and run `db:migrate`.
+   - Create/patch `config/initializers/source_monitor.rb` with sensible defaults plus TODO comments for any unresolved configuration (Mission Control, custom queues, etc.).
+   - Offer guided prompts (Y/N) for optional Devise wiring, with snippets inserted only when the host uses Devise (detected via Bundler).
+   - Verify Solid Queue worker availability by optionally starting a transient worker or pinging existing processes, logging failures with remediation.
+   - Verify Action Cable by ensuring either Solid Cable tables exist or Redis adapter credentials are configured; provide auto-detection and optional smoke ping.
+3. Emit a structured summary (JSON + human-readable table) at the end of the setup run showing which steps succeeded, which need manual follow-up, and links to docs.
+4. Create an updated checklist document (living under `docs/setup.md`) that mirrors the automated steps, clarifies manual-only tasks (e.g., navigation link updates, Mission Control wiring), and references the new command.
+5. Expose a reusable verification task (e.g., `rails source_monitor:verify_install`) that can be run in CI to confirm migrations, queues, and Action Cable remain healthy after upgrades.
+6. Ensure the workflow supports Solid Queue/Solid Cable by default and optionally configures Redis for Action Cable when the host opts in (prompt + adapter switch helper).
+7. Add minimal telemetry hooks (log lines or optional webhook) so support teams can request the last setup report when debugging customer installs.
+8. Provide sample scripts or templates for integrating a basic Devise-backed system test (sign-in + visit mount path) but mark it as optional to keep scope aligned with must-have validations (engine + background job success).
+9. Document how to roll back the setup (e.g., remove gem, initializer, route) to encourage experimentation without risk.
+
+## 5. Non-Goals (Out of Scope)
+- Supporting non-PostgreSQL databases or Rails versions below 8.0.2.1.
+- Full automation of Devise or other authentication stacks (provide guidance and optional snippets only).
+- Provisioning or managing Redis/Solid Queue infrastructure beyond verifying connectivity and migrations.
+- Replacing the existing CI pipeline; the focus is on installation workflow, not release automation.
+- Creating GUI installers or web-based setup wizards—command-line + documentation only.
+
+## 6. Design Considerations
+- Provide dry-run and verbose flags so advanced users can inspect actions without modifying their apps.
+- Structure setup steps as discrete service objects to enable reuse in future generators and tests.
+- Store mount path and adapter decisions in `config/source_monitor.yml` to keep the initializer tidy.
+- When Redis is selected for Action Cable, generate template credentials entries and highlight security requirements.
+
+## 7. Technical Considerations
+- Rails generators for CLI interactions to reuse existing generator patterns and support prompts.
+- Respect rbenv by invoking Ruby/Bundler via `ENV["RBENV_ROOT"]` shims (mirroring existing binstubs).
+- Ensure idempotency: rerunning the setup command should detect completed steps and skip or re-verify without breaking the app.
+- For migration deduplication, compare checksum filenames before copying to avoid duplicates in existing hosts.
+- Telemetry/logging should default to local file output (e.g., `log/source_monitor_setup.log`) with an opt-in environment variable for remote reporting.
+
+## 8. Success Metrics
+- ≥80% of beta users report completing setup in ≤15 minutes (collected via follow-up survey/logs).
+- Support tickets related to initial installation drop by 50% quarter-over-quarter.
+- Automated verification task adopted in CI for at least 3 internal environments within two weeks of release.
+- Zero critical setup regressions reported within the first month after launch (monitored via issue tracker).
+
+## 9. Open Questions
+- Should the setup command automatically create a nav link in host layouts, or simply print instructions?
+- How should we detect whether `npm install` is necessary in hosts that vend their own asset pipeline (e.g., Propshaft, esbuild)?
+- Do we need to version-gate the workflow for future Rails releases (8.1, 8.2), and how will we communicate incompatibilities?
+- Is telemetry opt-in per run (flag) or opt-out (environment variable)?