maquina-generators 0.5.0 → 0.7.0

data/lib/generators/maquina/csp_reports/csp_reports_generator.rb

@@ -0,0 +1,231 @@
+require "rails/generators"
+require "rails/generators/migration"
+
+module Maquina
+  module Generators
+    class CspReportsGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      THROTTLE_LIMIT = 100
+      THROTTLE_PERIOD = "5.minutes"
+      # Rails' default nonce generator, empty for a request without a session.
+      SESSION_NONCE = "->(request) { request.session.id.to_s }"
+      POLICY_BLOCK = /^  config\.content_security_policy do \|policy\|\n/
+      # The general throttle's exemptions, in the two shapes maquina:rack_attack
+      # has shipped: a start_with? list, and a STATIC_FILE_PREFIXES word array.
+      COUNTED_IP_EXEMPTIONS = /req\.path\.start_with\?\("\/assets", "\/rails\/active_storage"/
+      STATIC_FILE_PREFIXES = /(STATIC_FILE_PREFIXES = %w\[)([^\]]*)(\])/
+      SECURITY_PAGE_END = /\n<\/div>\n\z/
+
+      class_option :path, type: :string, default: "/csp-reports",
+        desc: "Path browsers post violation reports to"
+      class_option :quiet, type: :boolean, default: false,
+        desc: "Suppress post-install instructions"
+
+      def self.next_migration_number(dirname)
+        current = Time.now.utc.strftime("%Y%m%d%H%M%S")
+        existing = Dir.glob("#{dirname}/[0-9]*_*.rb").map { |f| File.basename(f).split("_", 2).first }.max
+        (existing && existing >= current) ? existing.succ : current
+      end
+
+      # 1. maquina:security owns the database the reports go in.
+      def require_security_database
+        return if File.exist?(File.join(destination_root, "db/security_schema.rb"))
+
+        raise Thor::Error, "maquina:csp_reports stores reports in the `security` database. Run `rails g maquina:security --prefix /admin` first."
+      end
+
+      # 2. Models
+      def create_models
+        copy_file "app/models/security/csp_violation.rb", "app/models/security/csp_violation.rb"
+        copy_file "app/models/security/csp_violation_report.rb", "app/models/security/csp_violation_report.rb"
+      end
+
+      # 3. Controller and route
+      def create_controller
+        copy_file "app/controllers/csp_reports_controller.rb", "app/controllers/csp_reports_controller.rb"
+        route %(post "#{options[:path]}", to: "csp_reports#create", as: :csp_reports)
+      end
+
+      # 4. The table: a migration for an existing security database, the schema
+      #    for a fresh one (db:prepare loads the schema only on create).
+      def create_table
+        return if File.read(schema_path).include?(%("csp_violations"))
+
+        migration_template "db/create_csp_violations.rb.tt", "db/security_migrate/create_csp_violations.rb"
+        version = Dir.glob(File.join(destination_root, "db/security_migrate/*_create_csp_violations.rb"))
+          .map { |f| File.basename(f).split("_", 2).first }.max
+        gsub_file "db/security_schema.rb", /define\(version: [\d_]+\)/, "define(version: #{version_with_underscores(version)})"
+        inject_into_file "db/security_schema.rb", csp_violations_table, before: /^end\s*\z/
+      end
+
+      # 5. The policy reports to the endpoint, and anonymous requests get a nonce.
+      def configure_content_security_policy
+        path = "config/initializers/content_security_policy.rb"
+        content = File.exist?(File.join(destination_root, path)) ? File.read(File.join(destination_root, path)) : ""
+
+        if content.include?("report_uri")
+          @report_uri_pending = !content.include?(%(report_uri "#{options[:path]}"))
+        elsif content.match?(POLICY_BLOCK)
+          inject_into_file path, report_uri_line, after: POLICY_BLOCK
+        else
+          @report_uri_pending = true
+        end
+
+        if content.include?(SESSION_NONCE)
+          gsub_file path, SESSION_NONCE, "->(request) { request.session.id.to_s.presence || SecureRandom.base64(16) }"
+        end
+      end
+
+      # 6. Rack::Attack: out of the general throttle, capped on its own.
+      def configure_rack_attack
+        path = "config/initializers/rack_attack.rb"
+        full_path = File.join(destination_root, path)
+        return @rack_attack_pending = true unless File.exist?(full_path)
+
+        content = File.read(full_path)
+        return if content.include?(%("csp/ip"))
+
+        if content.match?(COUNTED_IP_EXEMPTIONS)
+          # The match stops before the call's closing paren, which stays in place.
+          gsub_file path, COUNTED_IP_EXEMPTIONS, 'req.path.start_with?("/assets", "/rails/active_storage", ' + %("#{options[:path]}")
+        elsif content.match?(STATIC_FILE_PREFIXES)
+          gsub_file path, STATIC_FILE_PREFIXES, "\\1\\2 #{options[:path]}\\3"
+        else
+          @rack_attack_pending = true
+        end
+
+        append_to_file path, csp_throttle
+      end
+
+      # 7. Daily purge
+      def add_recurring_purge
+        path = File.join(destination_root, "config/recurring.yml")
+        content = File.exist?(path) ? File.read(path) : ""
+        return if content.include?("purge_csp_violations")
+
+        if content.match?(/^production:\n/)
+          inject_into_file "config/recurring.yml", recurring_entry, after: /^production:\n/
+        else
+          @recurring_pending = true
+        end
+      end
+
+      # 8. Security page section
+      def add_security_page_section
+        copy_file "app/views/backstage/security/_csp_violations.html.erb",
+          "app/views/backstage/security/_csp_violations.html.erb"
+
+        page = "app/views/backstage/security/show.html.erb"
+        full_path = File.join(destination_root, page)
+        content = File.exist?(full_path) ? File.read(full_path) : ""
+        return if content.include?("backstage/security/csp_violations")
+
+        if content.match?(SECURITY_PAGE_END)
+          inject_into_file page, security_page_section, before: SECURITY_PAGE_END
+        else
+          @page_pending = true
+        end
+      end
+
+      # 9. Post-install message
+      def show_post_install
+        return if options[:quiet]
+
+        say ""
+        say "Content Security Policy reports are set up at POST #{options[:path]}.", :green
+        say ""
+        say "Next steps:", :yellow
+        say "  - Add the table: bin/rails db:migrate (db:prepare on deploy)"
+        say "  - Watch the Security page while the policy is report-only, then set"
+        say "    content_security_policy_report_only = false to enforce it."
+        if @report_uri_pending
+          say ""
+          say "Point the policy at the endpoint in config/initializers/content_security_policy.rb:", :yellow
+          say "  #{report_uri_line.strip}"
+        end
+        if @rack_attack_pending
+          say ""
+          say "Exempt #{options[:path]} from the general throttle in config/initializers/rack_attack.rb and add:", :yellow
+          say csp_throttle
+        end
+        if @recurring_pending
+          say ""
+          say "Add to config/recurring.yml under your production (or shared) key:", :yellow
+          say recurring_entry
+        end
+        if @page_pending
+          say ""
+          say "Render the section on the Security page:", :yellow
+          say security_page_section
+        end
+        say ""
+      end
+
+      private
+
+      def schema_path = File.join(destination_root, "db/security_schema.rb")
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+      end
+
+      def version_with_underscores(version)
+        version.sub(/\A(\d{4})(\d{2})(\d{2})(\d{6})\z/, '\1_\2_\3_\4')
+      end
+
+      def report_uri_line
+        %(    # Violations go to CspReportsController (maquina:csp_reports). report-uri\n) +
+          %(    # alone: adding report-to switches Chrome to the batched Reporting API.\n) +
+          %(    policy.report_uri "#{options[:path]}"\n)
+      end
+
+      def csp_throttle
+        <<~RUBY
+
+          # Content Security Policy reports (maquina:csp_reports): exempt from the
+          # general throttle above — one page with a dozen violations would spend a
+          # reader's budget — and capped on their own.
+          Rack::Attack.throttle("csp/ip", limit: #{THROTTLE_LIMIT}, period: #{THROTTLE_PERIOD}) do |req|
+            (req.env["action_dispatch.remote_ip"]&.to_s || req.ip) if req.path == "#{options[:path]}" && req.post?
+          end
+        RUBY
+      end
+
+      def recurring_entry
+        <<~YAML.gsub(/^/, "  ")
+          purge_csp_violations:
+            command: "Security::CspViolation.expired.delete_all"
+            schedule: every day at 4:30am
+        YAML
+      end
+
+      def security_page_section
+        %(\n\n  <%= render "backstage/security/csp_violations", report: Security::CspViolationReport.new %>)
+      end
+
+      def csp_violations_table
+        <<~RUBY.gsub(/^(?=.)/, "  ")
+
+          create_table "csp_violations", force: :cascade do |t|
+            t.integer "column_number"
+            t.datetime "created_at", null: false
+            t.string "blocked_uri"
+            t.string "disposition"
+            t.string "document_uri"
+            t.string "effective_directive", null: false
+            t.string "ip"
+            t.integer "line_number"
+            t.string "sample"
+            t.string "source_file"
+            t.string "user_agent"
+            t.index ["created_at"], name: "index_csp_violations_on_created_at"
+            t.index ["effective_directive", "created_at"], name: "index_csp_violations_on_effective_directive_and_created_at"
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/generators/maquina/csp_reports/templates/app/controllers/csp_reports_controller.rb

@@ -0,0 +1,24 @@
+# Receives Content Security Policy violation reports. Browsers post them with no
+# cookie and no CSRF token, in either the legacy report-uri shape
+# (application/csp-report) or the Reporting API's (application/reports+json),
+# so this is an API controller that reads the raw body itself.
+#
+# Always 204 for a report it could read — a browser does nothing with the
+# answer — and best effort: a locked security database must never turn a
+# report into a 500 that the browser retries.
+class CspReportsController < ActionController::API
+  MAX_BYTES = 64.kilobytes
+
+  def create
+    body = request.body.read(MAX_BYTES + 1).to_s
+    return head 413 if body.bytesize > MAX_BYTES
+
+    Security::CspViolation.record_report!(body, ip: request.remote_ip, user_agent: request.user_agent)
+    head :no_content
+  rescue JSON::ParserError
+    head :bad_request
+  rescue => error
+    Rails.logger.error "[CSP] report not recorded: #{error.class}: #{error.message}"
+    head :no_content
+  end
+end

data/lib/generators/maquina/csp_reports/templates/app/models/security/csp_violation.rb

@@ -0,0 +1,89 @@
+# One Content Security Policy violation a browser reported to CspReportsController.
+# Rows are written once and never updated; they are what tells you whether the
+# policy is ready to enforce (report-only) or what it is breaking (enforced).
+#
+# Browsers send two shapes. The legacy `report-uri` one is a single object,
+# `{"csp-report": {"blocked-uri": ..., ...}}` (Content-Type application/csp-report);
+# the Reporting API one is an array of `{"type": "csp-violation", "body": {...}}`
+# (application/reports+json) with camelCase keys. Both normalize to the same row.
+class Security::CspViolation < Security::Record
+  RETENTION = 30.days
+
+  # Violations caused by the reader's own browser extensions say nothing about
+  # the app, and they are most of the volume.
+  NOISE_SCHEMES = %w[chrome-extension moz-extension safari-extension safari-web-extension ms-browser-extension].freeze
+
+  FIELD_LIMIT = 1024
+  SAMPLE_LIMIT = 256
+
+  LEGACY_KEYS = {
+    "document-uri" => :document_uri, "blocked-uri" => :blocked_uri,
+    "effective-directive" => :effective_directive, "violated-directive" => :effective_directive,
+    "disposition" => :disposition, "source-file" => :source_file,
+    "line-number" => :line_number, "column-number" => :column_number, "script-sample" => :sample
+  }.freeze
+
+  REPORTING_API_KEYS = {
+    "documentURL" => :document_uri, "blockedURL" => :blocked_uri,
+    "effectiveDirective" => :effective_directive, "disposition" => :disposition,
+    "sourceFile" => :source_file, "lineNumber" => :line_number,
+    "columnNumber" => :column_number, "sample" => :sample
+  }.freeze
+
+  validates :effective_directive, presence: true
+
+  scope :recent, -> { order(created_at: :desc, id: :desc) }
+  scope :within, ->(window) { where(created_at: window.ago..) }
+  scope :expired, -> { where(created_at: ...RETENTION.ago) }
+
+  # Records every violation in a raw report body; returns how many were kept.
+  # Raises JSON::ParserError on a body that isn't JSON.
+  def self.record_report!(raw, ip:, user_agent:)
+    violations = parse(raw).reject { |attrs| noise?(attrs) }
+    violations.each do |attrs|
+      create!(attrs.merge(ip:, user_agent: user_agent&.truncate(FIELD_LIMIT, omission: "")))
+    end
+    violations.size
+  end
+
+  def self.parse(raw)
+    payload = JSON.parse(raw)
+    reports = payload.is_a?(Array) ? payload : [payload]
+
+    reports.filter_map do |report|
+      next unless report.is_a?(Hash)
+
+      if report.key?("csp-report")
+        normalize(report["csp-report"], LEGACY_KEYS)
+      elsif report["type"] == "csp-violation"
+        normalize(report["body"], REPORTING_API_KEYS)
+      end
+    end
+  end
+
+  def self.noise?(attrs)
+    [attrs[:blocked_uri], attrs[:source_file]].compact.any? do |uri|
+      NOISE_SCHEMES.any? { |scheme| uri.start_with?("#{scheme}:") }
+    end
+  end
+
+  def self.normalize(body, keys)
+    return unless body.is_a?(Hash)
+
+    attrs = keys.each_with_object({}) do |(key, attribute), acc|
+      acc[attribute] ||= body[key] if body.key?(key)
+    end
+    # The directive alone (`script-src`), not the whole violated policy line.
+    attrs[:effective_directive] = attrs[:effective_directive].to_s.split.first
+    # URLs lose their query and fragment: a reported URL can carry a token.
+    %i[document_uri blocked_uri source_file].each { |key| attrs[key] = strip_url(attrs[key]) }
+    attrs[:sample] = attrs[:sample]&.to_s&.truncate(SAMPLE_LIMIT, omission: "")
+    %i[line_number column_number].each { |key| attrs[key] = attrs[key]&.to_i }
+    attrs.transform_values { |value| value.is_a?(String) ? value.truncate(FIELD_LIMIT, omission: "") : value }
+  end
+
+  def self.strip_url(value)
+    value&.to_s&.split(/[?#]/, 2)&.first
+  end
+  private_class_method :normalize, :strip_url
+end

data/lib/generators/maquina/csp_reports/templates/app/models/security/csp_violation_report.rb

@@ -0,0 +1,30 @@
+# What the Security page shows about Content Security Policy: the last `window`
+# of reported violations, grouped by what was blocked, where and why.
+class Security::CspViolationReport
+  Group = Data.define(:effective_directive, :blocked_uri, :document_uri, :count, :last_seen)
+
+  attr_reader :window, :limit
+
+  def initialize(window: 7.days, limit: 10)
+    @window = window
+    @limit = limit
+  end
+
+  def violations = Security::CspViolation.within(window)
+
+  def empty? = violations.none?
+
+  def total = violations.count
+
+  # The same blocked resource on the same page under the same directive, most
+  # frequent first — one row per thing to fix, however many readers hit it.
+  def top
+    violations.group(:effective_directive, :blocked_uri, :document_uri)
+      .order(Arel.sql("COUNT(*) DESC, MAX(created_at) DESC")).limit(limit)
+      .pluck(:effective_directive, :blocked_uri, :document_uri, Arel.sql("COUNT(*)"), Arel.sql("MAX(created_at)"))
+      .map do |directive, blocked, document, count, last|
+        Group.new(effective_directive: directive, blocked_uri: blocked, document_uri: document,
+          count:, last_seen: last.is_a?(String) ? ActiveSupport::TimeZone["UTC"].parse(last) : last)
+      end
+  end
+end

data/lib/generators/maquina/csp_reports/templates/app/views/backstage/security/_csp_violations.html.erb

@@ -0,0 +1,42 @@
+<%# locals: (report:) %>
+<%# Content Security Policy violations browsers reported to /csp-reports
+    (maquina:csp_reports), grouped so each row is one thing to fix. %>
+<%= render "components/card" do %>
+  <%= render "components/card/header" do %>
+    <%= render "components/card/title", text: "Content Security Policy violations" %>
+    <%= render "components/card/description",
+          text: "#{number_with_delimiter(report.total)} reported in the last #{report.window.inspect}, kept for #{Security::CspViolation::RETENTION.inspect}. Most frequent first." %>
+  <% end %>
+  <%= render "components/card/content", spacing: :full do %>
+    <% if report.empty? %>
+      <%= empty_state(title: "No violation was reported.", icon: :check_circle, size: :compact) %>
+    <% else %>
+      <div class="overflow-x-auto">
+        <%= render "components/table", container: false, "aria-label": "Content Security Policy violations" do %>
+          <%= render "components/table/header" do %>
+            <%= render "components/table/row" do %>
+              <%= render "components/table/head", text: "Directive" %>
+              <%= render "components/table/head", text: "Blocked" %>
+              <%= render "components/table/head", text: "Page" %>
+              <%= render "components/table/head", text: "Reports", css_classes: "text-right" %>
+              <%= render "components/table/head", text: "Last seen" %>
+            <% end %>
+          <% end %>
+          <%= render "components/table/body" do %>
+            <% report.top.each do |group| %>
+              <%= render "components/table/row" do %>
+                <%= render "components/table/cell", css_classes: "font-mono", text: group.effective_directive %>
+                <%= render "components/table/cell", css_classes: "font-mono whitespace-normal break-all", text: group.blocked_uri.presence || "—" %>
+                <%= render "components/table/cell", css_classes: "font-mono whitespace-normal break-all", text: group.document_uri.presence || "—" %>
+                <%= render "components/table/cell", css_classes: "text-right tabular-nums", text: number_with_delimiter(group.count) %>
+                <%= render "components/table/cell" do %>
+                  <%= render "backstage/security/utc_time", time: group.last_seen %>
+                <% end %>
+              <% end %>
+            <% end %>
+          <% end %>
+        <% end %>
+      </div>
+    <% end %>
+  <% end %>
+<% end %>

data/lib/generators/maquina/csp_reports/templates/db/create_csp_violations.rb.tt

@@ -0,0 +1,23 @@
+# Content Security Policy violation reports (maquina:csp_reports). Lives in the
+# `security` database next to abuse_events; db/security_schema.rb carries the same
+# table for a fresh database, this migration adds it to an existing one.
+class CreateCspViolations < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :csp_violations do |t|
+      t.string :effective_directive, null: false
+      t.string :blocked_uri
+      t.string :document_uri
+      t.string :source_file
+      t.integer :line_number
+      t.integer :column_number
+      t.string :disposition
+      t.string :sample
+      t.string :ip
+      t.string :user_agent
+      t.datetime :created_at, null: false
+    end
+
+    add_index :csp_violations, :created_at
+    add_index :csp_violations, [:effective_directive, :created_at]
+  end
+end

data/lib/generators/maquina/mission_control_jobs/mission_control_jobs_generator.rb

@@ -49,7 +49,7 @@ module Maquina
 
       # 5. Routes
       def add_route
-        mount_path = "#{options[:prefix]}/mission_control_jobs"
+        mount_path = "#{options[:prefix]}/jobs"
 
         route "mount MissionControl::Jobs::Engine, at: \"#{mount_path}\""
       end
@@ -67,6 +67,13 @@ module Maquina
         layout_files.each { |f| copy_file f, f }
       end
 
+      # 7b. Backstage dashboard — admin overview at the prefix root, linking to
+      #     the installed engines. Shared with the solid_errors generator, so
+      #     guard every step for idempotency when both run.
+      def create_backstage_dashboard
+        install_backstage_dashboard
+      end
+
       # 8. Custom views
       def copy_views
         return unless options[:copy_views]
@@ -105,6 +112,30 @@ module Maquina
         File.exist?(File.join(destination_root, "bin/rails"))
       end
 
+      # Idempotent install of the shared backstage dashboard (controller, layout,
+      # prefix-aware view, and the prefix-root route). Safe to run from both this
+      # generator and solid_errors.
+      def install_backstage_dashboard
+        unless File.exist?(File.join(destination_root, "app/controllers/backstage_dashboard_controller.rb"))
+          copy_file "app/controllers/backstage_dashboard_controller.rb",
+            "app/controllers/backstage_dashboard_controller.rb"
+        end
+
+        unless File.exist?(File.join(destination_root, "app/views/layouts/admin.html.erb"))
+          copy_file "app/views/layouts/admin.html.erb", "app/views/layouts/admin.html.erb"
+        end
+
+        unless File.exist?(File.join(destination_root, "app/views/backstage_dashboard/index.html.erb"))
+          template "app/views/backstage_dashboard/index.html.erb.tt",
+            "app/views/backstage_dashboard/index.html.erb"
+        end
+
+        routes_path = File.join(destination_root, "config/routes.rb")
+        if File.exist?(routes_path) && !File.read(routes_path).include?("backstage_dashboard#index")
+          route %(get "#{options[:prefix]}" => "backstage_dashboard#index", as: :backstage_dashboard)
+        end
+      end
+
       def layout_files
         layouts_dir = File.join(self.class.source_root, "app/views/layouts/mission_control")
         Dir.glob("**/*.erb", base: layouts_dir).map do |file|

data/lib/generators/maquina/mission_control_jobs/templates/app/controllers/backstage_dashboard_controller.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Admin overview — a backstage surface alongside the SolidErrors and Mission
+# Control Jobs engines, under the same backstage Basic auth.
+#
+# Out of the box it shows the installed engine entry points and an empty metrics
+# area. Populate @metrics in #index with aggregate, non-sensitive counts for
+# your app — counts, not names or per-record detail.
+class BackstageDashboardController < BackstageController
+  layout "admin"
+
+  before_action :require_backstage_credentials
+  before_action :authenticate_backstage
+
+  def index
+    @generated_at = Time.current
+
+    # Add overview metrics here. Each entry renders as a card:
+    #
+    #   @metrics = [
+    #     {label: "Accounts", icon: :folder, value: Account.count, hint: "tenants"},
+    #     {label: "Users", icon: :user, value: User.count, hint: "members"}
+    #   ]
+    #
+    # Keep them aggregate-only. :total and :hint are optional.
+    @metrics = []
+  end
+
+  private
+
+  # Closed (503) until credentials.backstage is set. Without this an unset
+  # username and password are both "", and an empty Basic header matches them.
+  def require_backstage_credentials
+    backstage = Rails.application.credentials.backstage || {}
+    head :service_unavailable if backstage[:username].blank? || backstage[:password].blank?
+  end
+
+  # Same backstage credentials the engines use.
+  def authenticate_backstage
+    authenticate_or_request_with_http_basic("Admin") do |username, password|
+      backstage = Rails.application.credentials.backstage || {}
+
+      ActiveSupport::SecurityUtils.secure_compare(username.to_s, backstage[:username].to_s) &
+        ActiveSupport::SecurityUtils.secure_compare(password.to_s, backstage[:password].to_s)
+    end
+  end
+end

data/lib/generators/maquina/mission_control_jobs/templates/app/views/backstage_dashboard/index.html.erb.tt

@@ -0,0 +1,93 @@
+<div class="py-8">
+  <!-- Header -->
+  <div class="mb-6 flex items-end justify-between border-b border-border pb-4">
+    <h1 class="text-2xl font-bold text-foreground">Overview</h1>
+    <%% if @generated_at %>
+      <p class="font-mono text-[11px] tabular-nums text-muted-foreground">as of <%%= @generated_at.strftime("%H:%M %Z") %></p>
+    <%% end %>
+  </div>
+
+  <!-- Metrics: populate @metrics in BackstageDashboardController#index. Aggregate-only. -->
+  <%% if @metrics.present? %>
+    <div class="grid grid-cols-2 gap-4 lg:grid-cols-4">
+      <%% @metrics.each do |metric| %>
+        <%%= render "components/card" do %>
+          <div class="px-5 py-4">
+            <div class="mb-2 flex items-center gap-1.5 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">
+              <%% if metric[:icon] %><%%= icon_for(metric[:icon], class: "size-3.5") %><%% end %>
+              <%%= metric[:label] %>
+            </div>
+            <div class="font-display text-4xl font-semibold tabular-nums text-foreground">
+              <%%= number_with_delimiter(metric[:value]) %><%% if metric[:total] %><span class="text-xl text-muted-foreground">/<%%= number_with_delimiter(metric[:total]) %></span><%% end %>
+            </div>
+            <%% if metric[:hint] %>
+              <div class="mt-1 text-[11px] tabular-nums text-muted-foreground"><%%= metric[:hint] %></div>
+            <%% end %>
+          </div>
+        <%% end %>
+      <%% end %>
+    </div>
+  <%% else %>
+    <%%= empty_state(
+      title: "No metrics yet",
+      description: "Add aggregate counts in BackstageDashboardController#index to populate this overview.",
+      icon: :layout_dashboard,
+      size: :default
+    ) %>
+  <%% end %>
+
+  <!-- Operations: entry points to the installed engines -->
+  <h2 class="mt-10 mb-3 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">Operations</h2>
+  <div class="grid grid-cols-1 gap-4 sm:grid-cols-2">
+    <%% if defined?(SolidErrors::Engine) %>
+      <%%= link_to "<%= options[:prefix] %>/errors", class: "group block" do %>
+        <%%= render "components/card", css_classes: "transition-shadow hover:shadow-md" do %>
+          <div class="flex items-center gap-4 px-5 py-4">
+            <span class="inline-flex size-10 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground">
+              <%%= icon_for(:triangle_alert, class: "size-5") %>
+            </span>
+            <div class="min-w-0 flex-1">
+              <div class="font-semibold text-foreground">Errors</div>
+              <div class="text-sm text-muted-foreground">Exceptions, backtraces, and resolution</div>
+            </div>
+            <%%= icon_for(:arrow_right, class: "size-4 text-muted-foreground transition-transform group-hover:translate-x-0.5") %>
+          </div>
+        <%% end %>
+      <%% end %>
+    <%% end %>
+
+    <%% if defined?(MissionControl::Jobs::Engine) %>
+      <%%= link_to "<%= options[:prefix] %>/jobs", class: "group block" do %>
+        <%%= render "components/card", css_classes: "transition-shadow hover:shadow-md" do %>
+          <div class="flex items-center gap-4 px-5 py-4">
+            <span class="inline-flex size-10 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground">
+              <%%= icon_for(:inbox, class: "size-5") %>
+            </span>
+            <div class="min-w-0 flex-1">
+              <div class="font-semibold text-foreground">Background jobs</div>
+              <div class="text-sm text-muted-foreground">Queues, workers, and recurring tasks</div>
+            </div>
+            <%%= icon_for(:arrow_right, class: "size-4 text-muted-foreground transition-transform group-hover:translate-x-0.5") %>
+          </div>
+        <%% end %>
+      <%% end %>
+    <%% end %>
+
+    <%% if defined?(Security::AbuseEvent) %>
+      <%%= link_to "<%= options[:prefix] %>/security", class: "group block" do %>
+        <%%= render "components/card", css_classes: "transition-shadow hover:shadow-md" do %>
+          <div class="flex items-center gap-4 px-5 py-4">
+            <span class="inline-flex size-10 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground">
+              <%%= icon_for(:slash, class: "size-5") %>
+            </span>
+            <div class="min-w-0 flex-1">
+              <div class="font-semibold text-foreground">Security</div>
+              <div class="text-sm text-muted-foreground">Throttled, blocked, and banned requests</div>
+            </div>
+            <%%= icon_for(:arrow_right, class: "size-4 text-muted-foreground transition-transform group-hover:translate-x-0.5") %>
+          </div>
+        <%% end %>
+      <%% end %>
+    <%% end %>
+  </div>
+</div>