notificare 0.1.0.alpha.1

data/app/views/active_job/notificare/_notifications.html.erb

@@ -0,0 +1,7 @@
+<%= turbo_stream_from "active_job_notifications", recipient.to_gid_param %>
+<div id="active_job_notifications" class="notificare-inbox">
+  <%= button_to t(".clear_all"), notificare.clear_notifications_path, method: :delete %>
+  <% notifications.each do |notification| %>
+    <%= render "active_job/notificare/notification", notification: notification %>
+  <% end %>
+</div>

data/app/views/active_job/notificare/_progress.html.erb

@@ -0,0 +1,17 @@
+<%= turbo_stream_from "active_job_progress", execution.job_id %>
+<div id="<%= dom_id(execution) %>" class="notificare-progress">
+  <% if execution.progress_total.present? %>
+    <progress class="notificare-progress__bar" value="<%= execution.progress_current %>" max="<%= execution.progress_total %>"></progress>
+    <span class="notificare-progress__label"><%= execution.progress_current %>/<%= execution.progress_total %> (<%= (execution.progress_current.to_f / execution.progress_total * 100).round %>%)</span>
+    <% if execution.current_step.present? %>
+      <span class="notificare-progress__step"><%= execution.current_step %></span>
+    <% end %>
+  <% else %>
+    <% if !execution.failed? %>
+      <span class="notificare-progress__spinner" role="status" aria-label="Loading..."></span>
+    <% end %>
+    <% if execution.current_step.present? %>
+      <span class="notificare-progress__step"><%= execution.current_step %></span>
+    <% end %>
+  <% end %>
+</div>

data/app/views/active_job/notificare/executions/index.html.erb

@@ -0,0 +1,75 @@
+<h1>Job Executions</h1>
+<p class="nf-subtitle">Live registry of background job activity</p>
+
+<%= form_with url: executions_path, method: :get, local: true, class: "nf-filters" do |f| %>
+  <%= f.select :status,
+        [ [ "All statuses", "" ] ] + @statuses.map { |s| [ s.titleize, s ] },
+        { selected: params[:status] } %>
+  <%= f.select :job_class,
+        [ [ "All job classes", "" ] ] + @job_classes.map { |c| [ c, c ] },
+        { selected: params[:job_class] } %>
+  <%= f.submit "Filter" %>
+  <% if params[:status].present? || params[:job_class].present? %>
+    <%= link_to "Clear", executions_path, class: "nf-clear" %>
+  <% end %>
+<% end %>
+
+<div class="nf-card">
+  <% if @executions.any? %>
+    <table class="nf-table">
+      <thead>
+        <tr>
+          <th>Status</th>
+          <th>Job class</th>
+          <th>Job ID</th>
+          <th>Step</th>
+          <th>Progress</th>
+          <th>Started</th>
+          <th>Finished</th>
+        </tr>
+      </thead>
+      <tbody>
+        <% @executions.each do |execution| %>
+          <tr>
+            <td><span class="nf-badge nf-badge--<%= execution.status %>"><%= execution.status %></span></td>
+            <td><%= link_to execution.job_class, execution_path(execution) %></td>
+            <td class="nf-mono"><%= truncate(execution.job_id, length: 22) %></td>
+            <td><%= execution.current_step %></td>
+            <td>
+              <% if execution.progress_total %>
+                <span class="nf-mono"><%= execution.progress_current %> / <%= execution.progress_total %></span>
+              <% end %>
+            </td>
+            <td class="nf-mono"><%= execution.started_at&.strftime("%Y-%m-%d %H:%M:%S") %></td>
+            <td class="nf-mono"><%= execution.completed_at&.strftime("%Y-%m-%d %H:%M:%S") %></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  <% else %>
+    <div class="nf-empty">No executions found.</div>
+  <% end %>
+</div>
+
+<% if @total_pages > 1 %>
+  <nav class="nf-pagination" aria-label="Pagination">
+    <% if @page > 1 %>
+      <%= link_to "← Prev", executions_path(page: @page - 1, status: params[:status], job_class: params[:job_class]) %>
+    <% end %>
+
+    <% window_start = [ 1, @page - 2 ].max %>
+    <% window_end   = [ @total_pages, @page + 2 ].min %>
+    <% (window_start..window_end).each do |p| %>
+      <% if p == @page %>
+        <span class="nf-pagination__current"><%= p %></span>
+      <% else %>
+        <%= link_to p, executions_path(page: p, status: params[:status], job_class: params[:job_class]) %>
+      <% end %>
+    <% end %>
+
+    <% if @page < @total_pages %>
+      <%= link_to "Next →", executions_path(page: @page + 1, status: params[:status], job_class: params[:job_class]) %>
+    <% end %>
+  </nav>
+  <p class="nf-pagination__info"><%= @total_count %> total</p>
+<% end %>

data/app/views/active_job/notificare/executions/show.html.erb

@@ -0,0 +1,66 @@
+<%= link_to "← executions", executions_path, class: "nf-back" %>
+
+<h1><%= @execution.job_class %></h1>
+<p class="nf-subtitle nf-mono"><%= @execution.job_id %></p>
+
+<div class="nf-detail">
+  <div>
+    <div class="nf-card">
+      <div class="nf-card__header">Execution details</div>
+      <div class="nf-card__body">
+        <dl class="nf-kv">
+          <dt>Status</dt>
+          <dd><%= tag.span class: "nf-badge nf-badge--#{@execution.status}" do %><%= @execution.status %><% end %></dd>
+
+          <dt>Current step</dt>
+          <dd><%= @execution.current_step.presence || "—" %></dd>
+
+          <dt>Started at</dt>
+          <dd><%= @execution.started_at&.strftime("%Y-%m-%d %H:%M:%S UTC") || "—" %></dd>
+
+          <dt>Completed at</dt>
+          <dd><%= @execution.completed_at&.strftime("%Y-%m-%d %H:%M:%S UTC") || "—" %></dd>
+        </dl>
+
+        <% if @execution.error.present? %>
+          <div class="nf-error"><%= @execution.error %></div>
+        <% end %>
+      </div>
+    </div>
+  </div>
+
+  <div>
+    <div class="nf-card">
+      <div class="nf-card__header">Live progress</div>
+      <div class="nf-card__body">
+        <%= active_job_notificare(@execution) %>
+      </div>
+    </div>
+  </div>
+</div>
+
+<% if @notifications.any? %>
+  <div class="nf-card">
+    <div class="nf-card__header">Notifications (<%= @notifications.size %>)</div>
+    <table class="nf-table">
+      <thead>
+        <tr>
+          <th>Type</th>
+          <th>Title</th>
+          <th>Description</th>
+          <th>Time</th>
+        </tr>
+      </thead>
+      <tbody>
+        <% @notifications.each do |notification| %>
+          <tr>
+            <td><%= tag.span class: "nf-badge nf-badge--#{notification.event_type}" do %><%= notification.event_type %><% end %></td>
+            <td><%= notification.title %></td>
+            <td><%= notification.description %></td>
+            <td class="nf-mono"><%= notification.created_at.strftime("%Y-%m-%d %H:%M:%S") %></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+<% end %>

data/app/views/active_job/notificare/notifications/clear.turbo_stream.erb

@@ -0,0 +1,3 @@
+<% @notifications.each do |notification| %>
+  <%= turbo_stream.remove dom_id(notification) %>
+<% end %>

data/app/views/active_job/notificare/notifications/dismiss.turbo_stream.erb

@@ -0,0 +1 @@
+<%= turbo_stream.remove dom_id(@notification) %>

data/app/views/active_job/notificare/notifications/read.turbo_stream.erb

@@ -0,0 +1,3 @@
+<%= turbo_stream.replace dom_id(@notification) do %>
+  <%= render "active_job/notificare/notification", notification: @notification %>
+<% end %>

data/app/views/layouts/active_job/notificare/application.html.erb

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Notificare</title>
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= csrf_meta_tags %>
+    <script nonce="<%= content_security_policy_nonce %>">
+      (function(){
+        var t=localStorage.getItem('nf-theme')||(window.matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light');
+        document.documentElement.dataset.theme=t;
+      })();
+    </script>
+    <%= stylesheet_link_tag "active_job/notificare/engine" %>
+    <%= javascript_importmap_tags if respond_to?(:javascript_importmap_tags) %>
+  </head>
+  <body>
+    <header class="nf-header">
+      <a href="<%= executions_path %>" class="nf-brand">
+        <span class="nf-brand__mark" aria-hidden="true">✦</span>
+        Notificare
+      </a>
+      <button class="nf-theme-toggle" id="nf-theme-toggle" aria-label="Toggle colour theme"></button>
+    </header>
+    <div class="nf-folk-strip" aria-hidden="true"></div>
+    <main class="nf-main">
+      <%= yield %>
+    </main>
+    <script nonce="<%= content_security_policy_nonce %>">
+      (function(){
+        var btn=document.getElementById('nf-theme-toggle');
+        function sync(t){ btn.textContent=t==='dark'?'☀':'☾'; btn.title=t==='dark'?'Switch to light':'Switch to dark'; }
+        sync(document.documentElement.dataset.theme);
+        btn.addEventListener('click',function(){
+          var next=document.documentElement.dataset.theme==='dark'?'light':'dark';
+          document.documentElement.dataset.theme=next;
+          localStorage.setItem('nf-theme',next);
+          sync(next);
+        });
+      })();
+    </script>
+  </body>
+</html>

data/config/locales/en.yml

@@ -0,0 +1,7 @@
+en:
+  active_job:
+    notificare:
+      notifications:
+        clear_all: "Clear all"
+        mark_as_read: "Mark as read"
+        dismiss: "Dismiss"

data/config/routes.rb

@@ -0,0 +1,13 @@
+ActiveJob::Notificare::Engine.routes.draw do
+  root to: "executions#index"
+  resources :executions, only: [ :index, :show ]
+
+  resources :notifications, only: [] do
+    member do
+      patch :read
+      patch :dismiss
+    end
+  end
+
+  delete "notifications", to: "notifications#clear", as: :clear_notifications
+end

data/lib/active_job/notificare/concern.rb

@@ -0,0 +1,78 @@
+require "active_support/concern"
+require "active_job/continuation"
+require "active_job/continuable"
+
+module ActiveJob
+  module Notificare
+    extend ActiveSupport::Concern
+
+    included do
+      include ActiveJob::Continuable
+      include StepDSL
+      include Recipient
+    end
+
+    class_methods do
+      # Opt out of the projection. Including the module is the opt-in;
+      # `tracks_progress false` flips it off without removing the include.
+      def tracks_progress(value = true)
+        @tracks_progress = value
+      end
+
+      def tracks_progress?
+        @tracks_progress != false
+      end
+
+      # Declare which lifecycle events auto-write a Notification row.
+      # Accepted values: :completed, :failed (or both).
+      def notify_on(*event_types)
+        @_notificare_notify_on = event_types.map(&:to_sym)
+      end
+
+      def notificare_notify_on
+        @_notificare_notify_on || []
+      end
+
+      # Eagerly opt into recipient enforcement at enqueue time, before any instance
+      # has called notify(...). Use this when you know the job will call notify but
+      # want the ArgumentError to fire on the very first enqueue.
+      def uses_notify!
+        @_uses_notify = true
+      end
+
+      # True if uses_notify! was called explicitly, or after the first instance called
+      # notify(...) during perform (which flips this flag).
+      def uses_notify?
+        @_uses_notify == true
+      end
+    end
+
+    # The polymorphic recipient for notifications. Job authors set this inside
+    # perform (e.g. `self.recipient = recipient`).
+    attr_accessor :recipient
+
+    def progress
+      @progress ||= ProgressHandle.new(job_id)
+    end
+
+    # Write a custom Notification row directly. Safe to call at any point during or
+    # after perform — does not rely on lifecycle hooks (ERD §9 case 5).
+    #
+    # Also flips self.class.uses_notify? to true so subsequent enqueues are subject
+    # to recipient enforcement.
+    def notify(title:, description: nil, metadata: {}, actions: [])
+      self.class.uses_notify!
+      return unless recipient
+
+      Notification.create!(
+        recipient: recipient,
+        job_id: job_id,
+        event_type: "custom",
+        title: title,
+        description: description,
+        metadata: metadata.presence,
+        actions: actions.presence
+      )
+    end
+  end
+end

data/lib/active_job/notificare/engine.rb

@@ -0,0 +1,28 @@
+require "active_job/notificare/projection"
+
+module ActiveJob
+  module Notificare
+    class Engine < ::Rails::Engine
+      isolate_namespace ActiveJob::Notificare
+
+      initializer "active_job.notificare.projection" do
+        ActiveJob::Notificare::Projection.subscribe!
+      end
+
+      initializer "active_job.notificare.helpers" do
+        ActiveSupport.on_load(:action_view) do
+          include ActiveJob::Notificare::ViewHelpers
+        end
+      end
+
+      config.to_prepare do
+        unless ::Notificare.const_defined?(:Execution, false)
+          ::Notificare.const_set(:Execution, ActiveJob::Notificare::Execution)
+        end
+        unless ::Notificare.const_defined?(:Notification, false)
+          ::Notificare.const_set(:Notification, ActiveJob::Notificare::Notification)
+        end
+      end
+    end
+  end
+end

data/lib/active_job/notificare/progress_handle.rb

@@ -0,0 +1,23 @@
+module ActiveJob
+  module Notificare
+    class ProgressHandle
+      def initialize(job_id)
+        @job_id = job_id
+      end
+
+      def total(n)
+        rows = Execution.where(job_id: @job_id).update_all(progress_total: n)
+        if rows == 0
+          Rails.logger.debug { "[notificare] progress.total called before execution row exists for job_id=#{@job_id}" }
+        end
+      end
+
+      def advance!(by = 1)
+        rows = Execution.where(job_id: @job_id).update_all("progress_current = progress_current + #{by.to_i}")
+        if rows == 0
+          Rails.logger.debug { "[notificare] progress.advance! called before execution row exists for job_id=#{@job_id}" }
+        end
+      end
+    end
+  end
+end

data/lib/active_job/notificare/projection.rb

@@ -0,0 +1,145 @@
+module ActiveJob
+  module Notificare
+    module Projection
+      SUBSCRIPTIONS = []
+
+      def self.subscribe!
+        SUBSCRIPTIONS << ActiveSupport::Notifications.subscribe("enqueue.active_job") do |event|
+          job = event.payload[:job]
+          next unless tracks_progress?(job)
+
+          begin
+            Execution.find_or_create_by!(job_id: job.job_id) do |e|
+              e.job_class = job.class.name
+              e.status = "enqueued"
+            end
+          rescue ActiveRecord::RecordNotUnique
+            # Two concurrent projections for the same job_id — uniqueness constraint caught the
+            # duplicate; the other thread won, so just find the existing row.
+            Execution.find_by!(job_id: job.job_id)
+          end
+        end
+
+        SUBSCRIPTIONS << ActiveSupport::Notifications.subscribe("perform_start.active_job") do |event|
+          job = event.payload[:job]
+          next unless tracks_progress?(job)
+
+          execution = Execution.find_by(job_id: job.job_id)
+          next unless execution
+
+          if execution.running?
+            # Resume path (ERD §9 case 3): worker was killed before perform.active_job fired,
+            # leaving status as running. Preserve progress_current and started_at.
+            # No continuation_state column — Continuation owns that (ERD §6).
+            execution.update!(error: nil) if execution.error.present?
+          else
+            execution.update!(status: "running", started_at: Time.current)
+          end
+        end
+
+        # Mirror ActiveJob::Continuation's current step name onto the execution row.
+        SUBSCRIPTIONS << ActiveSupport::Notifications.subscribe("step_started.active_job") do |event|
+          job = event.payload[:job]
+          next unless tracks_progress?(job)
+
+          step = event.payload[:step]
+          Execution.find_by(job_id: job.job_id)&.update!(current_step: step.name.to_s)
+        end
+
+        # ActiveJob::Continuation fires `step.active_job` (not `step_completed`) after each step's
+        # block finishes (whether successfully or with an exception). Only write a notification
+        # when the step completed without error and was not interrupted.
+        SUBSCRIPTIONS << ActiveSupport::Notifications.subscribe("step.active_job") do |event|
+          next if event.payload[:exception_object]
+          next if event.payload[:interrupted]
+
+          job = event.payload[:job]
+          next unless tracks_progress?(job)
+
+          step = event.payload[:step]
+          notify_event = job.respond_to?(:notificare_step_notify_for) ? job.notificare_step_notify_for(step.name) : nil
+          write_step_notification(job, step.name, notify_event) if notify_event
+        end
+
+        SUBSCRIPTIONS << ActiveSupport::Notifications.subscribe("perform.active_job") do |event|
+          job = event.payload[:job]
+          next unless tracks_progress?(job)
+
+          execution = Execution.find_by(job_id: job.job_id)
+          next unless execution
+
+          if (exception = event.payload[:exception_object])
+            execution.update!(status: "failed", completed_at: Time.current, error: exception.message)
+            write_lifecycle_notification(job, :failed, exception.message) if notifies_on?(job, :failed)
+          else
+            execution.update!(status: "completed", completed_at: Time.current)
+            write_lifecycle_notification(job, :completed) if notifies_on?(job, :completed)
+          end
+        end
+      end
+
+      def self.unsubscribe!
+        SUBSCRIPTIONS.each { |s| ActiveSupport::Notifications.unsubscribe(s) }
+        SUBSCRIPTIONS.clear
+      end
+
+      def self.tracks_progress?(job)
+        job.class.respond_to?(:tracks_progress?) && job.class.tracks_progress?
+      end
+      private_class_method :tracks_progress?
+
+      def self.notifies_on?(job, event_type)
+        job.class.respond_to?(:notificare_notify_on) && job.class.notificare_notify_on.include?(event_type)
+      end
+      private_class_method :notifies_on?
+
+      def self.recipient_for(job)
+        job.respond_to?(:recipient) ? job.recipient : nil
+      end
+      private_class_method :recipient_for
+
+      def self.write_lifecycle_notification(job, event_type, description = nil)
+        recipient = recipient_for(job)
+        return unless recipient
+
+        Notification.create!(
+          recipient: recipient,
+          job_id: job.job_id,
+          event_type: event_type.to_s,
+          title: "#{job.class.name} #{event_type}",
+          description: description
+        )
+      end
+      private_class_method :write_lifecycle_notification
+
+      def self.write_step_notification(job, step_name, notify_event)
+        recipient = recipient_for(job)
+        return unless recipient
+
+        Notification.create!(build_step_notification_attrs(job, step_name, notify_event))
+      end
+      private_class_method :write_step_notification
+
+      def self.build_step_notification_attrs(job, step_name, notify_event)
+        base = { recipient: recipient_for(job), job_id: job.job_id, event_type: "custom" }
+
+        case notify_event
+        when Symbol
+          base.merge(
+            title: "#{job.class.name}: #{notify_event}",
+            metadata: { "event" => notify_event.to_s }
+          )
+        when Hash
+          event = notify_event[:event] || step_name
+          extra_metadata = notify_event[:metadata]&.transform_keys(&:to_s) || {}
+          base.merge(
+            title: notify_event[:title] || "#{job.class.name}: #{event}",
+            description: notify_event[:description],
+            metadata: { "event" => event.to_s }.merge(extra_metadata)
+          )
+        end
+      end
+      private_class_method :build_step_notification_attrs
+    end
+  end
+end

data/lib/active_job/notificare/recipient.rb

@@ -0,0 +1,39 @@
+require "active_support/concern"
+
+module ActiveJob
+  module Notificare
+    # around_enqueue guard: raises ArgumentError before the adapter receives the job
+    # when the job opts into notifications but no `recipient:` keyword was supplied.
+    #
+    # Opt-in triggers (any one is sufficient):
+    #   - notify_on declared on the class
+    #   - uses_notify! called on the class (or uses_notify? already true from a prior run)
+    #   - step(notify:) was called in a prior run (has_step_notifications? is true)
+    module Recipient
+      extend ActiveSupport::Concern
+
+      included do
+        around_enqueue :enforce_recipient!
+      end
+
+      private
+
+      def enforce_recipient!
+        if needs_recipient? && !recipient_argument_present?
+          raise ArgumentError, "#{self.class.name} requires a `recipient:` keyword argument"
+        end
+        yield
+      end
+
+      def needs_recipient?
+        self.class.notificare_notify_on.any? ||
+          self.class.uses_notify? ||
+          self.class.has_step_notifications?
+      end
+
+      def recipient_argument_present?
+        arguments.any? { |arg| arg.is_a?(Hash) && (arg.key?(:recipient) || arg.key?("recipient")) }
+      end
+    end
+  end
+end

data/lib/active_job/notificare/step_dsl.rb

@@ -0,0 +1,42 @@
+require "active_support/concern"
+
+module ActiveJob
+  module Notificare
+    # Wraps ActiveJob::Continuation#step with Notificare-specific kwargs.
+    #
+    # `notify:` declares a state-machine event tied to the step's successful completion.
+    # The value is stashed on the job instance keyed by step name; the projection reads it
+    # off `event.payload[:job]` at `step_completed.active_job` time. Actual Notification
+    # row writes land in ticket 06.
+    module StepDSL
+      extend ActiveSupport::Concern
+
+      included do
+        extend ClassMethods
+      end
+
+      module ClassMethods
+        # True after the first run of any instance that called step(notify:).
+        # Used by Recipient to enforce recipient: presence on subsequent enqueues.
+        def has_step_notifications?
+          @_has_step_notifications == true
+        end
+      end
+
+      def step(name, *args, notify: nil, **opts, &block)
+        if notify
+          self.class.instance_variable_set(:@_has_step_notifications, true)
+          @_notificare_step_notify ||= {}
+          @_notificare_step_notify[name.to_sym] = notify
+        end
+        super(name, *args, **opts, &block)
+      end
+
+      # Read by Projection's `step_completed.active_job` handler.
+      def notificare_step_notify_for(step_name)
+        return nil unless defined?(@_notificare_step_notify) && @_notificare_step_notify
+        @_notificare_step_notify[step_name.to_sym]
+      end
+    end
+  end
+end

data/lib/active_job/notificare/version.rb

@@ -0,0 +1,5 @@
+module ActiveJob
+  module Notificare
+    VERSION = "0.1.0.alpha.1"
+  end
+end

data/lib/active_job/notificare.rb

@@ -0,0 +1,14 @@
+require "active_job/notificare/version"
+require "active_job/notificare/engine"
+require "active_job/notificare/progress_handle"
+require "active_job/notificare/step_dsl"
+require "active_job/notificare/recipient"
+require "active_job/notificare/concern"
+
+module ActiveJob
+  module Notificare
+    mattr_accessor :current_recipient_proc
+    mattr_accessor :parent_controller, default: "ApplicationController"
+    mattr_accessor :authenticate_with
+  end
+end