mighost 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8aff4752d4638c5822c2e81ff30f7b2fd2b5ddf7f38009cbd24faea539fa1c24
+  data.tar.gz: 3a8580ffebdc73e87ce3eac7f29c5a7a9b98a83f935925974729b01581436336
+SHA512:
+  metadata.gz: 1e9bf5182859b684f2799edfcdd9be3025af0af5416f4748207ce3bb439b6c5252db037c75443388353284f964a6192d8d9ccafe5d241201015dbb757a333e6c
+  data.tar.gz: 2eb3deee0b4c7083b887187fcce41e7e53252eb12e08b8756a9ec1bbbccac5b142ef64cef9a39ec5996d3f3edb737e31be7bbceab3bb5d701d3b322f1beff401

data/CHANGELOG.md

@@ -0,0 +1,51 @@
+# 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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.0] - 2026-07-08
+
+First public release.
+
+### Fixed
+
+- Ghost migrations whose last touch in git history was a deletion are now
+  recoverable: recovery resolves to the last commit where the file existed
+  instead of the deleting commit.
+- `Mighost::GitMetadata.reset!` no longer permanently disables git detection.
+- Worktree paths containing spaces or shell metacharacters are handled correctly.
+- Rollback now fails loudly when the migration class cannot be determined from
+  the recovered file, instead of guessing among loaded migration classes.
+
+### Changed
+
+- CI matrix (Ruby 3.1–3.4 × Rails 7.1–8.1), packaging cleanup, and expanded
+  test coverage in preparation for the public release.
+
+## [0.3.0] - 2026-04-06 (internal)
+
+### Added
+
+- Automatic capture of migration file contents on `db:migrate` into a local
+  SQLite store (`.mighost.sqlite3`).
+- 3-tier recovery for orphaned ("ghost") migrations: stored snapshots,
+  git history across all branches, and other git worktrees.
+- Rake tasks: `mighost:status`, `mighost:rollback`, `mighost:scan`,
+  `mighost:list`, `mighost:dismiss`, `mighost:undismiss`, `mighost:dismissed`,
+  `mighost:cleanup`, `mighost:help`.
+- Version range syntax for dismiss/undismiss (`VERSION=a..b`, `a..`, `..b`).
+- Stable programmatic interface via `Mighost::API` (used by
+  [railbow](https://github.com/amberpixels/railbow)).
+- Pluggable UI adapter (`Mighost.ui`) with a zero-dependency `PlainUI` default.
+- Git metadata capture: branch, SHA, and author per migration.
+- Rails 6.1–8.1 support.
+
+## [0.2.0] - 2026-01-23 (internal)
+
+- Git history recovery, dismiss/undismiss workflow, performance improvements.
+
+## [0.1.0] - 2026-01-21 (internal)
+
+- Initial prototype: snapshot capture and rollback of missing migrations.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 amberpixels (Eugene M)
+
+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,189 @@
+<p align="center">
+  <img src="logo.svg" alt="Mighost" width="620">
+</p>
+
+<div align="center">
+
+### Rollback Rails migrations even when the migration file is missing.
+
+[![Gem Version](https://img.shields.io/gem/v/mighost)](https://rubygems.org/gems/mighost)
+[![CI](https://github.com/amberpixels/mighost/actions/workflows/ci.yml/badge.svg)](https://github.com/amberpixels/mighost/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
+
+</div>
+
+---
+
+## The Problem
+
+When working with Rails migrations across git branches:
+
+1. You run migrations on a feature branch
+2. Switch back to `main`
+3. Run `db:migrate` - Rails dumps schema including changes from the other branch
+4. You can't rollback because the migration files don't exist in current branch
+
+**Usual workaround**: Switch to the other branch, rollback, switch back. Tedious.
+
+## The Solution
+
+Mighost automatically captures migration file contents when they run, enabling rollback even when the original file is not present. It uses a 3-tier recovery strategy:
+
+1. **Stored snapshots** — captured at migration time into a local SQLite file
+2. **Git history** — searches across all branches
+3. **Worktree recovery** — finds files in other git worktrees
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'mighost', group: [:development, :test]
+```
+
+Then run:
+
+```bash
+bundle install
+rails generate mighost:install
+```
+
+Add `.mighost.sqlite3` to your `.gitignore`.
+
+Requires Ruby >= 3.1 and Rails 6.1–8.1.
+
+## Usage
+
+### Check for orphaned migrations
+
+```bash
+rails mighost:status
+```
+
+### Rollback orphaned migrations
+
+```bash
+# Interactive (with confirmation)
+rails mighost:rollback
+
+# Force (no confirmation)
+FORCE=1 rails mighost:rollback
+
+# Specific version
+rails mighost:rollback VERSION=20240115123456
+```
+
+### Scan existing migrations & git history
+
+If you install Mighost on an existing project:
+
+```bash
+rails mighost:scan
+```
+
+### All commands
+
+| Command | Description | Options |
+|---------|-------------|---------|
+| `mighost:status` | Show orphaned migrations | `DEBUG=1`, `SHOW_DISMISSED=1` |
+| `mighost:rollback` | Rollback orphaned migrations | `VERSION=x`, `FORCE=1` |
+| `mighost:scan` | Capture migrations + search git | `RESCAN=1` |
+| `mighost:list` (`ls`) | List stored migration records | `LIMIT=N` |
+| `mighost:dismiss` | Hide migrations from status | `VERSION=x`, `VERSION=a..b`, `OLD=1` |
+| `mighost:undismiss` | Restore dismissed migrations | `VERSION=x` |
+| `mighost:dismissed` | List dismissed migrations | |
+| `mighost:cleanup` | Remove stale records | `FORCE=1` |
+| `mighost:help` | Show command reference | |
+
+### Version ranges
+
+```bash
+VERSION=20240115123456       # Single version
+VERSION=20240110..20240120   # Inclusive range
+VERSION=20240110..           # From version onwards
+VERSION=..20240120           # Up to version
+```
+
+## Configuration
+
+```ruby
+# config/initializers/mighost.rb
+Mighost.configure do |config|
+  # Path to SQLite file (relative to Rails.root)
+  config.storage_path = ".mighost.sqlite3"
+
+  # Auto-capture on migrate
+  config.auto_capture = true
+
+  # Store git metadata
+  config.store_git_metadata = true
+
+  # Enable/disable (disabled in production by default)
+  config.enabled = !Rails.env.production?
+end
+```
+
+## Rich Output with Railbow
+
+By default, Mighost outputs plain, uncolored text. For rich, colorized output with tables, emojis, and git enrichment, use the [railbow](https://github.com/amberpixels/railbow) gem:
+
+```ruby
+gem 'railbow'
+```
+
+Railbow automatically detects Mighost and enhances its output.
+
+## Public API
+
+Mighost exposes a stable API for programmatic access:
+
+```ruby
+# Detect orphaned migrations
+Mighost::API.orphaned_migrations                  # => [OrphanedMigration, ...]
+
+# Find snapshots
+Mighost::API.find_snapshot("20240115123456")       # => Snapshot or nil
+Mighost::API.find_or_recover_snapshot("20240115")  # => Snapshot (with git/worktree fallback)
+
+# Scan and recover
+Mighost::API.scan!(rescan: false)                  # => {captured:, git_recovered:, ...}
+
+# Rollback
+Mighost::API.rollback_version!("20240115123456")   # raises on failure
+```
+
+### UI Adapter
+
+Mighost uses a pluggable UI adapter for output. Replace it to customize formatting:
+
+```ruby
+# In your railtie or initializer:
+Mighost.ui = YourCustomUI.new
+```
+
+The adapter must implement: `render_orphans`, `render_records`, `render_recoverable_list`, `render_scan_details`, `render_scan_results`, `render_dismiss_preview`, `render_dismiss_remaining`, `render_dismissed_list`, `confirm?`, `confirm_each?`, `confirm_dismiss?`, `success`, `error`, `warning`, `info`, `hint`. See [`Mighost::PlainUI`](lib/mighost/plain_ui.rb) for the reference implementation.
+
+## How It Works
+
+1. **Capture**: When you run `db:migrate`, Mighost hooks into `ActiveRecord::Migrator` and stores the migration file content along with git metadata (branch, SHA) in a local SQLite file.
+
+2. **Detect**: `mighost:status` compares `schema_migrations` table with actual migration files to find orphans.
+
+3. **Recover**: For missing files, Mighost searches stored snapshots, git history (all branches), and other git worktrees.
+
+4. **Rollback**: Writes recovered content to a temp file, loads it, calls the `down` method, then removes the version from `schema_migrations`.
+
+## Limitations
+
+- **Irreversible migrations**: If the migration raises `ActiveRecord::IrreversibleMigration`, Mighost can't help.
+- **Model dependencies**: If your migration references models/classes that don't exist in the current branch, the rollback may fail.
+- **Manual SQL changes**: If someone manually modified the database, rollback might not work correctly.
+- **Trust**: Recovered migration code (from snapshots, git history, or worktrees) is executed with the same trust as your own migrations — it is code from your repository, run by you.
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/amberpixels/mighost/issues). Run `bundle exec rake` (specs + standardrb) before submitting.
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

data/lib/generators/mighost/install_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Mighost
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Mighost initializer"
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/mighost.rb"
+      end
+
+      def show_instructions
+        say "\nMighost configured (local SQLite storage).", :green
+        say "Add '.mighost.sqlite3' to your .gitignore"
+      end
+    end
+  end
+end

data/lib/generators/mighost/templates/initializer.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+Mighost.configure do |config|
+  # Path to SQLite file (relative to Rails.root)
+  # config.storage_path = ".mighost.sqlite3"
+
+  # Auto-capture migrations when they run
+  config.auto_capture = true
+
+  # Store git metadata (branch name, commit SHA)
+  config.store_git_metadata = true
+
+  # Disable in production
+  config.enabled = !Rails.env.production?
+end

data/lib/mighost/api.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/object/blank"
+require_relative "orphan_detector"
+require_relative "snapshot"
+require_relative "rollbacker"
+require_relative "capturer"
+require_relative "git_recovery"
+require_relative "worktree_recovery"
+require_relative "git_metadata"
+require_relative "formatting"
+
+module Mighost
+  # Public API for programmatic access.
+  # This is the stable interface for external consumers (e.g. railbow).
+  module API
+    module_function
+
+    # Returns [OrphanedMigration]
+    def orphaned_migrations(include_dismissed: false)
+      OrphanDetector.detect(include_dismissed: include_dismissed)
+    end
+
+    # Returns Snapshot or nil
+    def find_snapshot(version)
+      Snapshot.find_by_version(version)
+    end
+
+    # Returns Snapshot (with git/worktree fallback) or nil
+    def find_or_recover_snapshot(version)
+      Snapshot.find_or_recover(version)
+    end
+
+    # Returns [Snapshot]
+    def all_snapshots(limit: nil)
+      records = Snapshot.all_snapshots
+      limit&.positive? ? records.first(limit) : records
+    end
+
+    # Executes rollback. Raises SnapshotNotFound or RollbackFailed on failure.
+    def rollback_version!(version)
+      Rollbacker.rollback_version!(version)
+    end
+
+    # Scan: capture files, search git, search worktrees.
+    # Returns {captured:, git_recovered:, worktree_recovered:, branch:, sha:, details:[]}
+    def scan!(rescan: false)
+      migration_paths = if defined?(Rails) && Rails.application
+        Rails.application.config.paths["db/migrate"].to_ary
+      else
+        ["db/migrate"]
+      end
+
+      migrated_versions = Mighost::Base.connection
+        .select_values("SELECT version FROM schema_migrations")
+        .map(&:to_s)
+
+      captured = 0
+      git_recovered = 0
+      worktree_recovered = 0
+      details = []
+
+      # Phase 1: Capture existing migration files
+      migration_paths.each do |path|
+        Dir.glob(File.join(path, "*.rb")).each do |file|
+          basename = File.basename(file)
+          version = basename.split("_").first
+
+          next unless migrated_versions.include?(version)
+          next if !rescan && Snapshot.find_by_version(version)
+
+          Capturer.new(version, file).capture
+          details << {type: :captured, filename: basename}
+          captured += 1
+        end
+      end
+
+      # Phase 2: Search git for orphaned migrations
+      orphan_versions = migrated_versions.reject do |version|
+        migration_paths.any? { |p| Dir.glob(File.join(p, "#{version}_*.rb")).any? }
+      end
+
+      orphan_versions.each do |version|
+        existing = Snapshot.find_by_version(version)
+        next if !rescan && existing&.source.present?
+
+        git_data = GitRecovery.find_migration(version)
+        next unless git_data
+
+        Snapshot.store(
+          version: version,
+          content: git_data[:content],
+          filename: git_data[:filename],
+          branch_name: git_data[:branch],
+          git_sha: git_data[:sha],
+          source: "git",
+          author_name: git_data[:author_name],
+          author_email: git_data[:author_email]
+        )
+        details << {type: :git_recovered, filename: git_data[:filename], branch: git_data[:branch]}
+        git_recovered += 1
+      end
+
+      # Phase 3: Search worktrees for uncommitted migrations
+      remaining_orphans = orphan_versions.reject do |version|
+        existing = Snapshot.find_by_version(version)
+        !rescan && existing&.source.present?
+      end
+
+      remaining_orphans.each do |version|
+        wt_data = WorktreeRecovery.find_migration(version)
+        next unless wt_data
+
+        Snapshot.store(
+          version: version,
+          content: wt_data[:content],
+          filename: wt_data[:filename],
+          branch_name: wt_data[:branch],
+          source: "worktree",
+          author_name: wt_data[:author_name],
+          author_email: wt_data[:author_email]
+        )
+        details << {type: :worktree_recovered, filename: wt_data[:filename], branch: wt_data[:branch]}
+        worktree_recovered += 1
+      end
+
+      # Store scan metadata
+      branch = GitMetadata.current_branch
+      sha = GitMetadata.current_sha
+      Snapshot.store_scan_metadata(branch: branch, sha: sha)
+
+      {
+        captured: captured,
+        git_recovered: git_recovered,
+        worktree_recovered: worktree_recovered,
+        branch: branch,
+        sha: sha,
+        details: details
+      }
+    end
+
+    def dismiss(version)
+      Snapshot.dismiss(version)
+    end
+
+    def undismiss(version)
+      Snapshot.undismiss(version)
+    end
+
+    def dismissed_count
+      Snapshot.dismissed_versions.count
+    end
+  end
+end

data/lib/mighost/capturer.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require_relative "snapshot"
+require_relative "git_metadata"
+
+module Mighost
+  class Capturer
+    attr_reader :version, :migration_path
+
+    def initialize(version, migration_path)
+      @version = version.to_s
+      @migration_path = migration_path
+    end
+
+    def capture
+      return unless Mighost.enabled?
+      return unless Mighost.configuration.auto_capture
+      return unless File.exist?(migration_path)
+
+      content = File.read(migration_path)
+      filename = File.basename(migration_path)
+
+      attributes = {
+        version: version,
+        content: content,
+        filename: filename
+      }
+
+      if Mighost.configuration.store_git_metadata
+        attributes[:branch_name] = GitMetadata.current_branch
+        attributes[:git_sha] = GitMetadata.current_sha
+
+        author_name, author_email = git_author_of(migration_path)
+        attributes[:author_name] = author_name
+        attributes[:author_email] = author_email
+      end
+
+      Snapshot.store(**attributes)
+    rescue => e
+      # Don't break migrations if snapshot capture fails
+      warn "[Mighost] Failed to capture snapshot for #{version}: #{e.message}"
+    end
+
+    private
+
+    def git_author_of(filepath)
+      return [nil, nil] unless GitMetadata.git_available?
+
+      escaped = Shellwords.shellescape(filepath)
+      output = `git log --format='%aN\t%aE' --follow -1 -- #{escaped} 2>/dev/null`.strip
+      return [nil, nil] if output.empty?
+
+      output.split("\t", 2)
+    rescue
+      [nil, nil]
+    end
+  end
+end

data/lib/mighost/configuration.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# active_support must load before any core_ext cherry-pick (AS 7.1 requirement)
+require "active_support"
+require "active_support/core_ext/integer/time"
+
+module Mighost
+  class Configuration
+    # Path to SQLite file (relative to Rails.root)
+    attr_accessor :storage_path
+
+    # Auto-capture migrations on db:migrate
+    attr_accessor :auto_capture
+
+    # Store git metadata (branch, SHA)
+    attr_accessor :store_git_metadata
+
+    # Enabled environments (disabled in production by default)
+    attr_accessor :enabled
+
+    # Threshold for suggesting dismissal of old unrecoverable migrations
+    attr_accessor :dismiss_old_threshold
+
+    def initialize
+      @storage_path = ".mighost.sqlite3"
+      @auto_capture = true
+      @store_git_metadata = true
+      @enabled = true
+      @dismiss_old_threshold = 6.months
+    end
+
+    def enabled?
+      @enabled
+    end
+  end
+end

data/lib/mighost/formatting.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Mighost
+  module Formatting
+    module_function
+
+    def format_version(version)
+      if version =~ /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})$/
+        "#{$1}-#{$2}-#{$3} #{$4}:#{$5}"
+      else
+        version.to_s
+      end
+    end
+
+    def format_name(filename)
+      return "(unknown)" unless filename
+
+      name = filename.sub(/^\d+_/, "").sub(/\.rb$/, "")
+      truncate(name, 40)
+    end
+
+    def format_recovery(source)
+      case source
+      when :snapshot then "snapshot"
+      when :branch then "git"
+      when :worktree then "worktree"
+      else "-"
+      end
+    end
+
+    def format_captured_at(value)
+      case value
+      when String then value[0, 10]
+      when Time then value.strftime("%Y-%m-%d")
+      else "-"
+      end
+    end
+
+    def format_age(created_at)
+      return "-" unless created_at
+
+      seconds = Time.now - created_at
+      return "-" if seconds < 0
+
+      days = (seconds / 86400).to_i
+      months = (days / 30.0).to_i
+      years = (days / 365.0).to_i
+
+      if years >= 1
+        remaining_months = ((days - years * 365) / 30.0).to_i
+        if remaining_months.positive?
+          "#{years}y #{remaining_months}mo"
+        else
+          "#{years}y"
+        end
+      elsif months >= 1
+        "#{months}mo"
+      elsif days >= 1
+        "#{days}d"
+      else
+        "<1d"
+      end
+    end
+
+    def truncate(str, max_length)
+      return str if str.length <= max_length
+
+      "#{str[0, max_length - 3]}..."
+    end
+
+    def parse_version_range(param, available_versions)
+      return [] if available_versions.empty?
+
+      case param
+      when /^\.\.(.+)$/ # ..bbb (up to)
+        upper = $1
+        available_versions.select { |v| v <= upper }
+      when /^(.+)\.\.$/ # aaa.. (from onwards)
+        lower = $1
+        available_versions.select { |v| v >= lower }
+      when /^(.+)\.\.(.+)$/ # aaa..bbb (range)
+        lower, upper = $1, $2
+        available_versions.select { |v| v.between?(lower, upper) }
+      else # single version
+        available_versions.include?(param) ? [param] : []
+      end
+    end
+  end
+end

data/lib/mighost/git_metadata.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Mighost
+  class GitMetadata
+    class << self
+      def current_branch
+        return nil unless git_available?
+
+        result = `git rev-parse --abbrev-ref HEAD 2>/dev/null`.strip
+        result.empty? ? nil : result
+      end
+
+      def current_sha
+        return nil unless git_available?
+
+        result = `git rev-parse HEAD 2>/dev/null`.strip
+        result.empty? ? nil : result[0, 12] # Short SHA
+      end
+
+      def git_available?
+        return @git_available if defined?(@git_available)
+
+        @git_available = system("git rev-parse --git-dir > /dev/null 2>&1")
+      end
+
+      def reset!
+        remove_instance_variable(:@git_available) if defined?(@git_available)
+      end
+    end
+  end
+end