rake_audit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9a179a34a78178c7a695d637e8ff9479d016258a2d7d69cb62e3b8ac33b557b7
+  data.tar.gz: 6c8cce01a8857dd1d3e50d32bdffe0a2f8d603460018d1aa70d59e01367496f4
+SHA512:
+  metadata.gz: 50022c1e1011ad9143446c28f3b23a4563d1fc47251985e6bb81070f3f39793f898f42a83ffaf85d22cfad256fbbcef7e03b3e8fc163733fedaedabd4d80b620
+  data.tar.gz: 165a918cfeccc962b3f86342e3306b6efb8c54c7891103d674527192760442469888e553ffc38ec11f83e76c8a69433197bd7a1db2c057ef65f551d360fa9bfe

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-03
+
+Initial public release.
+
+### Added
+
+- **Automatic Rake auditing** — a prepended `Rake::Task#execute` hook records the
+  task name, arguments, start/finish times, duration, status (success/failure), and
+  error details for every Rake task execution, without altering task behavior.
+- **Pluggable storage adapters** built on a common `RakeAudit::Adapters::Base`:
+  - `ActiveRecordAdapter` — persists executions to a `rake_task_executions` table.
+  - `RedisAdapter` — stores executions as JSON in the `rake_audit:executions` list.
+  - `MongoAdapter` — stores executions in the `rake_task_executions` collection.
+  - Custom adapters are supported by subclassing `Base` and implementing `#save`.
+- **Configurable capture** of hostname, PID, Ruby version, and Rails environment,
+  plus a configurable logger for adapter save failures.
+- **Rails Web UI** (mountable engine) providing:
+  - A paginated, filterable execution list (Kaminari-backed).
+  - A dashboard with aggregate stats (totals, success/failure counts, average
+    duration, top failed tasks).
+  - A per-execution detail view.
+  - Optional access control via a configurable `authenticate_with` lambda.
+- **Rails install generator** (`rails generate rake_audit:install`) that copies an
+  initializer and a timestamped ActiveRecord migration.
+- **Rails-free operation** — the gem loads and records outside Rails; Kaminari's
+  ActiveRecord/ActionView integrations stay inert until those libraries are present.
+
+[Unreleased]: https://github.com/eraxel-dev/rake_audit/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/eraxel-dev/rake_audit/releases/tag/v0.1.0

data/LICENSE

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

data/README.md

@@ -0,0 +1,235 @@
+# Rake Audit
+
+**Full Audit Trail for Every Rake Execution**
+
+RakeAudit automatically records who ran what, when it started, when it finished, how long it took, and whether it succeeded or failed.
+
+Built for modern Rails applications, it supports pluggable storage adapters including ActiveRecord, Redis, MongoDB, and custom backends.
+
+Gain a complete historical record of your operational tasks without touching your existing codebase.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Setup](#setup)
+  - [Rails (ActiveRecord)](#rails-activerecord)
+  - [Redis](#redis)
+  - [MongoDB](#mongodb)
+  - [Plain Ruby / Standalone Rake](#plain-ruby--standalone-rake)
+- [Configuration](#configuration)
+- [Web UI](#web-ui)
+- [Custom Adapter](#custom-adapter)
+- [Example Usages](#example-usages)
+
+---
+
+## Installation
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem 'rake_audit'
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+Or install directly:
+
+```sh
+gem install rake_audit
+```
+
+---
+
+## Setup
+
+### Rails (ActiveRecord)
+
+Run the install generator to create the initializer and database migration:
+
+```sh
+rails generate rake_audit:install
+```
+
+This copies `config/initializers/rake_audit.rb` and a timestamped migration to `db/migrate/`. Run the migration:
+
+```sh
+rails db:migrate
+```
+
+Then enable the ActiveRecord adapter in `config/initializers/rake_audit.rb`:
+
+```ruby
+RakeAudit.configure do |config|
+  config.adapter = RakeAudit::Adapters::ActiveRecordAdapter.new
+end
+```
+
+### Redis
+
+Provide a connected `Redis` client:
+
+```ruby
+require 'redis'
+
+RakeAudit.configure do |config|
+  config.adapter = RakeAudit::Adapters::RedisAdapter.new(
+    client: Redis.new(url: ENV['REDIS_URL'])
+  )
+end
+```
+
+Execution records are stored as JSON in the `rake_audit:executions` list key.
+
+### MongoDB
+
+Provide a connected `Mongo::Client`:
+
+```ruby
+require 'mongo'
+
+RakeAudit.configure do |config|
+  config.adapter = RakeAudit::Adapters::MongoAdapter.new(
+    client: Mongo::Client.new(ENV['MONGODB_URI'])
+  )
+end
+```
+
+Records are stored in the `rake_task_executions` collection.
+
+### Plain Ruby / Standalone Rake
+
+RakeAudit works outside Rails. Require the gem and configure an adapter before tasks run:
+
+```ruby
+require 'rake_audit'
+
+RakeAudit.configure do |config|
+  config.adapter = MyCustomAdapter.new
+end
+
+RakeAudit.install!
+```
+
+---
+
+## Configuration
+
+All options with their defaults:
+
+```ruby
+RakeAudit.configure do |config|
+  # Storage adapter — required to enable recording.
+  config.adapter = RakeAudit::Adapters::ActiveRecordAdapter.new
+
+  # Logger for adapter save failures (defaults to Rails.logger or $stdout).
+  config.logger = Rails.logger
+
+  # Fields captured on each execution record.
+  config.capture_hostname     = true   # machine hostname
+  config.capture_pid          = true   # process ID
+  config.capture_ruby_version = true   # Ruby version string
+  config.capture_rails_env    = true   # Rails.env value
+
+  # Web UI (see below).
+  config.web_ui_enabled    = true
+  config.authenticate_with = ->(controller) { controller.authenticate_admin! }
+end
+```
+
+Without an adapter, RakeAudit loads silently and records nothing.
+
+---
+
+## Web UI
+
+Mount the engine in `config/routes.rb` to enable the built-in dashboard and execution list:
+
+```ruby
+Rails.application.routes.draw do
+  mount RakeAudit::Engine, at: '/rake_audit'
+end
+```
+
+| Path | Description |
+|---|---|
+| `/rake_audit` | Paginated execution list with filters |
+| `/rake_audit/dashboard` | Aggregate stats (total, success/failure counts, avg duration) |
+| `/rake_audit/executions/:id` | Detail view for a single execution |
+
+To restrict access, set `authenticate_with` to a lambda that calls your authentication helper:
+
+```ruby
+config.authenticate_with = ->(controller) { controller.authenticate_admin! }
+```
+
+---
+
+## Custom Adapter
+
+Subclass `RakeAudit::Adapters::Base` and implement `#save`. Implement the remaining query methods to support the Web UI:
+
+```ruby
+class MyAdapter < RakeAudit::Adapters::Base
+  def save(record)
+    # record is a RakeAudit::TaskExecutionRecord
+    # record.to_h returns a plain hash of all fields
+    MyStore.insert(record.to_h)
+  end
+
+  # Optional — required only when using the Web UI.
+  def query(filters: {}, page: nil, per_page: 25) = raise NotImplementedError
+  def find(id)                                     = raise NotImplementedError
+  def count                                        = raise NotImplementedError
+  def count_by_status(status)                      = raise NotImplementedError
+  def average_duration_ms                          = raise NotImplementedError
+  def top_failed_tasks(limit: 10)                  = raise NotImplementedError
+end
+
+RakeAudit.configure { |c| c.adapter = MyAdapter.new }
+```
+
+---
+
+## Example Usages
+
+**Query executions directly (ActiveRecord adapter)**
+
+```ruby
+# All executions for a task, newest first.
+RakeAudit::TaskExecution.where(task_name: 'db:migrate').order(started_at: :desc)
+
+# Failed executions in the last 24 hours.
+RakeAudit::TaskExecution.where(status: 'failure')
+                        .where(started_at: 24.hours.ago..)
+```
+
+**Check stats programmatically**
+
+```ruby
+adapter = RakeAudit.config.adapter
+stats   = adapter.stats
+# => { total: 1482, success_count: 1470, failure_count: 12,
+#      average_duration_ms: 843.2, top_failed_tasks: [["db:seed", 7], ...] }
+```
+
+**Reset configuration in tests**
+
+```ruby
+RSpec.configure do |config|
+  config.after { RakeAudit.reset_config! }
+end
+```
+
+**Disable the Web UI for API-only apps**
+
+```ruby
+RakeAudit.configure do |config|
+  config.adapter        = RakeAudit::Adapters::ActiveRecordAdapter.new
+  config.web_ui_enabled = false
+end
+```

data/app/controllers/rake_audit/application_controller.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RakeAudit
+  # Base controller for every RakeAudit Web UI page.
+  #
+  # It installs the pluggable authentication hook as a +before_action+. When the
+  # host application has configured {RakeAudit::Configuration#authenticate_with}
+  # with a callable, that callable is run in the controller instance's context on
+  # every request (so it may call host helpers such as +authenticate_admin!+ or
+  # +redirect_to+). When +authenticate_with+ is +nil+, the hook is a no-op and
+  # all pages are publicly accessible.
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+
+    before_action :authenticate!
+    rescue_from RakeAudit::RecordNotFound, with: :record_not_found
+
+    private
+
+    # Run the configured authentication callable, if any, in the context of this
+    # controller instance. The controller is also passed as the block argument so
+    # procs may be written as +->(controller) { ... }+ or use +self+ directly.
+    #
+    # @return [void]
+    def authenticate!
+      callable = RakeAudit.config.authenticate_with
+      return unless callable
+
+      instance_exec(self, &callable)
+    end
+
+    # Returns the configured adapter. Falls back to a fresh ActiveRecordAdapter
+    # when none is set so existing apps keep working without explicit configuration.
+    #
+    # @return [RakeAudit::Adapters::Base]
+    def web_adapter
+      RakeAudit.config.adapter || default_web_adapter
+    end
+
+    def default_web_adapter
+      require 'rake_audit/adapters/active_record_adapter'
+      RakeAudit.config.logger.warn(
+        '[RakeAudit] config.adapter is nil — falling back to ActiveRecordAdapter. ' \
+        'Set RakeAudit.configure { |c| c.adapter = ... } in your initializer to silence this warning.'
+      )
+      RakeAudit::Adapters::ActiveRecordAdapter.new
+    end
+
+    def record_not_found
+      head :not_found
+    end
+  end
+end

data/app/controllers/rake_audit/dashboard_controller.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RakeAudit
+  # Renders the dashboard: six aggregate metrics plus the ten task names with
+  # the most failures. All data access is delegated to +web_adapter+ so the
+  # controller is backend-agnostic (ActiveRecord, Redis, Mongo, …).
+  class DashboardController < ApplicationController
+    # Compute the dashboard aggregates and expose them as instance variables.
+    # All five metrics are fetched via a single +web_adapter.stats+ call so
+    # adapters can compute them in one pass (e.g. one Redis LRANGE instead of five).
+    #
+    # @return [void]
+    def index
+      s = web_adapter.stats
+      @total               = s[:total]
+      @success_count       = s[:success_count]
+      @failure_count       = s[:failure_count]
+      @failure_rate        = failure_rate(@failure_count, @total)
+      @average_duration_ms = s[:average_duration_ms]
+      @top_failed_tasks    = s[:top_failed_tasks]
+    end
+
+    private
+
+    # Percentage of executions that failed, guarding against division by zero.
+    #
+    # @param failures [Integer]
+    # @param total [Integer]
+    # @return [Float]
+    def failure_rate(failures, total)
+      return 0.0 if total.zero?
+
+      failures / total.to_f * 100
+    end
+  end
+end

data/app/controllers/rake_audit/executions_controller.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RakeAudit
+  # Lists recorded task executions (with filtering + pagination) and shows the
+  # detail of a single execution. All data access is delegated to +web_adapter+
+  # so the controller is backend-agnostic (ActiveRecord, Redis, Mongo, …).
+  class ExecutionsController < ApplicationController
+    # Newest-first, filtered, paginated list of executions.
+    #
+    # @return [void]
+    def index
+      @executions = web_adapter.query(filters: filter_params, page: params[:page])
+    end
+
+    # Detail of one execution, looked up by id.
+    #
+    # @return [void]
+    def show
+      @execution = web_adapter.find(params[:id])
+    end
+
+    private
+
+    # Build a filter hash from request params, omitting any blank values so
+    # adapters can safely check +filters.key?(col)+ without blank-value guards.
+    #
+    # @return [Hash]
+    def filter_params
+      {
+        task_name: params[:task_name],
+        status: params[:status],
+        hostname: params[:hostname],
+        rails_env: params[:rails_env],
+        from: params[:from],
+        to: params[:to]
+      }.reject { |_, v| v.blank? }
+    end
+  end
+end

data/app/models/rake_audit/task_execution.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RakeAudit
+  # ActiveRecord model backing the +rake_task_executions+ table.
+  #
+  # This is the persistence target of {RakeAudit::Adapters::ActiveRecordAdapter},
+  # which calls +TaskExecution.create!(record.to_h)+ with the twelve fields a
+  # {RakeAudit::TaskExecutionRecord} serializes. The four columns that are
+  # always populated for a completed execution carry presence validations so a
+  # malformed record fails loudly rather than persisting a partial row.
+  #
+  # When the host application defines an +ApplicationRecord+ the model inherits
+  # from it (picking up the app's connection and conventions); otherwise it
+  # falls back to +ActiveRecord::Base+ so the gem also works in a plain
+  # ActiveRecord setup without Rails.
+  class TaskExecution < (defined?(ApplicationRecord) ? ApplicationRecord : ActiveRecord::Base)
+    self.table_name = 'rake_task_executions'
+
+    # Treat +arguments+ as JSON on every backend so a Hash round-trips to a Hash.
+    # On PostgreSQL/MySQL the column is natively json(b); on SQLite it is +text+,
+    # where without an explicit JSON type a Hash would be stored via Ruby's
+    # +to_s+ and read back as a String. +ActiveRecord::Type::Json+ casts Hash to
+    # JSON on write and back on read for both column kinds, needs no database
+    # connection at load time, and never raises — unlike +serialize+, which
+    # rejects a natively JSON-typed column.
+    attribute :arguments, ActiveRecord::Type::Json.new
+
+    validates :task_name, presence: true
+    validates :status, presence: true
+    validates :started_at, presence: true
+    validates :finished_at, presence: true
+  end
+end

data/app/views/layouts/rake_audit/application.html.erb

@@ -0,0 +1,70 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>RakeAudit</title>
+    <style>
+      :root { color-scheme: light dark; }
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+        line-height: 1.5;
+        color: #1f2933;
+        background: #f5f7fa;
+      }
+      header.rake-audit-bar {
+        background: #1f2933;
+        color: #fff;
+        padding: 0.75rem 1.5rem;
+        display: flex;
+        align-items: center;
+        gap: 1.5rem;
+      }
+      header.rake-audit-bar a { color: #cbd2d9; text-decoration: none; font-weight: 600; }
+      header.rake-audit-bar a:hover { color: #fff; }
+      header.rake-audit-bar .brand { color: #fff; font-size: 1.1rem; }
+      main { padding: 1.5rem; max-width: 1100px; margin: 0 auto; }
+      h1 { font-size: 1.4rem; margin-top: 0; }
+      table { width: 100%; border-collapse: collapse; background: #fff; }
+      th, td { text-align: left; padding: 0.5rem 0.75rem; border-bottom: 1px solid #e4e7eb; }
+      th { background: #f0f4f8; font-size: 0.8rem; text-transform: uppercase; letter-spacing: 0.03em; }
+      .cards { display: flex; flex-wrap: wrap; gap: 1rem; margin-bottom: 1.5rem; }
+      .card {
+        background: #fff;
+        border: 1px solid #e4e7eb;
+        border-radius: 8px;
+        padding: 1rem 1.25rem;
+        min-width: 150px;
+        flex: 1;
+      }
+      .card .label { font-size: 0.75rem; text-transform: uppercase; color: #7b8794; }
+      .card .value { font-size: 1.6rem; font-weight: 700; }
+      form.filters { background: #fff; border: 1px solid #e4e7eb; border-radius: 8px; padding: 1rem; margin-bottom: 1.5rem; }
+      form.filters .row { display: flex; flex-wrap: wrap; gap: 0.75rem; align-items: flex-end; }
+      form.filters label { display: flex; flex-direction: column; font-size: 0.75rem; color: #52606d; gap: 0.25rem; }
+      form.filters input, form.filters select { padding: 0.35rem 0.5rem; border: 1px solid #cbd2d9; border-radius: 4px; }
+      form.filters button { padding: 0.45rem 1rem; border: 0; border-radius: 4px; background: #2563eb; color: #fff; cursor: pointer; }
+      .status-success { color: #057a55; font-weight: 600; }
+      .status-failure { color: #c81e1e; font-weight: 600; }
+      .section { background: #fff; border: 1px solid #e4e7eb; border-radius: 8px; padding: 1rem 1.25rem; margin-bottom: 1rem; }
+      .section h2 { font-size: 1rem; margin-top: 0; }
+      dl { display: grid; grid-template-columns: max-content 1fr; gap: 0.35rem 1rem; margin: 0; }
+      dt { font-weight: 600; color: #52606d; }
+      pre { background: #f0f4f8; padding: 0.75rem; border-radius: 4px; overflow-x: auto; margin: 0; }
+      .pagination { margin-top: 1rem; }
+      .pagination a, .pagination span { padding: 0.25rem 0.5rem; }
+    </style>
+  </head>
+  <body>
+    <header class="rake-audit-bar">
+      <span class="brand">RakeAudit</span>
+      <%= link_to "Executions", executions_path %>
+      <%= link_to "Dashboard", dashboard_path %>
+    </header>
+    <main>
+      <%= yield %>
+    </main>
+  </body>
+</html>

data/app/views/rake_audit/dashboard/index.html.erb

@@ -0,0 +1,48 @@
+<h1>Dashboard</h1>
+
+<section class="cards">
+  <div class="card">
+    <div class="label">Total</div>
+    <div class="value"><%= @total %></div>
+  </div>
+  <div class="card">
+    <div class="label">Success</div>
+    <div class="value"><%= @success_count %></div>
+  </div>
+  <div class="card">
+    <div class="label">Failure</div>
+    <div class="value"><%= @failure_count %></div>
+  </div>
+  <div class="card">
+    <div class="label">Failure Rate</div>
+    <div class="value"><%= format("%.1f%%", @failure_rate) %></div>
+  </div>
+  <div class="card">
+    <div class="label">Avg Duration (ms)</div>
+    <div class="value"><%= @average_duration_ms ? format("%.1f", @average_duration_ms) : "—" %></div>
+  </div>
+</section>
+
+<section class="section">
+  <h2>Top 10 Failed Tasks</h2>
+  <% if @top_failed_tasks.any? %>
+    <table>
+      <thead>
+        <tr>
+          <th>Task Name</th>
+          <th>Failure Count</th>
+        </tr>
+      </thead>
+      <tbody>
+        <% @top_failed_tasks.each do |task_name, failure_count| %>
+          <tr>
+            <td><%= task_name %></td>
+            <td><%= failure_count %></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  <% else %>
+    <p>No failed tasks recorded.</p>
+  <% end %>
+</section>

data/app/views/rake_audit/executions/index.html.erb

@@ -0,0 +1,74 @@
+<h1>Executions</h1>
+
+<%= form_with url: executions_path, method: :get, class: "filters" do |f| %>
+  <div class="row">
+    <label>
+      Task Name
+      <%= f.text_field :task_name, value: params[:task_name] %>
+    </label>
+    <label>
+      Status
+      <%= f.select :status,
+            options_for_select(
+              [["All", ""], ["Success", "success"], ["Failure", "failure"]],
+              params[:status]
+            ) %>
+    </label>
+    <label>
+      Hostname
+      <%= f.text_field :hostname, value: params[:hostname] %>
+    </label>
+    <label>
+      Rails Env
+      <%= f.text_field :rails_env, value: params[:rails_env] %>
+    </label>
+    <label>
+      From
+      <%= f.date_field :from, value: params[:from] %>
+    </label>
+    <label>
+      To
+      <%= f.date_field :to, value: params[:to] %>
+    </label>
+    <button type="submit">Filter</button>
+  </div>
+<% end %>
+
+<table>
+  <thead>
+    <tr>
+      <th>Task Name</th>
+      <th>Status</th>
+      <th>Duration (ms)</th>
+      <th>Started At</th>
+      <th>Hostname</th>
+      <th>Rails Env</th>
+      <th></th>
+    </tr>
+  </thead>
+  <tbody>
+    <% if @executions.any? %>
+      <% @executions.each do |execution| %>
+        <tr>
+          <td><%= execution.task_name %></td>
+          <td class="status-<%= execution.status %>"><%= execution.status %></td>
+          <td><%= execution.duration_ms %></td>
+          <td><%= execution.started_at %></td>
+          <td><%= execution.hostname %></td>
+          <td><%= execution.rails_env %></td>
+          <td><%= link_to "View", execution_path(execution) %></td>
+        </tr>
+      <% end %>
+    <% else %>
+      <tr>
+        <td colspan="7">No executions found.</td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>
+
+<% if @executions.respond_to?(:current_page) %>
+  <div class="pagination">
+    <%= paginate @executions if respond_to?(:paginate) %>
+  </div>
+<% end %>