plutonium 0.55.0 → 0.56.0

data/docs/superpowers/plans/2026-06-04-sqlite-tune-maintenance-generators.md.tasks.json

@@ -0,0 +1,45 @@
+{
+  "planPath": "docs/superpowers/plans/2026-06-04-sqlite-tune-maintenance-generators.md",
+  "tasks": [
+    {
+      "id": 1,
+      "subject": "Task 1: Extract ConfiguresRecurring concern + refactor rails_pulse",
+      "status": "completed",
+      "description": "Move env-aware recurring.yml injection into a reusable, unit-testable ConfiguresRecurring concern (pure nested RecurringYAML); rails_pulse keeps identical behavior.\n\n```json:metadata\n{\"files\": [\"lib/generators/pu/lib/plutonium_generators/concerns/configures_recurring.rb\", \"lib/generators/pu/lite/rails_pulse/rails_pulse_generator.rb\", \"test/generators/configures_recurring_test.rb\"], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/generators/configures_recurring_test.rb test/generators/lite_generators_test.rb\", \"acceptanceCriteria\": [\"ConfiguresRecurring autoloads and exposes add_recurring_tasks(tasks_yaml, marker:)\", \"RecurringYAML tested for env-scoped and flat layouts\", \"rails_pulse uses concern, old private method removed, tests still pass\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 2,
+      "subject": "Task 2: pu:lite:tune generator (SQLite pragmas)",
+      "status": "completed",
+      "description": "Generator that inserts tuned, version-aware performance pragmas into config/database.yml default block, idempotently.\n\n```json:metadata\n{\"files\": [\"lib/generators/pu/lite/tune/tune_generator.rb\", \"test/generators/lite_generators_test.rb\"], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/generators/lite_generators_test.rb\", \"acceptanceCriteria\": [\"TuneGenerator < Rails::Generators::Base, includes Generator\", \"Rails 8.1+ block = four deltas, no baseline, no busy_timeout\", \"Rails <8.1 also includes baseline pragmas\", \"idempotent re-run\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 3,
+      "subject": "Task 3: pu:lite:maintenance generator (job + schedule)",
+      "status": "completed",
+      "blockedBy": [1],
+      "description": "Generator that installs app/jobs/sqlite_maintenance_job.rb and schedules it in config/recurring.yml via ConfiguresRecurring.\n\n```json:metadata\n{\"files\": [\"lib/generators/pu/lite/maintenance/maintenance_generator.rb\", \"lib/generators/pu/lite/maintenance/templates/app/jobs/sqlite_maintenance_job.rb.tt\", \"test/generators/lite_generators_test.rb\"], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/generators/lite_generators_test.rb\", \"acceptanceCriteria\": [\"MaintenanceGenerator includes Generator + ConfiguresRecurring\", \"--schedule option defaults to 'every day at 3:30am'\", \"job template defines MaintenanceConnection/OPTIMIZE_DBS/VACUUM_DBS, PRAGMA optimize + VACUUM, Rails.error.report\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 4,
+      "subject": "Task 4: Wire generators into lite.rb app template",
+      "status": "completed",
+      "blockedBy": [2, 3],
+      "description": "lite app template runs pu:lite:tune after setup and pu:lite:maintenance after the solid/rails_pulse stack, each with a commit guard. Only edit public source.\n\n```json:metadata\n{\"files\": [\"docs/public/templates/lite.rb\"], \"verifyCommand\": \"ruby -c docs/public/templates/lite.rb\", \"acceptanceCriteria\": [\"tune generated after setup with commit guard\", \"maintenance generated after rails_pulse with commit guard\", \"only public/templates/lite.rb edited\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 5,
+      "subject": "Task 5: Docs page + sidebar entry",
+      "status": "completed",
+      "description": "Add docs/reference/generators/lite.md documenting both generators and link it in the VitePress sidebar.\n\n```json:metadata\n{\"files\": [\"docs/reference/generators/lite.md\", \"docs/.vitepress/config.ts\"], \"verifyCommand\": \"yarn docs:build\", \"acceptanceCriteria\": [\"lite.md documents both generators with rationale\", \"sidebar links /reference/generators/lite\", \"docs build passes with no broken links\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 6,
+      "subject": "Task 6: Full suite + single final commit",
+      "status": "pending",
+      "blockedBy": [1, 2, 3, 4, 5],
+      "description": "Run full generator test suite, then make ONE commit with all changes (per user's 'commit at the end').\n\n```json:metadata\n{\"files\": [], \"verifyCommand\": \"bundle exec appraisal rails-8.1 ruby -Itest test/generators/lite_generators_test.rb test/generators/configures_recurring_test.rb\", \"acceptanceCriteria\": [\"generator tests pass on Rails 8.1\", \"single commit contains all generators, concern, refactor, template, docs\"], \"requiresUserVerification\": false}\n```"
+    }
+  ],
+  "lastUpdated": "2026-06-04"
+}

data/docs/superpowers/specs/2026-06-04-sqlite-tune-maintenance-generators-design.md

@@ -0,0 +1,238 @@
+# SQLite Tuning & Maintenance Generators — Design
+
+**Date:** 2026-06-04
+**Status:** Approved (design); pending implementation plan
+
+## Summary
+
+Port two production-proven SQLite improvements from `radioactive_labs/universal_chatbot`
+into the Plutonium generator template:
+
+1. **Config tuning** — performance pragmas in `config/database.yml`.
+2. **Maintenance** — a scheduled `SqliteMaintenanceJob` (`PRAGMA optimize` everywhere,
+   `VACUUM` on safe databases only).
+
+Both ship as **two new generators** under the existing `pu:lite` namespace:
+`pu:lite:tune` and `pu:lite:maintenance`. The existing `pu:lite:setup` generator is
+left untouched.
+
+## Background
+
+### What the reference project does
+
+`config/database.yml` `default: &default` block carries tuned pragmas:
+
+```yaml
+pragmas:
+  cache_size: -64000           # 64 MB page cache (default ~2 MB is too small)
+  temp_store: 2                # MEMORY — sorts/temp indexes stay off disk
+  mmap_size: 536870912         # 512 MB (override the 128 MB default)
+  wal_autocheckpoint: 10000    # checkpoint every ~40 MB of WAL, fewer pauses
+```
+
+It deliberately does **not** set `busy_timeout` — Rails routes the `timeout:` key to
+the sqlite3 gem's constant-poll `busy_handler_timeout`, which has better tail-latency
+than SQLite's internal backoff. Adding `busy_timeout` to pragmas would replace that with
+the worse handler.
+
+`app/jobs/sqlite_maintenance_job.rb` runs nightly via `config/recurring.yml`:
+
+- Uses an isolated abstract connection class (`MaintenanceConnection`) so it never
+  mutates the global primary connection that sibling jobs rely on.
+- `PRAGMA optimize` on all databases (cheap, brief shared lock).
+- `VACUUM` only on databases without live 24/7 writers. Excludes `queue`/`cache`/`cable`
+  because SolidQueue / Solid Cache / Solid Cable write to them constantly, and VACUUM's
+  global exclusive lock stalls and errors those processes (e.g. SolidQueue process
+  deregistration hitting "database is locked"). This is the `2b813bdd` fix
+  ("stop nightly VACUUM from locking the live queue DB").
+- Errors are reported via `Rails.error.report` and the connection is always removed in
+  an `ensure` block.
+
+### Current Plutonium state
+
+- `pu:lite:setup` only ensures the `sqlite3` gem version and adds the Rails 7 enhanced
+  adapter. **No pragma tuning.**
+- `pu:lite:*` generators (solid_queue, solid_cache, solid_cable, solid_errors,
+  rails_pulse, litestream) wire up extra databases via the `ConfiguresSqlite` concern.
+- `rails_pulse_generator.rb` already contains working, env-aware `config/recurring.yml`
+  injection logic (handles both env-scoped and flat recurring files).
+- **No pragma tuning and no maintenance job exist in the template today.**
+
+## Design Decisions (confirmed)
+
+| Decision | Choice |
+|---|---|
+| Packaging | Two new generators: `pu:lite:tune`, `pu:lite:maintenance`. `pu:lite:setup` untouched. |
+| Pragma values | Port reference values **verbatim**. |
+| VACUUM target selection | Editable list in the generated job; runtime confirms each DB exists (`configs_for ... return unless config`); user can extend the list. |
+| `recurring.yml` editing | Extract the rails_pulse injection logic into a shared `ConfiguresRecurring` concern; rails_pulse refactored to use it. |
+| Generator names | `pu:lite:tune` and `pu:lite:maintenance` (confirmed). |
+
+## Component 1: `pu:lite:tune`
+
+**File:** `lib/generators/pu/lite/tune/tune_generator.rb`
+
+**Purpose:** Insert tuned performance pragmas into `config/database.yml`'s
+`default: &default` block.
+
+**Behavior:**
+
+- Locate the `default: &default` mapping in `config/database.yml`.
+- If a `pragmas:` key already exists under `default`, merge our keys, skipping any key
+  already present (no clobbering user values).
+- If no `pragmas:` key exists, insert a new `pragmas:` block containing the four reference
+  deltas plus the reference's explanatory comments, including the `busy_timeout` note.
+- **Version-aware pragma set:**
+  - Rails **8.1+**: write only the four deltas (`cache_size`, `temp_store`, `mmap_size`,
+    `wal_autocheckpoint`) — Rails already sets WAL / synchronous=NORMAL / foreign_keys /
+    mmap=128MB / journal_size_limit by default.
+  - Rails **< 8.1**: also emit the baseline set (`journal_mode: WAL`,
+    `synchronous: NORMAL`, `foreign_keys: true`, `journal_size_limit`) since these are not
+    guaranteed there. The Rails 7 path already pulls in
+    `activerecord-enhancedsqlite3-adapter` via `pu:lite:setup`, which supports pragmas.
+- **Idempotent:** re-running skips keys already present; a marker (the comment header or
+  the presence of our keys) prevents duplicate insertion.
+- Emits `say_status` lines for each key added.
+
+**Reuse:** YAML location/insertion can lean on the existing `ConfiguresSqlite` concern's
+file-manipulation helpers (`insert_into_file`, regex anchors) and `file_includes?`. The
+default-block anchor is matched the same way the concern matches `default: &default`.
+
+## Component 2: `pu:lite:maintenance`
+
+**File:** `lib/generators/pu/lite/maintenance/maintenance_generator.rb`
+**Template:** `lib/generators/pu/lite/maintenance/templates/app/jobs/sqlite_maintenance_job.rb.tt`
+
+**Purpose:** Install `SqliteMaintenanceJob` and schedule it in `config/recurring.yml`.
+
+**Behavior:**
+
+- `template` the job to `app/jobs/sqlite_maintenance_job.rb`, ported from the reference:
+  - Isolated `MaintenanceConnection < ActiveRecord::Base` (`abstract_class = true`).
+  - `OPTIMIZE_DBS` and `VACUUM_DBS = %w[primary errors rails_pulse]` as **editable
+    constants**, with comments instructing the user to add their own DB names.
+  - At runtime, `configs_for(env_name:, name:, include_hidden: true)` returns the config
+    or nil; `return unless config` silently skips DBs that don't exist — this is the
+    "keep a list, confirm they exist" behavior.
+  - `PRAGMA optimize` on every `OPTIMIZE_DBS` entry; `VACUUM` only on `VACUUM_DBS`.
+  - Preserve the live-writer exclusion rationale (queue/cache/cable) as comments.
+  - `rescue => e` → `Rails.error.report(e, context: {...})`; `ensure` removes the
+    connection.
+- Add the recurring entry to `config/recurring.yml` using the shared
+  `ConfiguresRecurring` concern (see below):
+  ```yaml
+  sqlite_maintenance:
+    class: SqliteMaintenanceJob
+    queue: default
+    schedule: every day at 3:30am
+    description: "VACUUM + PRAGMA optimize across SQLite databases"
+  ```
+- **Gating:** if solid_queue is not installed or `config/recurring.yml` is absent, still
+  write the job file but log that no scheduler was found (mirrors rails_pulse's
+  `solid_queue_installed?` gate).
+- **Idempotent:** skip the recurring injection if `sqlite_maintenance` is already present;
+  `template` with conflict handling for the job file.
+
+## Component 3: `ConfiguresRecurring` concern (refactor)
+
+**File:** `lib/generators/pu/lib/plutonium_generators/concerns/configures_recurring.rb`
+
+Extract the env-aware `recurring.yml` injection currently private to
+`rails_pulse_generator.rb` into a reusable concern. Concerns are autoloaded by Zeitwerk
+(`Zeitwerk::Loader.for_gem` in `lib/generators/pu/lib/plutonium_generators.rb`), so a new
+file at the conventional path with module nesting
+`PlutoniumGenerators::Concerns::ConfiguresRecurring` is picked up automatically — no
+manual `require` needed. Public surface:
+
+```ruby
+# Inject one or more recurring task blocks into config/recurring.yml,
+# handling both env-scoped (production:/development:) and flat layouts.
+add_recurring_tasks(tasks_yaml, marker:)
+```
+
+- `tasks_yaml`: the YAML body for the task(s), without leading indentation (the concern
+  re-indents per environment, as the existing code does).
+- `marker`: a string used for the `file_includes?` idempotency guard (e.g.
+  `"rails_pulse"`, `"sqlite_maintenance"`).
+- Internals are the existing `inject_*_under_envs` / indent-detection logic, generalized
+  to accept arbitrary task YAML instead of hardcoded rails_pulse tasks.
+
+`rails_pulse_generator.rb` is refactored to call `add_recurring_tasks` with its existing
+task YAML and `marker: "rails_pulse"`. No behavior change.
+
+## Testing
+
+Add to `test/generators/` (alongside `lite_generators_test.rb`,
+`configures_sqlite_test.rb`):
+
+- **`pu:lite:tune`:**
+  - Inserts the `pragmas:` block with the four delta keys into the `default` anchor.
+  - Re-running is idempotent (no duplicate keys).
+  - Merges into an existing `pragmas:` block without clobbering user-set keys.
+  - (If feasible in the harness) version-aware: Rails < 8.1 emits the baseline set.
+- **`pu:lite:maintenance`:**
+  - Creates `app/jobs/sqlite_maintenance_job.rb` with the expected constants.
+  - Injects the `sqlite_maintenance` entry under each environment in an env-scoped
+    `recurring.yml`; idempotent on re-run.
+  - When `recurring.yml` is absent, writes the job and logs the missing-scheduler notice.
+- **`ConfiguresRecurring`:** the extracted concern behaves identically to the old
+  rails_pulse path (regression guard) — verify via the existing rails_pulse test still
+  passing plus a focused concern test.
+
+## App template integration (`lite.rb`)
+
+`docs/public/templates/lite.rb` is the SQLite-stack app template that chains the
+`pu:lite:*` generators `after_bundle` (setup → solid_queue/cache/cable/errors →
+litestream → rails_pulse), each followed by a conditional git commit.
+
+Wire **both** new generators into this template, matching the existing pattern (each with
+its own `git add` / `git commit` guard):
+
+- `pu:lite:tune` — immediately after `pu:lite:setup` (pragmas belong with the base SQLite
+  config, before the extra DBs are added).
+- `pu:lite:maintenance` — after the solid stack and rails_pulse, so the extra databases
+  exist and `solid_queue` is present for scheduling.
+
+Only edit the source template at `docs/public/templates/lite.rb`; the copies under
+`docs/dist/` and `docs/.vitepress/dist/` are build artifacts regenerated by
+`yarn docs:build`.
+
+## Documentation
+
+- New standalone page **`docs/reference/generators/lite.md`** describing the `pu:lite:*`
+  generators, with full sections for `pu:lite:tune` and `pu:lite:maintenance` (purpose,
+  options, idempotency, the `busy_timeout` rationale, and the VACUUM live-writer
+  exclusion rationale). Documenting the other existing `pu:lite:*` generators on this page
+  is a nice-to-have but the two new ones are required.
+- Add the new page to the VitePress sidebar in `docs/.vitepress/config.ts` (near the
+  existing `/reference/app/generators` entry) so it is reachable.
+- Skills require a gem release to take effect; a skill update is **out of scope** for this
+  change (docs page + sidebar only).
+
+## Out of scope (YAGNI)
+
+- App-specific extras from the reference (`sqlite_vec` extension loading, per-app
+  cleanup jobs, Rails Pulse summary/cleanup jobs) — those belong to their own generators
+  or the app, not this port.
+- Changing `pu:lite:setup` behavior.
+- Litestream / backup concerns (separate `pu:lite:litestream` generator already exists).
+
+## File change list
+
+| Action | Path |
+|---|---|
+| Create | `lib/generators/pu/lite/tune/tune_generator.rb` |
+| Create | `lib/generators/pu/lite/maintenance/maintenance_generator.rb` |
+| Create | `lib/generators/pu/lite/maintenance/templates/app/jobs/sqlite_maintenance_job.rb.tt` |
+| Create | `lib/generators/pu/lib/plutonium_generators/concerns/configures_recurring.rb` |
+| Modify | `lib/generators/pu/lite/rails_pulse/rails_pulse_generator.rb` (use shared concern) |
+| Modify | `docs/public/templates/lite.rb` (chain `pu:lite:tune` + `pu:lite:maintenance`) |
+| Create | `test/generators/tune_generator_test.rb` (or extend `lite_generators_test.rb`) |
+| Create | `test/generators/maintenance_generator_test.rb` (or extend `lite_generators_test.rb`) |
+| Create | `docs/reference/generators/lite.md` |
+| Modify | `docs/.vitepress/config.ts` (sidebar entry for the new page) |
+
+> Zeitwerk autoloads concerns by path, so no edit to
+> `lib/generators/pu/lib/plutonium_generators.rb` is required for the new concern.
+> The `docs/dist/` and `docs/.vitepress/dist/` copies of `lite.rb` are build artifacts —
+> do not hand-edit them.

data/gemfiles/rails_7.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.52.0)
+    plutonium (0.55.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 43.0)

data/gemfiles/rails_8.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.52.0)
+    plutonium (0.55.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 43.0)

data/gemfiles/rails_8.1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    plutonium (0.54.0)
+    plutonium (0.55.0)
       action_policy (~> 0.7.0)
       listen (~> 3.8)
       pagy (~> 43.0)

data/lib/generators/pu/core/update/update_generator.rb

@@ -23,7 +23,10 @@ module Pu
         return unless File.file?(Rails.root.join(".claude", "skills", "plutonium", "SKILL.md"))
 
         say_status :update, "Syncing Plutonium Claude skills...", :green
-        Rails::Generators.invoke("pu:skills:sync", [], destination_root: Rails.root)
+        # Shell out to a fresh process so the sync reads the newly-installed
+        # gem's skills. Invoking in-process would reuse the already-loaded
+        # (pre-update) gem, whose Plutonium.root still points at the old skills.
+        run "bin/rails generate pu:skills:sync"
       end
 
       def update_gem

data/lib/generators/pu/lib/plutonium_generators/concerns/configures_recurring.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module PlutoniumGenerators
+  module Concerns
+    module ConfiguresRecurring
+      ENV_KEYS = %w[production development staging test].freeze
+
+      # Pure transform of a config/recurring.yml string. No file IO — testable
+      # in isolation, mirroring ConfiguresSqlite::DatabaseYAML.
+      class RecurringYAML
+        # Returns new content with `tasks_yaml` injected. If the file is
+        # env-scoped (has top-level production:/development:/... keys), the
+        # tasks are inserted under each environment at the siblings' indent.
+        # Otherwise they are appended at column 0.
+        def inject(content, tasks_yaml)
+          if env_scoped?(content)
+            inject_under_envs(content, tasks_yaml)
+          else
+            content.rstrip + "\n\n" + indent(tasks_yaml, 0)
+          end
+        end
+
+        private
+
+        def env_scoped?(content)
+          content.lines.any? { |l| l.match?(env_re) }
+        end
+
+        def env_re
+          /^(#{ENV_KEYS.join("|")}):\s*$/
+        end
+
+        def indent(yaml, n)
+          pad = " " * n
+          yaml.gsub(/^(?=.)/, pad)
+        end
+
+        def inject_under_envs(content, tasks_yaml)
+          lines = content.lines
+          env_starts = lines.each_with_index.select { |l, _| env_re.match?(l) }.map(&:last)
+
+          env_starts.reverse_each do |start|
+            end_idx = lines.length
+            ((start + 1)...lines.length).each do |i|
+              if lines[i].match?(/^[^\s#]/)
+                end_idx = i
+                break
+              end
+            end
+
+            child_indent = 2
+            ((start + 1)...end_idx).each do |i|
+              if (m = lines[i].match(/^(\s+)\S/))
+                child_indent = m[1].length
+                break
+              end
+            end
+
+            insert_at = end_idx
+            while insert_at > start + 1 && lines[insert_at - 1].strip.empty?
+              insert_at -= 1
+            end
+
+            lines.insert(insert_at, "\n", indent(tasks_yaml, child_indent))
+          end
+
+          lines.join
+        end
+      end
+
+      private
+
+      # Inject recurring task YAML into config/recurring.yml. Returns true when
+      # written, false when the file is missing or the marker already present
+      # (idempotent). `marker` is matched with file_includes? to avoid dupes.
+      def add_recurring_tasks(tasks_yaml, marker:)
+        recurring_file = "config/recurring.yml"
+        full_path = File.expand_path(recurring_file, destination_root)
+        return false unless File.exist?(full_path)
+        return false if file_includes?(recurring_file, marker)
+
+        new_content = RecurringYAML.new.inject(File.read(full_path), tasks_yaml)
+        create_file recurring_file, new_content, force: true
+        say_status :recurring, "#{marker} (config/recurring.yml)"
+        true
+      end
+    end
+  end
+end

data/lib/generators/pu/lite/maintenance/maintenance_generator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../../lib/plutonium_generators"
+
+module Pu
+  module Lite
+    class MaintenanceGenerator < Rails::Generators::Base
+      include PlutoniumGenerators::Generator
+      include PlutoniumGenerators::Concerns::ConfiguresRecurring
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install a nightly SqliteMaintenanceJob (PRAGMA optimize + VACUUM)"
+
+      class_option :schedule, type: :string, default: "every day at 3:30am",
+        desc: "Cron-style schedule for the maintenance job"
+
+      def start
+        template "app/jobs/sqlite_maintenance_job.rb"
+
+        if gem_in_bundle?("solid_queue")
+          unless add_recurring_tasks(maintenance_task_yaml, marker: "sqlite_maintenance")
+            log :skip, "could not schedule (config/recurring.yml missing or already scheduled)"
+          end
+        else
+          log :info, "solid_queue not found — job installed but not scheduled. Add a 'sqlite_maintenance' entry to your scheduler."
+        end
+      rescue => e
+        exception "#{self.class} failed:", e
+      end
+
+      private
+
+      def maintenance_task_yaml
+        <<~YAML
+          sqlite_maintenance:
+            class: SqliteMaintenanceJob
+            queue: default
+            schedule: "#{options[:schedule]}"
+            description: "VACUUM + PRAGMA optimize across SQLite databases"
+        YAML
+      end
+    end
+  end
+end

data/lib/generators/pu/lite/maintenance/templates/app/jobs/sqlite_maintenance_job.rb.tt

@@ -0,0 +1,60 @@
+class SqliteMaintenanceJob < ApplicationJob
+  queue_as :default
+
+  # Isolated connection for maintenance. Establishing on this dedicated
+  # abstract class (instead of ActiveRecord::Base) means we never mutate
+  # the global primary connection — a sibling job on the other worker
+  # thread keeps talking to the right database.
+  class MaintenanceConnection < ActiveRecord::Base
+    self.abstract_class = true
+  end
+
+  # Names match the keys in config/database.yml. Add your own database
+  # names here if you run extra SQLite databases.
+  #
+  # PRAGMA optimize is cheap (just refreshes query-planner stats, brief
+  # shared lock) so it runs everywhere. Full VACUUM rewrites the file
+  # under a global *exclusive* lock for its whole duration, so it only
+  # runs on databases without live 24/7 writers.
+  OPTIMIZE_DBS = %w[primary queue cache cable errors rails_pulse].freeze
+
+  # queue/cable/cache are deliberately excluded: SolidQueue, Solid Cable
+  # and Solid Cache write to them constantly, and a VACUUM lock there
+  # stalls (and errors out) those processes — e.g. SolidQueue's process
+  # deregistration hitting "database is locked". They also barely benefit:
+  # in WAL mode deleted pages land on the freelist and get reused, so a
+  # churning DB sits at a steady-state size without nightly reclamation.
+  VACUUM_DBS = %w[primary errors rails_pulse].freeze
+
+  def perform
+    OPTIMIZE_DBS.each { |db_name| run_maintenance(db_name) }
+  end
+
+  private
+
+  def run_maintenance(db_name)
+    config = ActiveRecord::Base.configurations.configs_for(
+      env_name: Rails.env,
+      name: db_name,
+      include_hidden: true
+    )
+    return unless config
+
+    MaintenanceConnection.establish_connection(config)
+    MaintenanceConnection.connection_pool.with_connection do |conn|
+      Rails.logger.info { "[SqliteMaintenance] PRAGMA optimize on #{db_name}" }
+      conn.execute("PRAGMA optimize")
+
+      next unless VACUUM_DBS.include?(db_name)
+
+      Rails.logger.info { "[SqliteMaintenance] VACUUM on #{db_name}" }
+      started = Time.current
+      conn.execute("VACUUM")
+      Rails.logger.info { "[SqliteMaintenance] VACUUM on #{db_name} done in #{(Time.current - started).round(2)}s" }
+    end
+  rescue => e
+    Rails.error.report(e, context: {db: db_name, action: "sqlite_maintenance"})
+  ensure
+    MaintenanceConnection.remove_connection
+  end
+end

data/lib/generators/pu/lite/rails_pulse/rails_pulse_generator.rb

@@ -7,6 +7,7 @@ module Pu
     class RailsPulseGenerator < Rails::Generators::Base
       include PlutoniumGenerators::Generator
       include PlutoniumGenerators::Concerns::ConfiguresSqlite
+      include PlutoniumGenerators::Concerns::ConfiguresRecurring
       include PlutoniumGenerators::Concerns::MountsEngines
 
       source_root File.expand_path("templates", __dir__)
@@ -69,25 +70,11 @@ module Pu
       end
 
       def setup_recurring_tasks
-        recurring_file = "config/recurring.yml"
-        full_path = File.expand_path(recurring_file, destination_root)
-        return unless File.exist?(full_path)
-        return if file_includes?(recurring_file, "rails_pulse")
-
-        content = File.read(full_path)
-        env_keys = %w[production development staging test]
-        env_scoped = content.lines.any? { |l| l.match?(/^(#{env_keys.join("|")}):\s*$/) }
-
-        if env_scoped
-          create_file recurring_file, inject_rails_pulse_under_envs(content, env_keys), force: true
-        else
-          append_to_file recurring_file, "\n" + rails_pulse_tasks_yaml(0)
-        end
+        add_recurring_tasks(rails_pulse_tasks_yaml, marker: "rails_pulse")
       end
 
-      def rails_pulse_tasks_yaml(indent)
-        pad = " " * indent
-        <<~YAML.gsub(/^(?=.)/, pad)
+      def rails_pulse_tasks_yaml
+        <<~YAML
           rails_pulse_summary:
             class: RailsPulse::SummaryJob
             queue: default
@@ -101,40 +88,6 @@ module Pu
             description: "Archive/purge old Rails Pulse data"
         YAML
       end
-
-      def inject_rails_pulse_under_envs(content, env_keys)
-        lines = content.lines
-        env_re = /^(#{env_keys.join("|")}):\s*$/
-
-        env_starts = lines.each_with_index.select { |l, _| env_re.match?(l) }.map(&:last)
-
-        env_starts.reverse_each do |start|
-          end_idx = lines.length
-          ((start + 1)...lines.length).each do |i|
-            if lines[i].match?(/^[^\s#]/)
-              end_idx = i
-              break
-            end
-          end
-
-          indent = 2
-          ((start + 1)...end_idx).each do |i|
-            if (m = lines[i].match(/^(\s+)\S/))
-              indent = m[1].length
-              break
-            end
-          end
-
-          insert_at = end_idx
-          while insert_at > start + 1 && lines[insert_at - 1].strip.empty?
-            insert_at -= 1
-          end
-
-          lines.insert(insert_at, "\n", rails_pulse_tasks_yaml(indent))
-        end
-
-        lines.join
-      end
     end
   end
 end

data/lib/generators/pu/lite/rails_pulse/templates/config/initializers/rails_pulse.rb.tt

@@ -27,6 +27,6 @@ RailsPulse.configure do |config|
 <%- if options[:database] -%>
 
   # Use separate database for performance data
-  config.connects_to = {database: {writing: :<%= options[:database] %>}}
+  config.connects_to = {database: {writing: :<%= options[:database] %>, reading: :<%= options[:database] %>}}
 <%- end -%>
 end