script_tracker 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6c4624d6b1fc0ede5e5691a6ec4b2ced79513620505434524b9d1d980e93d4ca
+  data.tar.gz: 427a3b57e4fe3436db63864e7a9d323f285c4ad5d1c763c15813a9da92c2d43d
+SHA512:
+  metadata.gz: 776ff4218886ee763f1b93d8212dfae35c68fa2f685f89a2664d642b4934ace4a1a0c3260bd692b7688c3cfc58864dd812329f24161ac91462b5d2ee92cf183a
+  data.tar.gz: 1ce7a1b8dc3b65888dbe2e9117b4cb06b3e31d0ff24f195d2e4bdb66d9b1782a2bd2441df09b66ff2aa4e8cb9ace86068bd0bb5af9c81051b2a90d325f1be7cf

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-01-17
+
+### Added
+- Initial release of ScriptTracker
+- Script execution tracking with status management
+- Transaction support for script execution
+- Built-in logging and progress tracking
+- Batch processing helpers
+- Timeout support for long-running scripts
+- Stale script cleanup functionality
+- Rake tasks for managing scripts:
+  - `scripts:create` - Create new scripts
+  - `scripts:run` - Run pending scripts
+  - `scripts:status` - View script status
+  - `scripts:rollback` - Rollback scripts
+  - `scripts:cleanup` - Cleanup stale scripts
+- Comprehensive RSpec test suite
+- Full documentation and examples
+
+[Unreleased]: https://github.com/blink-global/script_tracker/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/blink-global/script_tracker/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Blink
+
+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,276 @@
+# ScriptTracker
+
+ScriptTracker is a Ruby gem that provides a migration-like system for managing one-off scripts in Rails applications. It tracks script execution history, provides transaction support, and includes built-in logging and progress tracking.
+
+## Features
+
+- **Execution Tracking**: Automatically tracks which scripts have been run and their status
+- **Transaction Support**: Wraps script execution in database transactions
+- **Status Management**: Track scripts as success, failed, running, or skipped
+- **Built-in Logging**: Convenient logging methods with timestamps
+- **Batch Processing**: Helper methods for processing large datasets efficiently
+- **Timeout Support**: Configure custom timeouts for long-running scripts
+- **Stale Script Cleanup**: Automatically identify and cleanup stuck scripts
+- **Migration Generator**: Generate timestamped script files with templates
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'script_tracker'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install script_tracker
+```
+
+## Setup
+
+1. Install the gem using the generator:
+
+```bash
+rails generate script_tracker:install
+```
+
+This will:
+- Create a migration for the `executed_scripts` table
+- Create the `lib/scripts` directory for your scripts
+
+2. Run the migration:
+
+```bash
+rails db:migrate
+```
+
+3. (Optional) Configure the scripts directory in an initializer:
+
+```ruby
+# config/initializers/script_tracker.rb
+ScriptTracker.configure do |config|
+  config.scripts_path = Rails.root.join('lib', 'scripts')
+end
+```
+
+## Usage
+
+### Creating a New Script
+
+Generate a new script with a descriptive name:
+
+```bash
+rake scripts:create["update user preferences"]
+```
+
+This creates a timestamped script file in `lib/scripts/`:
+
+```ruby
+# lib/scripts/20231117120000_update_user_preferences.rb
+module Scripts
+  class UpdateUserPreferences < ScriptTracker::Base
+    def self.execute
+      log "Starting script: update user preferences"
+
+      # Your script logic here
+      User.find_each do |user|
+        user.update!(preferences: { theme: 'dark' })
+      end
+
+      log "Script completed successfully"
+    end
+  end
+end
+```
+
+### Running Scripts
+
+Run all pending (not yet executed) scripts:
+
+```bash
+rake scripts:run
+```
+
+### Checking Script Status
+
+View the status of all scripts:
+
+```bash
+rake scripts:status
+```
+
+Output:
+```
+Scripts:
+  [SUCCESS] 20231117120000_update_user_preferences.rb (2.5s)
+  [PENDING] 20231117130000_cleanup_old_data.rb
+```
+
+### Rolling Back a Script
+
+Remove a script from execution history (allows it to be run again):
+
+```bash
+rake scripts:rollback[20231117120000_update_user_preferences.rb]
+```
+
+### Cleaning Up Stale Scripts
+
+Mark scripts stuck in "running" status as failed:
+
+```bash
+rake scripts:cleanup
+```
+
+## Advanced Features
+
+### Skipping Scripts
+
+Skip a script execution conditionally:
+
+```ruby
+module Scripts
+  class ConditionalUpdate < ScriptTracker::Base
+    def self.execute
+      if User.where(needs_update: true).count.zero?
+        skip! "No users need updating"
+      end
+
+      # Your script logic here
+    end
+  end
+end
+```
+
+### Custom Timeout
+
+Override the default 5-minute timeout:
+
+```ruby
+module Scripts
+  class LongRunningScript < ScriptTracker::Base
+    def self.timeout
+      3600 # 1 hour in seconds
+    end
+
+    def self.execute
+      # Long-running logic here
+    end
+  end
+end
+```
+
+### Batch Processing
+
+Process large datasets efficiently:
+
+```ruby
+module Scripts
+  class ProcessUsers < ScriptTracker::Base
+    def self.execute
+      users = User.where(processed: false)
+
+      process_in_batches(users, batch_size: 1000) do |user|
+        user.update!(processed: true)
+      end
+    end
+  end
+end
+```
+
+### Progress Logging
+
+Track progress during execution:
+
+```ruby
+module Scripts
+  class DataMigration < ScriptTracker::Base
+    def self.execute
+      total = User.count
+      processed = 0
+
+      User.find_each do |user|
+        # Process user
+        processed += 1
+        log_progress(processed, total) if (processed % 100).zero?
+      end
+    end
+  end
+end
+```
+
+## API Reference
+
+### ScriptTracker::Base
+
+Base class for all scripts.
+
+**Class Methods:**
+
+- `execute` - Implement this method with your script logic (required)
+- `run` - Execute the script with transaction and error handling
+- `timeout` - Override to set custom timeout (default: 300 seconds)
+- `skip!(reason)` - Skip script execution with optional reason
+- `log(message, level: :info)` - Log a message with timestamp
+- `log_progress(current, total, message = nil)` - Log progress percentage
+- `process_in_batches(relation, batch_size: 1000, &block)` - Process records in batches
+
+### ScriptTracker::ExecutedScript
+
+ActiveRecord model for tracking script execution.
+
+**Scopes:**
+
+- `successful` - Scripts that completed successfully
+- `failed` - Scripts that failed
+- `running` - Scripts currently running
+- `skipped` - Scripts that were skipped
+- `completed` - Scripts that finished (success or failed)
+- `ordered` - Order by execution time ascending
+- `recent_first` - Order by execution time descending
+
+**Class Methods:**
+
+- `executed?(filename)` - Check if a script has been executed
+- `mark_as_running(filename)` - Mark a script as running
+- `cleanup_stale_running_scripts(older_than: 1.hour.ago)` - Clean up stale scripts
+
+**Instance Methods:**
+
+- `mark_success!(output, duration)` - Mark as successful
+- `mark_failed!(error, duration)` - Mark as failed
+- `mark_skipped!(output, duration)` - Mark as skipped
+- `success?`, `failed?`, `running?`, `skipped?` - Status predicates
+- `formatted_duration` - Human-readable duration
+- `formatted_output` - Truncated output text
+- `timeout_seconds` - Get timeout value
+- `timed_out?` - Check if script has timed out
+
+## Rake Tasks
+
+- `rake scripts:create[description]` - Create a new script
+- `rake scripts:run` - Run all pending scripts
+- `rake scripts:status` - Show status of all scripts
+- `rake scripts:rollback[filename]` - Rollback a script
+- `rake scripts:cleanup` - Cleanup stale running scripts
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/blink-global/script_tracker.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/script_tracker/base.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module ScriptTracker
+  class Base
+    class ScriptSkipped < StandardError; end
+
+    class << self
+      # Default timeout: 5 minutes
+      # Override in subclass to customize:
+      #   def self.timeout
+      #     3600 # 1 hour
+      #   end
+      def timeout
+        300 # 5 minutes in seconds
+      end
+
+      def run(executed_script_record = nil)
+        require 'timeout'
+        start_time = Time.current
+        timeout_seconds = timeout
+
+        # Check timeout before execution if we have a record
+        if executed_script_record&.timed_out?
+          duration = Time.current - start_time
+          error_message = "Script timed out after #{timeout_seconds} seconds"
+          log(error_message, level: :error)
+          return { success: false, skipped: false, output: error_message, duration: duration }
+        end
+
+        begin
+          result = nil
+
+          # Wrap execution in timeout if specified
+          if timeout_seconds && timeout_seconds > 0
+            Timeout.timeout(timeout_seconds, ScriptTimeoutError) do
+              result = execute_with_transaction
+            end
+          else
+            result = execute_with_transaction
+          end
+
+          duration = Time.current - start_time
+          output = "Script completed successfully in #{duration.round(2)}s"
+          log(output)
+
+          { success: true, skipped: false, output: output, duration: duration }
+        rescue ScriptSkipped => e
+          duration = Time.current - start_time
+          output = e.message.presence || 'Script was skipped (no action needed)'
+          { success: false, skipped: true, output: output, duration: duration }
+        rescue ScriptTimeoutError => e
+          duration = Time.current - start_time
+          error_message = "Script execution exceeded timeout of #{timeout_seconds} seconds"
+          log(error_message, level: :error)
+          { success: false, skipped: false, output: error_message, duration: duration }
+        rescue StandardError => e
+          duration = Time.current - start_time
+          error_message = "#{e.class}: #{e.message}\n#{e.backtrace.first(10).join("\n")}"
+          log(error_message, level: :error)
+
+          { success: false, skipped: false, output: error_message, duration: duration }
+        end
+      end
+
+      def execute_with_transaction
+        ActiveRecord::Base.transaction do
+          execute
+        end
+      end
+
+      class ScriptTimeoutError < StandardError; end
+
+      def execute
+        raise NotImplementedError, 'Subclasses must implement the execute method'
+      end
+
+      def skip!(reason = nil)
+        message = reason ? "Skipping: #{reason}" : 'Skipping script'
+        log(message)
+        raise ScriptSkipped, message
+      end
+
+      def log(message, level: :info)
+        timestamp = Time.current.strftime('%Y-%m-%d %H:%M:%S')
+        prefix = level == :error ? '[ERROR]' : '[INFO]'
+        puts "#{prefix} [#{timestamp}] #{message}"
+      end
+
+      def log_progress(current, total, message = nil)
+        percentage = ((current.to_f / total) * 100).round(2)
+        msg = message ? "#{message} (#{current}/#{total} - #{percentage}%)" : "Progress: #{current}/#{total} (#{percentage}%)"
+        log(msg)
+      end
+
+      def process_in_batches(relation, batch_size: 1000, &block)
+        total = relation.count
+        log("There are #{total} records to process")
+        return 0 if total.zero?
+
+        processed = 0
+        log("Processing #{total} records in batches of #{batch_size}")
+        relation.find_each(batch_size: batch_size) do |record|
+          block.call(record)
+          processed += 1
+          log_interval = [batch_size, (total * 0.1).to_i].max
+          log_progress(processed, total) if (processed % log_interval).zero?
+        end
+        log_progress(processed, total, 'Completed')
+        processed
+      end
+    end
+  end
+end

data/lib/script_tracker/executed_script.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module ScriptTracker
+  class ExecutedScript < ActiveRecord::Base
+    self.table_name = 'executed_scripts'
+
+    # Constants
+    DEFAULT_TIMEOUT = 300 # 5 minutes in seconds
+
+    # Validations
+    validates :filename, presence: true, uniqueness: true
+    validates :executed_at, presence: true
+    validates :status, presence: true, inclusion: { in: %w[success failed running skipped] }
+    validates :timeout, numericality: { greater_than: 0, allow_nil: true }
+
+    # Scopes
+    scope :successful, -> { where(status: 'success') }
+    scope :failed, -> { where(status: 'failed') }
+    scope :running, -> { where(status: 'running') }
+    scope :completed, -> { where(status: %w[success failed]) }
+    scope :skipped, -> { where(status: 'skipped') }
+    scope :ordered, -> { order(executed_at: :asc) }
+    scope :recent_first, -> { order(executed_at: :desc) }
+
+    # Class methods
+    def self.executed?(filename)
+      exists?(filename: filename)
+    end
+
+    def self.mark_as_running(filename)
+      create!(
+        filename: filename,
+        executed_at: Time.current,
+        status: 'running'
+      )
+    end
+
+    def self.cleanup_stale_running_scripts(older_than: 1.hour.ago)
+      stale_scripts = running.where('executed_at < ?', older_than)
+      count = stale_scripts.count
+      stale_scripts.update_all(
+        status: 'failed',
+        output: 'Script was marked as failed due to stale running status'
+      )
+      count
+    end
+
+    # Instance methods
+    def mark_success!(output_text = nil, execution_duration = nil)
+      update!(
+        status: 'success',
+        output: output_text,
+        duration: execution_duration
+      )
+    end
+
+    def mark_failed!(error_message, execution_duration = nil)
+      update!(
+        status: 'failed',
+        output: error_message,
+        duration: execution_duration
+      )
+    end
+
+    def mark_skipped!(output_text = nil, execution_duration = nil)
+      update!(
+        status: 'skipped',
+        output: output_text,
+        duration: execution_duration
+      )
+    end
+
+    def success?
+      status == 'success'
+    end
+
+    def failed?
+      status == 'failed'
+    end
+
+    def running?
+      status == 'running'
+    end
+
+    def skipped?
+      status == 'skipped'
+    end
+
+    def formatted_duration
+      return 'N/A' if duration.nil?
+
+      if duration < 1
+        "#{(duration * 1000).round(2)}ms"
+      elsif duration < 60
+        "#{duration.round(2)}s"
+      else
+        minutes = (duration / 60).floor
+        seconds = (duration % 60).round(2)
+        "#{minutes}m #{seconds}s"
+      end
+    end
+
+    def formatted_output
+      return 'No output' if output.blank?
+
+      output.truncate(500)
+    end
+
+    def timeout_seconds
+      timeout || DEFAULT_TIMEOUT
+    end
+
+    def timed_out?
+      return false unless running? && timeout
+
+      Time.current > executed_at + timeout.seconds
+    end
+  end
+end

data/lib/script_tracker/generators/install_generator.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'rails/generators/active_record'
+
+module ScriptTracker
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+      desc "Creates ScriptTracker migration file and initializer"
+
+      class_option :uuid, type: :boolean, default: true,
+                   desc: "Use UUID for primary keys (requires database support)"
+
+      class_option :skip_migration, type: :boolean, default: false,
+                   desc: "Skip creating the migration file"
+
+      class_option :skip_initializer, type: :boolean, default: false,
+                   desc: "Skip creating the initializer file"
+
+      def self.next_migration_number(dirname)
+        next_migration_number = current_migration_number(dirname) + 1
+        ActiveRecord::Migration.next_migration_number(next_migration_number)
+      end
+
+      def copy_migration
+        return if options[:skip_migration]
+
+        migration_template(
+          "create_executed_scripts.rb.erb",
+          "db/migrate/create_executed_scripts.rb",
+          migration_version: migration_version
+        )
+      end
+
+      def create_initializer
+        return if options[:skip_initializer]
+
+        template "initializer.rb", "config/initializers/script_tracker.rb"
+      end
+
+      def create_scripts_directory
+        empty_directory "lib/scripts"
+        create_file "lib/scripts/.keep"
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+
+      def use_uuid?
+        options[:uuid]
+      end
+
+      def primary_key_type
+        use_uuid? ? ":uuid" : "true"
+      end
+    end
+  end
+end

data/lib/script_tracker/generators/templates/README

@@ -0,0 +1,22 @@
+===============================================================================
+
+ScriptTracker has been installed!
+
+Next steps:
+
+1. Run the migration:
+   rails db:migrate
+
+2. Create your first script:
+   rake scripts:create["your script description"]
+
+3. Run pending scripts:
+   rake scripts:run
+
+4. Check scripts status:
+   rake scripts:status
+
+For more information, visit:
+https://github.com/blink-global/script_tracker
+
+===============================================================================

data/lib/script_tracker/generators/templates/create_executed_scripts.rb.erb

@@ -0,0 +1,17 @@
+class CreateExecutedScripts < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :executed_scripts<%= primary_key_type == ":uuid" ? ", id: :uuid" : "" %> do |t|
+      t.string :filename, null: false
+      t.datetime :executed_at, null: false
+      t.string :status, null: false, default: 'running'
+      t.text :output
+      t.float :duration
+      t.integer :timeout
+      t.timestamps
+    end
+
+    add_index :executed_scripts, :filename, unique: true
+    add_index :executed_scripts, :status
+    add_index :executed_scripts, :executed_at
+  end
+end

data/lib/script_tracker/generators/templates/initializer.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# ScriptTracker Configuration
+# Customize the scripts directory path if needed
+ScriptTracker.configure do |config|
+  # Default: Rails.root.join('lib', 'scripts')
+  # config.scripts_path = Rails.root.join('lib', 'scripts')
+end

data/lib/script_tracker/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ScriptTracker
+  class Railtie < ::Rails::Railtie
+    railtie_name :script_tracker
+
+    rake_tasks do
+      path = File.expand_path(__dir__)
+      Dir.glob("#{path}/../../tasks/**/*.rake").each { |f| load f }
+    end
+
+    initializer "script_tracker.configure" do |app|
+      app.config.script_tracker = ActiveSupport::OrderedOptions.new
+      app.config.script_tracker.scripts_path = app.root.join('lib', 'scripts')
+    end
+  end
+end

data/lib/script_tracker/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ScriptTracker
+  VERSION = "0.1.0"
+end

data/lib/script_tracker.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "script_tracker/version"
+require "script_tracker/base"
+require "script_tracker/executed_script"
+require "script_tracker/railtie" if defined?(Rails::Railtie)
+
+# Load generators for Rails
+if defined?(Rails)
+  require "rails/generators"
+  require_relative "script_tracker/generators/install_generator"
+end
+
+module ScriptTracker
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration) if block_given?
+    end
+
+    def scripts_path
+      configuration&.scripts_path || Rails.root.join('lib', 'scripts')
+    end
+  end
+
+  class Configuration
+    attr_accessor :scripts_path
+
+    def initialize
+      @scripts_path = nil
+    end
+  end
+end

data/tasks/script_tracker.rake

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+namespace :scripts do
+  desc 'Create a new script'
+  task :create, [:description] => :environment do |_task, args|
+    description = args[:description]
+
+    if description.blank?
+      puts 'Usage: rake scripts:create["description"]'
+      exit 1
+    end
+
+    timestamp = Time.current.strftime('%Y%m%d%H%M%S')
+    snake_case = description.downcase.gsub(/[^a-z0-9]+/, '_').gsub(/^_|_$/, '')
+    filename = "#{timestamp}_#{snake_case}.rb"
+    class_name = snake_case.camelize
+    scripts_dir = ScriptTracker.scripts_path
+    file_path = scripts_dir.join(filename)
+
+    FileUtils.mkdir_p(scripts_dir) unless Dir.exist?(scripts_dir)
+
+    template = File.read(File.expand_path('../templates/script_template.rb', __dir__))
+    content = template.gsub('<%= filename %>', filename)
+                      .gsub('<%= description %>', description)
+                      .gsub('<%= class_name %>', class_name)
+                      .gsub('<%= Time.current.year %>', Time.current.year.to_s)
+                      .gsub('<%= Time.current.strftime(\'%Y-%m-%d %H:%M:%S\') %>', Time.current.strftime('%Y-%m-%d %H:%M:%S'))
+
+    File.write(file_path, content)
+
+    puts "\nCreated #{filename}"
+    puts "Location: #{file_path}"
+  end
+
+  desc 'Run all pending scripts'
+  task run: :environment do
+    # Clean up any scripts that got stuck in "running" state
+    stale_count = ScriptTracker::ExecutedScript.cleanup_stale_running_scripts
+    puts "Cleaned up #{stale_count} stale script(s)\n\n" if stale_count > 0
+
+    # Find all scripts that haven't run yet
+    scripts_dir = ScriptTracker.scripts_path
+
+    unless Dir.exist?(scripts_dir)
+      puts "Error: Scripts directory does not exist: #{scripts_dir}"
+      puts "Please run: rails generate script_tracker:install"
+      exit 1
+    end
+
+    all_scripts = Dir[scripts_dir.join('*.rb')].sort
+    pending_scripts = all_scripts.reject { |f| ScriptTracker::ExecutedScript.executed?(File.basename(f)) }
+
+    if pending_scripts.empty?
+      puts "\nAll scripts are up to date. Nothing to run!"
+      exit 0
+    end
+
+    success_count = 0
+    failed_count = 0
+    skipped_count = 0
+
+    pending_scripts.each_with_index do |script_path, index|
+      script_name = File.basename(script_path)
+      puts "[#{index + 1}/#{pending_scripts.count}] Running #{script_name}..."
+
+      begin
+        # Load script file
+        load script_path
+
+        # Extract and validate class name
+        class_name = script_name.gsub(/^\d+_/, '').gsub('.rb', '').camelize
+        script_class_name = "Scripts::#{class_name}"
+
+        unless defined?(Scripts)
+          puts "Error: Scripts module not found. Ensure script defines 'module Scripts'"
+          failed_count += 1
+          next
+        end
+
+        begin
+          script_class = script_class_name.constantize
+        rescue NameError => e
+          puts "Error: Could not find class #{script_class_name}: #{e.message}"
+          failed_count += 1
+          next
+        end
+
+        # Validate script class
+        unless script_class < ScriptTracker::Base
+          puts "Error: Script class #{script_class_name} must inherit from ScriptTracker::Base"
+          failed_count += 1
+          next
+        end
+
+        unless script_class.respond_to?(:execute)
+          puts "Error: Script class #{script_class_name} must implement the execute method"
+          failed_count += 1
+          next
+        end
+
+        # Mark as running and get timeout
+        executed_script = ScriptTracker::ExecutedScript.mark_as_running(script_name)
+        executed_script.update(timeout: script_class.timeout) if script_class.respond_to?(:timeout)
+        start_time = Time.current
+
+        # Run script with timeout support
+        result = script_class.run(executed_script)
+        duration = Time.current - start_time
+
+        if result[:success]
+          executed_script.mark_success!(result[:output], result[:duration] || duration)
+          puts "Completed successfully in #{duration.round(2)}s\n\n"
+          success_count += 1
+        elsif result[:skipped]
+          executed_script.mark_skipped!(result[:output], result[:duration] || duration)
+          puts "Skipped in #{duration.round(2)}s\n\n"
+          skipped_count += 1
+        else
+          executed_script.mark_failed!(result[:output], result[:duration] || duration)
+          puts "Failed in #{duration.round(2)}s"
+          puts "Error: #{result[:output]}\n\n"
+          failed_count += 1
+        end
+      rescue LoadError => e
+        puts "Error: Could not load script file #{script_name}: #{e.message}"
+        failed_count += 1
+      rescue SyntaxError => e
+        puts "Error: Syntax error in script #{script_name}: #{e.message}"
+        failed_count += 1
+      rescue StandardError => e
+        duration = Time.current - start_time rescue 0
+        error_message = "#{e.class}: #{e.message}"
+        executed_script&.mark_failed!(error_message, duration)
+        puts "Error: #{e.message}\n\n"
+        failed_count += 1
+      end
+    end
+
+    puts "Summary: #{success_count} succeeded, #{failed_count} failed, #{skipped_count} skipped"
+
+    exit(1) if failed_count > 0
+  end
+
+  desc 'Show all scripts status'
+  task status: :environment do
+    scripts_dir = ScriptTracker.scripts_path
+
+    unless Dir.exist?(scripts_dir)
+      puts "Error: Scripts directory does not exist: #{scripts_dir}"
+      puts "Please run: rails generate script_tracker:install"
+      exit 1
+    end
+
+    script_files = Dir[scripts_dir.join('*.rb')].sort
+    executed_scripts = ScriptTracker::ExecutedScript.all.index_by(&:filename)
+
+    if script_files.empty?
+      puts "\nNo scripts found in #{scripts_dir}"
+      puts "Create a script with: rake scripts:create[\"description\"]"
+      exit 0
+    end
+
+    puts "\nScripts:"
+    script_files.each do |file|
+      filename = File.basename(file)
+      if (script = executed_scripts[filename])
+        status_icon = script.success? ? '[SUCCESS]' : script.failed? ? '[FAILED]' : script.skipped? ? '[SKIPPED]' : '[RUNNING]'
+        puts "  #{status_icon} #{filename} (#{script.formatted_duration})"
+      else
+        puts "  [PENDING] #{filename}"
+      end
+    end
+    puts
+  end
+
+  desc 'Rollback a script'
+  task :rollback, [:filename] => :environment do |_task, args|
+    filename = args[:filename]
+
+    if filename.blank?
+      puts 'Usage: rake scripts:rollback[filename.rb]'
+      exit 1
+    end
+
+    script = ScriptTracker::ExecutedScript.find_by(filename: filename)
+    if script.nil?
+      puts "Script not found: #{filename}"
+      exit 1
+    end
+
+    script.destroy!
+    puts "Rolled back: #{filename}"
+  end
+
+  desc 'Cleanup stale scripts'
+  task cleanup: :environment do
+    count = ScriptTracker::ExecutedScript.cleanup_stale_running_scripts
+    puts "Cleaned up #{count} stale script(s)"
+  end
+end

data/templates/script_template.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Script: <%= filename %>
+# Created: <%= Time.current.strftime('%Y-%m-%d %H:%M:%S') %>
+# Description: <%= description %>
+#
+# This script performs: [Describe what this script does]
+#
+# Prerequisites:
+# - [List any prerequisites]
+#
+# Rollback plan:
+# - [Describe how to rollback if needed]
+#
+
+module Scripts
+  class <%= class_name %> < ScriptTracker::Base
+    # Optional: Override timeout (default is 300 seconds / 5 minutes)
+    # def self.timeout
+    #   3600 # 1 hour
+    # end
+
+    def self.execute
+      log "Starting script: <%= filename %>"
+
+      # Example: Skip if work is already done
+      # if condition_already_met?
+      #   skip! "Reason for skipping"
+      # end
+
+      # Your script logic here
+
+      log "Script completed successfully"
+    end
+  end
+end
+
+# Execute the script if run directly
+if __FILE__ == $PROGRAM_NAME
+  result = Scripts::<%= class_name %>.run
+  exit(result[:success] ? 0 : 1)
+end

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification
+name: script_tracker
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ahmed Abd El-Latif
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-11-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner-active_record
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: ScriptTracker provides a migration-like system for managing one-off scripts
+  with execution tracking, transaction support, and built-in logging. Perfect for
+  data migrations, cleanup tasks, and administrative scripts.
+email:
+- ahmed.abdelatif@blink.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/script_tracker.rb
+- lib/script_tracker/base.rb
+- lib/script_tracker/executed_script.rb
+- lib/script_tracker/generators/install_generator.rb
+- lib/script_tracker/generators/templates/README
+- lib/script_tracker/generators/templates/create_executed_scripts.rb.erb
+- lib/script_tracker/generators/templates/initializer.rb
+- lib/script_tracker/railtie.rb
+- lib/script_tracker/version.rb
+- tasks/script_tracker.rake
+- templates/script_template.rb
+homepage: https://github.com/blink-global/script_tracker
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/blink-global/script_tracker
+  source_code_uri: https://github.com/a-abdellatif98/script_tracker
+  changelog_uri: https://github.com/a-abdellatif98/script_tracker/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: A Ruby gem for tracking and managing one-off script executions in Rails applications
+test_files: []