source_monitor 0.12.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cb1aa0acdd0eddd3b7b6a51e4e57861420a37e99398440f990cda73ee87b900
-  data.tar.gz: 916c1d6d11edd1b41422405c91b5b36100622f0c0b512ed6c7aa660a0625327e
+  metadata.gz: d460ce01dd1453813fe455bde15c1b8fc2eb6954ca20ff4bf7599b55480c98d5
+  data.tar.gz: 16e5903aa483ba06cc092b08a8148edc3050a3830cd4dda42abfbca3d1cab25f
 SHA512:
-  metadata.gz: e96387f3a085b20a56b9e97b97b4f0321737dd4f1ad046f364c7bd777f8d7cdf8bf30591a81db24c4ed7fba38742f80c97e3d31e9f794a2a18741dca568c7dee
-  data.tar.gz: 6672afcc7ac248c75520c638099b0a0dce8fe5e3a6e49621587de3d090a2fde15d88b57fb801d4eb9fe294366a7688a9d0ce0d45045f6e2860d6435e68a03e93
+  metadata.gz: 20a4b8a80f4a861d8ea7e543e4cd90e31709bf9a4d504cf40059375fa439f5d5dd3803bb6ad133d50c75dfe50ee42cfd0913cae66ea41422df1473710493bb5c
+  data.tar.gz: ae82ac7575c31e93839bbe48c309a71f57cc1ac91ecd67a4f7690d978be459459abcdafb554fad36e98ff0cdcc424133f6a77f4f756fdfbaf6e11b22c8c9ce27

data/.claude/commands/release.md

@@ -26,7 +26,8 @@ These are real issues encountered in previous releases. Each step below accounts
 9. **ESLint browser globals**: Any JS file using browser APIs (MutationObserver, requestAnimationFrame, cancelAnimationFrame, IntersectionObserver, etc.) MUST declare them with a `/* global ... */` comment at the top. ESLint's `no-undef` rule in CI will reject them otherwise.
 10. **Diff coverage rescue paths**: Every `rescue`/fallback/error handling branch in changed source code needs test coverage. Common blind spots: `rescue StandardError => e` logging, `rescue URI::InvalidURIError` returning nil, fallback `false` returns. Write targeted tests for these BEFORE creating the release commit.
 11. **Zsh glob nomatch**: Commands like `rm -f *.gem` fail in zsh when no files match. Always use `rm -f *.gem 2>/dev/null || true` or check existence first with `ls`.
-12. **Documentation drift**: Features, config options, and behavioral changes often land across milestone work without corresponding doc updates. The Documentation Audit step (Step 4) catches this -- check `docs/`, `README.md`, skill reference files (`sm-*/reference/`), and the initializer template against the actual source code. In v0.9.x, 14 files needed updates that would have been missed without this step.
+12. **Documentation drift**: Features, config options, and behavioral changes often land across milestone work without corresponding doc updates. Step 4 now spawns agents to both audit AND fix all stale docs automatically. In v0.9.x, 14 files needed updates; in v0.12.0, 7 files were stale (README version refs, docs/setup version refs, docs/upgrade missing section, 4 skill references). Always assume docs are stale.
+13. **test-coverage script health_suite**: The `bin/test-coverage` script runs a second "health_suite" pass with specific test files. If you add new test files for health/service classes, you MUST add them to the `TARGETED_TESTS` array in `bin/test-coverage` or SimpleCov's merged report will show 0% coverage for those files even though the main suite covers them. In v0.12.0, `source_health_check_orchestrator_test.rb` showed 31% coverage on CI despite 100% locally because it wasn't in the health_suite list.
 
 ## Step 1: Git Hygiene
 
@@ -114,54 +115,76 @@ The changelog follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) f
    - Insert the new versioned entry immediately after the `## [Unreleased]` block and before the previous release entry.
    - Preserve all existing entries below.
 
-## Step 4: Documentation Audit
+## Step 4: Documentation Update (Mandatory)
 
-Verify that all project documentation reflects the current state of the codebase. Changes made since the last release (or during milestone work) may have introduced features, configuration options, bug fixes, or behavioral changes that need to be documented.
+**This step is NON-OPTIONAL.** Every release MUST update all documentation to reflect the current codebase state. Documentation drift is the #1 blind spot in milestone-based work — in v0.9.x, 14 files needed updates; in v0.12.0, 7 files were stale. Always assume docs are stale and verify.
 
-1. **Gather what changed** since the last release tag:
-   ```
-   git diff vPREVIOUS..HEAD --name-only -- lib/ app/ config/
-   ```
-   This shows which source files changed. Use this to identify features/fixes that may need documentation.
-
-2. **Check these documentation files against the changes:**
-
-   | File | What to verify |
-   |------|---------------|
-   | `CHANGELOG.md` | Has an `[Unreleased]` or versioned entry covering all user-facing changes |
-   | `README.md` | Version references match, feature descriptions current, gem version in install instructions |
-   | `docs/configuration.md` | All config options documented, new settings included, env vars listed |
-   | `docs/deployment.md` | Worker/queue descriptions match current queues and job assignments |
-   | `docs/troubleshooting.md` | Covers known failure modes from recent changes |
-   | `docs/upgrade.md` | Has upgrade section for this version with action items |
-   | `docs/setup.md` | Setup steps still accurate |
-
-3. **Check skills reference files** (engine-specific documentation for Claude Code):
-
-   | Skill Reference | What to verify |
-   |----------------|---------------|
-   | `sm-configure/reference/configuration-reference.md` | All config settings and their defaults |
-   | `sm-configuration-setting/reference/settings-catalog.md` | Settings catalog with types, defaults, descriptions |
-   | `sm-job/reference/job-conventions.md` | Queue names, job assignments, concurrency defaults |
-   | `sm-pipeline-stage/reference/completion-handlers.md` | Pipeline handler code matches actual implementation |
-   | `sm-upgrade/reference/version-history.md` | Version transition notes for the new release |
-   | `sm-host-setup/reference/initializer-template.md` | Initializer template shows all configurable options |
-
-4. **For each file that is stale or missing coverage**:
-   - Update it to reflect the current codebase behavior.
-   - For config docs: read the actual settings classes in `lib/source_monitor/configuration/` to verify defaults.
-   - For job docs: read `app/jobs/source_monitor/` to verify queue assignments.
-   - For upgrade notes: summarize breaking changes, new config, and action items.
-
-5. **If all documentation is already up to date**, report:
-   ```
-   Documentation Audit: All files current. No updates needed.
-   ```
-   If updates were made, report:
-   ```
-   Documentation Audit: Updated N files.
-     - <file>: <what was updated>
-   ```
+### 4a. Gather what changed
+
+```
+git log vPREVIOUS..HEAD --oneline --no-merges
+git diff vPREVIOUS..HEAD --name-only -- lib/ app/ config/
+```
+
+Summarize the key changes: new classes, extracted services, new components, new model methods, new migrations, config changes, breaking changes.
+
+### 4b. Spawn Explore agent to audit all docs
+
+Spawn an Explore agent (subagent_type: "Explore", thoroughness: "very thorough") to compare documentation against the actual source code. The agent MUST check ALL of these files:
+
+**Project docs:**
+
+| File | What to verify |
+|------|---------------|
+| `README.md` | Version references match new version, feature descriptions current, install instructions accurate |
+| `docs/setup.md` | Version references match, setup steps accurate |
+| `docs/upgrade.md` | Has upgrade section for THIS version with migrations, action items, breaking changes |
+| `docs/configuration.md` | All config options documented, defaults match source code |
+| `docs/deployment.md` | Worker/queue descriptions match current queues and job assignments |
+| `docs/troubleshooting.md` | Covers known failure modes from recent changes |
+
+**Skills reference files** (engine-specific documentation for Claude Code):
+
+| Skill Reference | What to verify |
+|----------------|---------------|
+| `sm-configure/reference/configuration-reference.md` | All config settings and their defaults |
+| `sm-configuration-setting/reference/settings-catalog.md` | Settings catalog with types, defaults, descriptions |
+| `sm-job/reference/job-conventions.md` | Queue names, job assignments, concurrency defaults, service class delegation |
+| `sm-pipeline-stage/reference/completion-handlers.md` | Pipeline handler code matches actual implementation |
+| `sm-upgrade/reference/version-history.md` | Version transition notes for the new release |
+| `sm-host-setup/reference/initializer-template.md` | Initializer template shows all configurable options |
+| `sm-architecture/reference/module-map.md` | All modules, classes, components, presenters listed |
+| `sm-domain-model/reference/model-graph.md` | All model methods, validations, scopes, associations |
+
+The Explore agent should output a structured report: files that are current, files that need updates (with specific stale content), and what each update should contain.
+
+### 4c. Spawn Docs agent to fix all stale files
+
+Based on the Explore agent's report, spawn a Docs agent (subagent_type: "vbw:vbw-docs", model: "sonnet") to update ALL stale files. The Docs agent MUST:
+
+- Read each file before editing (targeted edits, not full rewrites)
+- Update version references to the new release version
+- Add upgrade section for this version (migrations, action items, breaking changes)
+- Update module maps, model graphs, job conventions to reflect current source code
+- Add entries for any new classes, components, concerns, or model methods
+
+### 4d. Verify and report
+
+After the Docs agent completes, verify all files were updated:
+```
+git diff --name-only  # Should show the updated doc files
+```
+
+Report:
+```
+Documentation Update: Updated N files.
+  - <file>: <what was updated>
+```
+
+If the Explore agent found 0 stale files, report:
+```
+Documentation Update: All files current. No updates needed.
+```
 
 Do NOT commit documentation updates separately -- they will be included in the single release commit in Step 7.
 

data/.claude/skills/sm-architecture/reference/module-map.md

@@ -79,6 +79,7 @@ Complete module tree with each module's responsibility.
 |--------|------|----------------|
 | `EntryNormalizer` | `import_sessions/entry_normalizer.rb` | Normalize OPML entries to standard format |
 | `HealthCheckBroadcaster` | `import_sessions/health_check_broadcaster.rb` | Broadcast health check progress via Turbo Streams |
+| `HealthCheckUpdater` | `import_sessions/health_check_updater.rb` | Service delegated to by ImportSessionHealthCheckJob; runs checks and broadcasts |
 
 ### Jobs
 
@@ -104,6 +105,7 @@ Complete module tree with each module's responsibility.
 |--------|------|----------------|
 | `Sanitizable` | `models/sanitizable.rb` | `sanitizes_string_attributes`, `sanitizes_hash_attributes` class methods |
 | `UrlNormalizable` | `models/url_normalizable.rb` | `normalizes_urls`, `validates_url_format` class methods |
+| `SetSource` | `models/set_source.rb` | Controller concern: resolves and assigns `@source` from params before actions |
 
 ### Scrapers (Scraper Adapters)
 
@@ -123,6 +125,7 @@ Complete module tree with each module's responsibility.
 | `ItemScraper` | `scraping/item_scraper.rb` | Scrape a single item |
 | `ItemScraper::AdapterResolver` | `scraping/item_scraper/adapter_resolver.rb` | Select scraper adapter for a source |
 | `ItemScraper::Persistence` | `scraping/item_scraper/persistence.rb` | Save scrape results to ItemContent |
+| `Runner` | `scraping/runner.rb` | Service delegated to by ScrapeItemJob; orchestrates state, scraping, and logging |
 | `BulkSourceScraper` | `scraping/bulk_source_scraper.rb` | Scrape all pending items for a source |
 | `BulkResultPresenter` | `scraping/bulk_result_presenter.rb` | Format bulk scrape results |
 | `State` | `scraping/state.rb` | Track scraping state per source |
@@ -150,6 +153,7 @@ Complete module tree with each module's responsibility.
 |--------|------|----------------|
 | `SourceHealthMonitor` | `health/source_health_monitor.rb` | Calculate rolling success rate, update health_status |
 | `SourceHealthCheck` | `health/source_health_check.rb` | Perform HTTP health check on a source |
+| `SourceHealthCheckOrchestrator` | `health/source_health_check_orchestrator.rb` | Service delegated to by SourceHealthCheckJob; coordinates check, logging, and broadcasting |
 | `SourceHealthReset` | `health/source_health_reset.rb` | Reset health state for a source |
 | `ImportSourceHealthCheck` | `health/import_source_health_check.rb` | Health check for import session sources |
 
@@ -182,6 +186,34 @@ Complete module tree with each module's responsibility.
 | `Verification::ActionCableVerifier` | `setup/verification/action_cable_verifier.rb` | Verify Action Cable setup |
 | `Verification::TelemetryLogger` | `setup/verification/telemetry_logger.rb` | Log setup telemetry |
 
+### Favicons
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `Favicons::Discoverer` | `favicons/discoverer.rb` | Multi-strategy favicon discovery (direct, HTML parsing, Google API) |
+| `Favicons::Fetcher` | `favicons/fetcher.rb` | Service delegated to by FaviconFetchJob; guards, discovers, and attaches favicon |
+
+### Images
+
+| Module | File | Responsibility |
+|--------|------|----------------|
+| `Images::Processor` | `images/processor.rb` | Service delegated to by DownloadContentImagesJob; downloads and attaches content images via Active Storage |
+
+### ViewComponents
+
+| Component | File | Responsibility |
+|-----------|------|----------------|
+| `StatusBadgeComponent` | `app/components/source_monitor/status_badge_component.rb` | Renders a colored status badge for health_status values |
+| `IconComponent` | `app/components/source_monitor/icon_component.rb` | Renders consistent inline SVG or CSS icons |
+| `FilterDropdownComponent` | `app/components/source_monitor/filter_dropdown_component.rb` | Renders filter dropdown menus for sources/items index |
+
+### Presenters
+
+| Presenter | File | Responsibility |
+|-----------|------|----------------|
+| `SourceDetailsPresenter` | `app/presenters/source_monitor/source_details_presenter.rb` | View-specific formatting for source detail pages (SimpleDelegator over Source) |
+| `SourcesFilterPresenter` | `app/presenters/source_monitor/sources_filter_presenter.rb` | Formats filter state and option lists for the sources index |
+
 ### Other
 
 | Module | File | Responsibility |

data/.claude/skills/sm-domain-model/reference/model-graph.md

@@ -112,4 +112,45 @@ Source has a `type` column for potential STI subclassing but it is not actively
 |--------|--------|-------|-------|
 | Source | `items_count` | Item | Only counts active (non-deleted) items |
 
-The counter is decremented manually during `soft_delete!` and can be recalculated via `reset_items_counter!`.
+The counter is decremented manually during `soft_delete!` and **incremented** during `restore!`. Both operations update `items_count` atomically. Use `reset_items_counter!` to recalculate from scratch if the counter drifts.
+
+## Model Methods (v0.12.0+)
+
+### Source.enable_scraping!(ids)
+
+Bulk-enables scraping for a list of source IDs:
+
+```ruby
+Source.enable_scraping!([1, 2, 3])
+# Sets scraping_enabled = true for each source in the list
+```
+
+Use case: enabling scraping on a filtered set of sources from the dashboard or a rake task.
+
+### Item#restore!
+
+Reverses a soft delete. Symmetric counterpart to `soft_delete!`:
+
+```ruby
+item.restore!
+# Clears deleted_at, increments source.items_count
+```
+
+After `restore!`, the item re-enters the `:items` (active) association and the source counter cache reflects the change.
+
+### health_status Validation
+
+As of v0.12.0, `health_status` is validated against the four permitted values. Assigning an unrecognized value raises a validation error:
+
+```ruby
+source.health_status = "healthy"  # invalid -- was removed in 0.11.0
+source.valid?                      # => false
+source.errors[:health_status]      # => ["is not included in the list"]
+```
+
+Permitted values: `"working"`, `"declining"`, `"improving"`, `"failing"`.
+
+## Schema Notes (v0.12.0)
+
+- **Composite indexes on log tables:** `sourcemon_fetch_logs`, `sourcemon_scrape_logs`, and `sourcemon_health_check_logs` now have composite indexes on `(source_id, created_at)` to improve log query performance on busy sources.
+- **health_status default alignment:** The `health_status` column default on `sourcemon_sources` was updated to `"working"` (previously `"healthy"`, a removed value) to match the four-value enum added in v0.11.0.

data/.claude/skills/sm-job/reference/job-conventions.md

@@ -113,7 +113,7 @@ Notable patterns:
 
 ### Worker Job (ScrapeItemJob)
 
-Demonstrates lifecycle logging:
+Demonstrates shallow delegation to a service class:
 
 ```ruby
 class ScrapeItemJob < ApplicationJob
@@ -121,35 +121,18 @@ class ScrapeItemJob < ApplicationJob
   discard_on ActiveJob::DeserializationError
 
   def perform(item_id)
-    log("job:start", item_id: item_id)
     item = Item.includes(:source).find_by(id: item_id)
     return unless item
 
-    source = item.source
-    unless source&.scraping_enabled?
-      log("job:skipped_scraping_disabled", item: item)
-      Scraping::State.clear_inflight!(item)
-      return
-    end
-
-    Scraping::State.mark_processing!(item)
-    Scraping::ItemScraper.new(item:, source:).call
-    log("job:completed", item: item, status: item.scrape_status)
-  rescue StandardError => error
-    log("job:error", item: item, error: error.message)
-    Scraping::State.mark_failed!(item)
-    raise
-  ensure
-    Scraping::State.clear_inflight!(item) if item
+    Scraping::Runner.new(item: item).call
   end
 end
 ```
 
 Notable patterns:
-- `includes(:source)` prevents N+1 query
-- Lifecycle state management (`mark_processing!`, `clear_inflight!`)
-- Error re-raise after state cleanup
-- Structured JSON logging at each stage
+- Job body is deserialization + delegation only
+- All business logic (state management, scraping, logging) lives in `Scraping::Runner`
+- `includes(:source)` prevents N+1 query before handing off to the service
 
 ### Scheduling Job (ScheduleFetchesJob)
 
@@ -168,7 +151,7 @@ end
 
 ### Lightweight Fetch Job (FaviconFetchJob)
 
-Demonstrates multi-strategy cascade with guard clauses:
+Demonstrates shallow delegation with guard clause:
 
 ```ruby
 class FaviconFetchJob < ApplicationJob
@@ -178,23 +161,19 @@ class FaviconFetchJob < ApplicationJob
   def perform(source_id)
     source = Source.find_by(id: source_id)
     return unless source
-    return unless should_fetch?(source)
 
-    result = Favicons::Discoverer.new(source: source).call
-    attach_favicon(source, result) if result.success?
+    Favicons::Fetcher.new(source: source).call
   end
 end
 ```
 
 Notable patterns:
-- Multiple guard clauses: source exists, Active Storage defined, no existing favicon, outside cooldown period
-- Uses `Favicons::Discoverer` service with 3-strategy cascade (direct `/favicon.ico`, HTML parsing, Google API)
-- Failed attempts tracked in source `metadata` JSONB (`favicon_last_attempted_at`) for retry cooldown
+- Job contains only lookup + delegation — guard clauses and discovery strategy cascade live in `Favicons::Fetcher`
 - Graceful degradation: host apps without Active Storage never enqueue this job
 
 ### Broadcast Job (SourceHealthCheckJob)
 
-Demonstrates result broadcasting:
+Demonstrates shallow delegation with result broadcasting:
 
 ```ruby
 class SourceHealthCheckJob < ApplicationJob
@@ -205,21 +184,48 @@ class SourceHealthCheckJob < ApplicationJob
     source = Source.find_by(id: source_id)
     return unless source
 
-    result = Health::SourceHealthCheck.new(source: source).call
-    broadcast_outcome(source, result)
-    result
-  rescue StandardError => error
-    record_unexpected_failure(source, error) if source
-    broadcast_outcome(source, nil, error) if source
-    nil
+    Health::SourceHealthCheckOrchestrator.new(source: source).call
   end
 end
 ```
 
 Notable patterns:
-- Always broadcasts UI update (success or failure)
-- Creates log record even for unexpected failures
-- Returns nil on error instead of re-raising (health checks are non-critical)
+- Job body is lookup + delegation only
+- Broadcasting, logging, and error handling live in `Health::SourceHealthCheckOrchestrator`
+- Returns nil on missing source; orchestrator handles nil-on-error (health checks are non-critical)
+
+## Shallow Delegation Pattern
+
+As of v0.12.0, five maintenance jobs delegate entirely to dedicated service classes. Jobs contain only deserialization and delegation — no business logic.
+
+| Job | Service Class |
+|-----|---------------|
+| `ScrapeItemJob` | `Scraping::Runner` |
+| `DownloadContentImagesJob` | `Images::Processor` |
+| `FaviconFetchJob` | `Favicons::Fetcher` |
+| `SourceHealthCheckJob` | `Health::SourceHealthCheckOrchestrator` |
+| `ImportSessionHealthCheckJob` | `ImportSessions::HealthCheckUpdater` |
+
+**Why this pattern:**
+- Jobs are the transport mechanism, not the behavior container.
+- Service classes are unit-testable without ActiveJob infrastructure.
+- Future pipeline changes (e.g., calling the same logic synchronously) require no job changes.
+
+**Template for new jobs:**
+
+```ruby
+class MyJob < ApplicationJob
+  source_monitor_queue :maintenance
+  discard_on ActiveJob::DeserializationError
+
+  def perform(record_id)
+    record = MyModel.find_by(id: record_id)
+    return unless record
+
+    MyNamespace::MyService.new(record: record).call
+  end
+end
+```
 
 ## _later / _now Naming Convention
 

data/.claude/skills/sm-upgrade/reference/version-history.md

@@ -2,6 +2,25 @@
 
 Version-specific migration notes for each major/minor version transition. Agents should reference this file when guiding users through multi-version upgrades.
 
+## 0.11.x to 0.12.0
+
+**Key changes:**
+- 2 new migrations: composite indexes on `sourcemon_fetch_logs`, `sourcemon_scrape_logs`, and `sourcemon_health_check_logs` (on `source_id, created_at`), and `health_status` column default corrected to `"working"`.
+- 5 background jobs extracted to service classes: `ScrapeItemJob` -> `Scraping::Runner`, `DownloadContentImagesJob` -> `Images::Processor`, `FaviconFetchJob` -> `Favicons::Fetcher`, `SourceHealthCheckJob` -> `Health::SourceHealthCheckOrchestrator`, `ImportSessionHealthCheckJob` -> `ImportSessions::HealthCheckUpdater`. Job arguments and queue assignments are unchanged.
+- New ViewComponents: `StatusBadgeComponent`, `IconComponent`, `FilterDropdownComponent`.
+- New presenters: `SourceDetailsPresenter`, `SourcesFilterPresenter`.
+- New model methods: `Source.enable_scraping!(ids)`, `Item#restore!`, `health_status` validation against the 4 permitted values.
+
+**Action items:**
+1. Copy and run migrations:
+   ```bash
+   bin/rails source_monitor:install:migrations
+   bin/rails db:migrate
+   ```
+2. No breaking changes -- all existing initializer configuration and job interfaces remain valid.
+3. No configuration changes required.
+4. ViewComponents and presenters are available for use in custom views but are not required.
+
 ## 0.10.2 to 0.11.0
 
 **Key changes:**

data/CHANGELOG.md

@@ -15,6 +15,13 @@ All notable changes to this project are documented below. The format follows [Ke
 
 - No unreleased changes yet.
 
+## [0.12.1] - 2026-03-15
+
+### Documentation
+- Updated README, docs/setup, docs/upgrade with v0.12.0 version references and upgrade guide
+- Updated 4 skill references (sm-job, sm-architecture, sm-domain-model, sm-upgrade) for service class extractions, new components, and model methods
+- Improved `/release` command: Step 4 now spawns agents to automatically audit AND fix all stale docs before every release
+
 ## [0.12.0] - 2026-03-15
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    source_monitor (0.12.0)
+    source_monitor (0.12.1)
       cssbundling-rails (~> 1.4)
       faraday (~> 2.9)
       faraday-follow_redirects (~> 0.4)

data/README.md

@@ -9,8 +9,8 @@ SourceMonitor is a production-ready Rails 8 mountable engine for ingesting, norm
 In your host Rails app:
 
 ```bash
-bundle add source_monitor --version "~> 0.11.0"
-# or add `gem "source_monitor", "~> 0.11.0"` manually, then run:
+bundle add source_monitor --version "~> 0.12.0"
+# or add `gem "source_monitor", "~> 0.12.0"` manually, then run:
 bundle install
 ```
 
@@ -25,6 +25,9 @@ This exposes `bin/source_monitor` (via Bundler binstubs) so you can run the guid
 - 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
+- ViewComponent UI primitives: `StatusBadgeComponent` and `IconComponent` for consistent badge and icon rendering in custom views
+- Presenter layer: `SourceDetailsPresenter` and `SourcesFilterPresenter` for view-specific formatting without coupling controllers to display logic
+- Shallow delegation service layer: five background jobs (ScrapeItemJob, DownloadContentImagesJob, FaviconFetchJob, SourceHealthCheckJob, ImportSessionHealthCheckJob) extracted to dedicated service classes, keeping job bodies to deserialization + delegation only
 
 ## Requirements
 - Ruby 4.0+ (we recommend [rbenv](https://github.com/rbenv/rbenv) for local development, but use whatever Ruby version manager suits your environment—asdf, chruby, rvm, or container-based workflows all work fine)
@@ -43,7 +46,7 @@ This exposes `bin/source_monitor` (via Bundler binstubs) so you can run the guid
 Before running any SourceMonitor commands inside your host app, add the gem and install dependencies:
 
 ```bash
-bundle add source_monitor --version "~> 0.11.0"
+bundle add source_monitor --version "~> 0.12.0"
 # or edit your Gemfile, then run
 bundle install
 ```

data/VERSION

@@ -1 +1 @@
-0.12.0
+0.12.1

data/docs/setup.md

@@ -18,8 +18,8 @@ This guide consolidates the new guided installer, verification commands, and rol
 Run these commands inside your host Rails application before invoking the guided workflow:
 
 ```bash
-bundle add source_monitor --version "~> 0.10.0"
-# or add gem "source_monitor", "~> 0.10.0" to Gemfile manually
+bundle add source_monitor --version "~> 0.12.0"
+# or add gem "source_monitor", "~> 0.12.0" to Gemfile manually
 bundle install
 ```
 

data/docs/upgrade.md

@@ -46,6 +46,29 @@ If a removed option raises an error (`SourceMonitor::DeprecatedOptionError`), yo
 
 ## Version-Specific Notes
 
+### Upgrading to 0.12.0
+
+**What changed:**
+- 2 new migrations: composite indexes on log tables and `health_status` default value alignment.
+- 5 background jobs extracted to service classes (`Scraping::Runner`, `Images::Processor`, `Favicons::Fetcher`, `Health::SourceHealthCheckOrchestrator`, `ImportSessions::HealthCheckUpdater`). Jobs now contain only deserialization and delegation — business logic lives in `lib/`.
+- New ViewComponents: `StatusBadgeComponent` and `IconComponent` for consistent badge and icon rendering.
+- New presenters: `SourceDetailsPresenter` and `SourcesFilterPresenter` for view-specific formatting.
+- New model methods: `Source.enable_scraping!(ids)` bulk-enables scraping for a list of source IDs; `Item#restore!` reverses a soft delete and updates the source counter cache; `health_status` now validated against the 4 permitted values (`working`, `declining`, `improving`, `failing`).
+
+**Upgrade steps:**
+```bash
+bundle update source_monitor
+bin/rails source_monitor:install:migrations
+bin/rails db:migrate
+```
+
+**Notes:**
+- No breaking changes. All existing initializer configuration remains valid.
+- No configuration changes required for this release.
+- The 5 service extractions are internal. Job class names and their public interfaces (queue, arguments) are unchanged.
+- New ViewComponents and presenters are available for custom view integration but are not required by default templates.
+- `Item#restore!` is the symmetric counterpart to `soft_delete!` — it clears `deleted_at` and increments the source `items_count` counter cache.
+
 ### Upgrading to 0.11.0
 
 **What changed:**

data/lib/source_monitor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SourceMonitor
-  VERSION = "0.12.0"
+  VERSION = "0.12.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: source_monitor
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.12.1
 platform: ruby
 authors:
 - dchuk