source_monitor 0.1.1

data/Gemfile.lock

@@ -0,0 +1,411 @@
+PATH
+  remote: .
+  specs:
+    source_monitor (0.1.1)
+      cssbundling-rails (~> 1.4)
+      faraday (~> 2.9)
+      faraday-follow_redirects (~> 0.4)
+      faraday-gzip (~> 3.0)
+      faraday-retry (~> 2.2)
+      feedjira (>= 3.2, < 5.0)
+      jsbundling-rails (~> 1.3)
+      nokolexbor (~> 0.5)
+      rails (>= 8.0.3, < 9.0)
+      ransack (~> 4.2)
+      ruby-readability (~> 0.7)
+      solid_cable (>= 3.0, < 4.0)
+      solid_queue (>= 0.3, < 3.0)
+      turbo-rails (~> 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    action_text-trix (2.1.15)
+      railties
+    actioncable (8.1.1)
+      actionpack (= 8.1.1)
+      activesupport (= 8.1.1)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+      zeitwerk (~> 2.6)
+    actionmailbox (8.1.1)
+      actionpack (= 8.1.1)
+      activejob (= 8.1.1)
+      activerecord (= 8.1.1)
+      activestorage (= 8.1.1)
+      activesupport (= 8.1.1)
+      mail (>= 2.8.0)
+    actionmailer (8.1.1)
+      actionpack (= 8.1.1)
+      actionview (= 8.1.1)
+      activejob (= 8.1.1)
+      activesupport (= 8.1.1)
+      mail (>= 2.8.0)
+      rails-dom-testing (~> 2.2)
+    actionpack (8.1.1)
+      actionview (= 8.1.1)
+      activesupport (= 8.1.1)
+      nokogiri (>= 1.8.5)
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+      useragent (~> 0.16)
+    actiontext (8.1.1)
+      action_text-trix (~> 2.1.15)
+      actionpack (= 8.1.1)
+      activerecord (= 8.1.1)
+      activestorage (= 8.1.1)
+      activesupport (= 8.1.1)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (8.1.1)
+      activesupport (= 8.1.1)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (8.1.1)
+      activesupport (= 8.1.1)
+      globalid (>= 0.3.6)
+    activemodel (8.1.1)
+      activesupport (= 8.1.1)
+    activerecord (8.1.1)
+      activemodel (= 8.1.1)
+      activesupport (= 8.1.1)
+      timeout (>= 0.4.0)
+    activestorage (8.1.1)
+      actionpack (= 8.1.1)
+      activejob (= 8.1.1)
+      activerecord (= 8.1.1)
+      activesupport (= 8.1.1)
+      marcel (~> 1.0)
+    activesupport (8.1.1)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (3.3.1)
+    brakeman (7.1.0)
+      racc
+    builder (3.3.0)
+    capybara (3.40.0)
+      addressable
+      matrix
+      mini_mime (>= 0.1.3)
+      nokogiri (~> 1.11)
+      rack (>= 1.6.0)
+      rack-test (>= 0.6.3)
+      regexp_parser (>= 1.5, < 3.0)
+      xpath (~> 3.2)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.5.4)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    crass (1.0.6)
+    cssbundling-rails (1.4.3)
+      railties (>= 6.0.0)
+    date (3.5.0)
+    docile (1.4.1)
+    drb (2.2.3)
+    erb (5.1.3)
+    erubi (1.13.1)
+    et-orbi (1.4.0)
+      tzinfo
+    faraday (2.14.0)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-follow_redirects (0.4.0)
+      faraday (>= 1, < 3)
+    faraday-gzip (3.0.4)
+      faraday (>= 2.0, < 3)
+      zlib (~> 3.0)
+    faraday-net_http (3.4.1)
+      net-http (>= 0.5.0)
+    faraday-retry (2.3.2)
+      faraday (~> 2.0)
+    feedjira (4.0.1)
+      logger (>= 1.0, < 2)
+      loofah (>= 2.3.1, < 3)
+      sax-machine (>= 1.0, < 2)
+    fugit (1.12.1)
+      et-orbi (~> 1.4)
+      raabro (~> 1.4)
+    globalid (1.3.0)
+      activesupport (>= 6.1)
+    guess_html_encoding (0.0.11)
+    hashdiff (1.2.1)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.1)
+    irb (1.15.3)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    jsbundling-rails (1.3.1)
+      railties (>= 6.0.0)
+    json (2.15.2)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    loofah (2.24.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.8.1)
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.1.0)
+    matrix (0.4.3)
+    mini_mime (1.1.5)
+    mini_portile2 (2.8.9)
+    minitest (5.26.0)
+    net-http (0.6.0)
+      uri
+    net-imap (0.5.12)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.1)
+      net-protocol
+    nio4r (2.7.4)
+    nokogiri (1.18.10)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
+    nokogiri (1.18.10-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.10-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.10-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.10-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.10-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.10-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.10-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.10-x86_64-linux-musl)
+      racc (~> 1.4)
+    nokolexbor (0.6.2)
+    nokolexbor (0.6.2-arm64-darwin)
+    nokolexbor (0.6.2-x86_64-darwin)
+    nokolexbor (0.6.2-x86_64-linux)
+    parallel (1.27.0)
+    parser (3.3.9.0)
+      ast (~> 2.4.1)
+      racc
+    pg (1.6.2)
+    pg (1.6.2-aarch64-linux)
+    pg (1.6.2-aarch64-linux-musl)
+    pg (1.6.2-arm64-darwin)
+    pg (1.6.2-x86_64-darwin)
+    pg (1.6.2-x86_64-linux)
+    pg (1.6.2-x86_64-linux-musl)
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.5.1)
+    propshaft (1.3.1)
+      actionpack (>= 7.0.0)
+      activesupport (>= 7.0.0)
+      rack
+    psych (5.2.6)
+      date
+      stringio
+    public_suffix (6.0.2)
+    puma (7.1.0)
+      nio4r (~> 2.0)
+    raabro (1.4.0)
+    racc (1.8.1)
+    rack (3.2.4)
+    rack-session (2.1.1)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.2.1)
+      rack (>= 3)
+    rails (8.1.1)
+      actioncable (= 8.1.1)
+      actionmailbox (= 8.1.1)
+      actionmailer (= 8.1.1)
+      actionpack (= 8.1.1)
+      actiontext (= 8.1.1)
+      actionview (= 8.1.1)
+      activejob (= 8.1.1)
+      activemodel (= 8.1.1)
+      activerecord (= 8.1.1)
+      activestorage (= 8.1.1)
+      activesupport (= 8.1.1)
+      bundler (>= 1.15.0)
+      railties (= 8.1.1)
+    rails-dom-testing (2.3.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.6.2)
+      loofah (~> 2.21)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (8.1.1)
+      actionpack (= 8.1.1)
+      activesupport (= 8.1.1)
+      irb (~> 1.13)
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      tsort (>= 0.2)
+      zeitwerk (~> 2.6)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    ransack (4.4.1)
+      activerecord (>= 7.2)
+      activesupport (>= 7.2)
+      i18n
+    rdoc (6.15.1)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    regexp_parser (2.11.3)
+    reline (0.6.2)
+      io-console (~> 0.5)
+    rexml (3.4.4)
+    rubocop (1.81.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.47.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-performance (1.26.0)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
+    rubocop-rails (2.33.4)
+      activesupport (>= 4.2.0)
+      lint_roller (~> 1.1)
+      rack (>= 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
+    rubocop-rails-omakase (1.1.0)
+      rubocop (>= 1.72)
+      rubocop-performance (>= 1.24)
+      rubocop-rails (>= 2.30)
+    ruby-progressbar (1.13.0)
+    ruby-readability (0.7.2)
+      guess_html_encoding (>= 0.0.4)
+      nokogiri (>= 1.6.0)
+    rubyzip (3.2.2)
+    sax-machine (1.3.2)
+    securerandom (0.4.1)
+    selenium-webdriver (4.38.0)
+      base64 (~> 0.2)
+      logger (~> 1.4)
+      rexml (~> 3.2, >= 3.2.5)
+      rubyzip (>= 1.2.2, < 4.0)
+      websocket (~> 1.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    solid_cable (3.0.12)
+      actioncable (>= 7.2)
+      activejob (>= 7.2)
+      activerecord (>= 7.2)
+      railties (>= 7.2)
+    solid_queue (1.2.4)
+      activejob (>= 7.1)
+      activerecord (>= 7.1)
+      concurrent-ruby (>= 1.3.1)
+      fugit (~> 1.11)
+      railties (>= 7.1)
+      thor (>= 1.3.1)
+    stackprof (0.2.27)
+    stringio (3.1.7)
+    test-prof (1.4.4)
+    thor (1.4.0)
+    timeout (0.4.4)
+    tsort (0.2.0)
+    turbo-rails (2.0.20)
+      actionpack (>= 7.1.0)
+      railties (>= 7.1.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
+    uri (1.1.0)
+    useragent (0.16.11)
+    vcr (6.3.1)
+      base64
+    webmock (3.26.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    websocket (1.2.11)
+    websocket-driver (0.8.0)
+      base64
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    xpath (3.2.0)
+      nokogiri (~> 1.8)
+    zeitwerk (2.7.3)
+    zlib (3.2.1)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  ruby
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  brakeman
+  capybara
+  pg
+  propshaft
+  puma
+  rubocop-rails-omakase
+  selenium-webdriver
+  simplecov
+  source_monitor!
+  stackprof
+  test-prof
+  vcr
+  webmock
+
+BUNDLED WITH
+   2.7.2

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright dchuk
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,108 @@
+# SourceMonitor
+
+SourceMonitor is a production-ready Rails 8 mountable engine for ingesting, normalising, scraping, and monitoring RSS/Atom/JSON feeds. It ships with a Tailwind-powered admin UI, Solid Queue job orchestration, Solid Cable realtime broadcasting, and an extensible configuration layer so host applications can offer full-stack feed operations without rebuilding infrastructure.
+
+## Highlights
+- Full-featured source and item administration backed by Turbo Streams and Tailwind UI components
+- Adaptive fetch pipeline (Feedjira + Faraday) with conditional GETs, retention pruning, and scrape orchestration
+- Realtime dashboard metrics, batching/caching query layer, and Mission Control integration hooks
+- Extensible scraper adapters (Readability included) with per-source settings and structured result metadata
+- Declarative configuration DSL covering queues, HTTP, retention, events, model extensions, authentication, and realtime transports
+- First-class observability through ActiveSupport notifications and `SourceMonitor::Metrics` counters/gauges
+
+## Requirements
+- Ruby 3.4.4 (we recommend [rbenv](https://github.com/rbenv/rbenv) for local development: `rbenv install 3.4.4 && rbenv local 3.4.4`, but use whatever Ruby version manager suits your environment—asdf, chruby, rvm, or container-based workflows all work fine)
+- Rails ≥ 8.0.2.1 in the host application
+- PostgreSQL 13+ (engine migrations use JSONB, SKIP LOCKED, advisory locks, and Solid Cable tables)
+- Node.js 18+ (npm or Yarn) for asset linting and the Tailwind/esbuild bundling pipeline
+- Solid Queue workers (Rails 8 default) and Solid Cable (default realtime adapter)
+- Optional: Mission Control Jobs for dashboard linking, Redis if you opt into the Redis realtime adapter
+
+## Quick Start (Host Application)
+
+> **Note on commands:** The examples below use bare `bundle` and `bin/rails` commands. If you use rbenv, prefix them with `rbenv exec` (e.g., `rbenv exec bundle install`). For Docker/container environments, run commands directly or via your container runtime. Adjust to match your Ruby version management approach.
+
+### Initial Install
+1. Add `gem "source_monitor", github: "dchuk/source_monitor"` to your Gemfile and run `bundle install`.
+2. Install the engine: `bin/rails generate source_monitor:install --mount-path=/source_monitor` (updates routes, drops the initializer, prints doc links).
+3. Copy migrations: `bin/rails railties:install:migrations FROM=source_monitor`.
+4. Apply migrations: `bin/rails db:migrate` (creates sources/items/logs tables, Solid Cable messages, and Solid Queue schema when required).
+5. Install frontend tooling if you plan to extend engine assets: `npm install`.
+6. Start background workers: `bin/rails solid_queue:start` (or your preferred process manager).
+7. Boot your app and visit the mount path you chose (default `/source_monitor`) to explore the dashboard and confirm Solid Queue metrics render.
+
+Detailed instructions, optional flags, and verification steps live in [docs/installation.md](docs/installation.md), with troubleshooting advice in [docs/troubleshooting.md](docs/troubleshooting.md).
+
+### Upgrading SourceMonitor
+1. Bump the gem version in your host `Gemfile` and run `bundle install` (or `bundle update source_monitor` when targeting a specific release).
+2. Re-run `bin/rails railties:install:migrations FROM=source_monitor` and then `bin/rails db:migrate` to pick up schema changes.
+3. Compare your `config/initializers/source_monitor.rb` against the newly generated template for configuration diffs (new queue knobs, HTTP options, etc.).
+4. Review release notes for optional integrations—when enabling Mission Control, ensure `mission_control-jobs` stays mounted and linked via `config.mission_control_dashboard_path`.
+5. Smoke test Solid Queue workers, Action Cable, and admin UI flows after the upgrade.
+
+## Example Applications
+- `examples/basic_host/template.rb` – Minimal host that seeds a Rails blog source and redirects `/` to the dashboard.
+- `examples/advanced_host/template.rb` – Production-style integration with Mission Control, Redis realtime, Solid Queue tuning, and metrics endpoint.
+- `examples/custom_adapter/template.rb` – Registers the sample Markdown scraper adapter and seeds a Markdown-based source.
+- `examples/docker` – Dockerfile, Compose stack, and entrypoint script that run any generated example alongside Postgres and Redis.
+
+See [examples/README.md](examples/README.md) for usage instructions.
+
+## Architecture at a Glance
+- **Source Lifecycle** – `SourceMonitor::Fetching::FetchRunner` coordinates advisory locking, fetch execution, retention pruning, and scrape enqueues. Source models store health metrics, failure states, and adaptive scheduling parameters.
+- **Item Processing** – `SourceMonitor::Items::RetentionPruner`, `SourceMonitor::Scraping::Enqueuer`, and `SourceMonitor::Scraping::ItemScraper` keep content fresh, ensure deduplicated storage, and capture scrape metadata/logs.
+- **Scraping Pipeline** – Adapters inherit from `SourceMonitor::Scrapers::Base`, merging default + source + invocation settings and returning structured results. The bundled Readability adapter composes `SourceMonitor::Scrapers::Fetchers::HttpFetcher` and `SourceMonitor::Scrapers::Parsers::ReadabilityParser`.
+- **Realtime Dashboard** – `SourceMonitor::Dashboard::Queries` batches SQL, caches per-request responses, emits instrumentation (`source_monitor.dashboard.*`), and coordinates Turbo broadcasts via Solid Cable.
+- **Observability** – `SourceMonitor::Metrics` tracks counters/gauges for fetches, scheduler runs, and dashboard activity. ActiveSupport notifications (`source_monitor.fetch.*`, `source_monitor.scheduler.run`, etc.) let you instrument external systems without monkey patches.
+- **Extensibility** – `SourceMonitor.configure` exposes namespaces for queue tuning, HTTP defaults, scraper registry, retention, event callbacks, model extensions, authentication hooks, realtime transports, health thresholds, and job metrics.
+
+## Admin Experience
+- Dashboard cards summarising source counts, recent activity, queue visibility, and upcoming fetch schedules
+- Source CRUD with scraping toggles, adaptive fetch controls, manual fetch triggers, and detailed fetch log timelines
+- Item explorer showing feed vs scraped content, scrape status badges, and manual scrape actions via Turbo
+- Fetch/scrape log viewers with HTTP status, duration, backtrace, and Solid Queue job references
+
+## Background Jobs & Scheduling
+- Solid Queue becomes the Active Job adapter when the host app still uses the inline `:async` adapter; queue names default to `source_monitor_fetch` and `source_monitor_scrape` and honour `ActiveJob.queue_name_prefix`.
+- `config/recurring.yml` schedules minute-level fetches and scrapes. Run `bin/jobs --recurring_schedule_file=config/recurring.yml` (or set `SOLID_QUEUE_RECURRING_SCHEDULE_FILE`) to load recurring tasks. Disable with `SOLID_QUEUE_SKIP_RECURRING=true`.
+- Retry/backoff behaviour is driven by `SourceMonitor.configure.fetching`. Fetch completion events and item processors allow you to chain downstream workflows (indexing, notifications, etc.).
+
+## Configuration & API Surface
+The generated initializer documents every setting. Key areas:
+
+- Queue namespace/concurrency helpers (`SourceMonitor.queue_name(:fetch)`)
+- HTTP, retry, and proxy settings (Faraday-backed)
+- Scraper registry (`config.scrapers.register(:my_adapter, "MyApp::Scrapers::Custom")`)
+- Retention defaults (`config.retention.items_retention_days`, `config.retention.strategy`)
+- Lifecycle hooks (`config.events.after_item_created`, `config.events.register_item_processor`)
+- Model extensions (table prefixes, included concerns, custom validations)
+- Realtime adapter selection (`config.realtime.adapter = :solid_cable | :redis | :async`)
+- Authentication helpers (`config.authentication.authenticate_with`, `authorize_with`, etc.)
+- Mission Control toggles (`config.mission_control_enabled`, `config.mission_control_dashboard_path`)
+- Health thresholds driving automatic pause/resume
+
+See [docs/configuration.md](docs/configuration.md) for exhaustive coverage and examples.
+
+## Deployment Considerations
+- Copy engine migrations before every deploy and run `bin/rails db:migrate`.
+- Precompile assets so SourceMonitor's bundled CSS/JS outputs are available at runtime.
+- Run dedicated Solid Queue worker processes; consider a separate scheduler process for recurring jobs.
+- Configure Action Cable (Solid Cable by default) and expose `/cable` through your load balancer.
+- Monitor gauges/counters emitted by `SourceMonitor::Metrics` and subscribe to notifications for alerting.
+
+More production guidance, including process topology and scaling tips, is available in [docs/deployment.md](docs/deployment.md).
+
+## Troubleshooting & Support
+Common installation and runtime issues (missing migrations, realtime not streaming, scraping failures, queue visibility gaps) are documented in [docs/troubleshooting.md](docs/troubleshooting.md). When you report bugs, include your `SourceMonitor::VERSION`, Rails version, configuration snippet, and relevant fetch/scrape logs so we can reproduce quickly.
+
+## Development & Testing (Engine Repository)
+- Install dependencies with `bundle install` and `npm install` (prefix with `rbenv exec` if using rbenv).
+- Use `test/dummy/bin/dev` to boot the dummy app with npm CSS/JS watchers, Solid Queue worker, and Rails server.
+- Run tests via `bin/test-coverage` (SimpleCov-enforced), `bundle exec rake app:test:smoke` for the fast subset, or `bin/rails test` for targeted suites.
+- Quality checks: `bin/rubocop`, `bin/brakeman --no-pager`, `bin/lint-assets`.
+- Record HTTP fixtures with VCR under `test/vcr_cassettes/` and keep coverage ≥ 90% for new code.
+
+Contributions follow the clean architecture and TDD guidelines in `.ai/project_overview.md`. Review `.ai/tasks.md` to align with the active roadmap slice before opening a pull request.
+
+## License
+SourceMonitor is released under the [MIT License](MIT-LICENSE).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/assets/config/source_monitor_manifest.js

@@ -0,0 +1,4 @@
+//= link_tree ../builds/source_monitor .css
+//= link_tree ../builds/source_monitor .js
+//= link_tree ../images/source_monitor
+//= link_tree ../svgs/source_monitor

data/app/assets/javascripts/source_monitor/application.js

@@ -0,0 +1,20 @@
+import { Application } from "@hotwired/stimulus";
+import AsyncSubmitController from "./controllers/async_submit_controller";
+import NotificationController from "./controllers/notification_controller";
+import DropdownController from "./controllers/dropdown_controller";
+import ModalController from "./controllers/modal_controller";
+import "./turbo_actions";
+
+const existingApplication = window.SourceMonitorStimulus;
+const application = existingApplication || Application.start();
+
+if (!existingApplication) {
+  window.SourceMonitorStimulus = application;
+}
+
+application.register("notification", NotificationController);
+application.register("async-submit", AsyncSubmitController);
+application.register("dropdown", DropdownController);
+application.register("modal", ModalController);
+
+export default application;

data/app/assets/javascripts/source_monitor/controllers/async_submit_controller.js

@@ -0,0 +1,36 @@
+import { Controller } from "@hotwired/stimulus";
+
+export default class extends Controller {
+  static targets = ["button"];
+  static values = { loadingText: String };
+
+  connect() {
+    if (this.hasButtonTarget) {
+      this.defaultText = this.buttonTarget.textContent;
+    }
+  }
+
+  start() {
+    if (!this.hasButtonTarget) return;
+
+    const button = this.buttonTarget;
+    button.disabled = true;
+    button.dataset.originalText = this.defaultText || button.textContent;
+    if (this.hasLoadingTextValue && this.loadingTextValue) {
+      button.textContent = this.loadingTextValue;
+    }
+    button.classList.add("opacity-75", "pointer-events-none");
+  }
+
+  finish() {
+    if (!this.hasButtonTarget) return;
+
+    const button = this.buttonTarget;
+    button.disabled = false;
+    button.classList.remove("opacity-75", "pointer-events-none");
+    const original = button.dataset.originalText;
+    if (original) {
+      button.textContent = original;
+    }
+  }
+}