docktor_rails 0.1.0

data/lib/docktor_rails/checks/shell_scripts_crlf.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "base_check"
+
+module DocktorRails
+  module Checks
+    class ShellScriptsCrlf < BaseCheck
+      DEFAULT_IGNORES = [
+        "/.git/",
+        "/node_modules/",
+        "/vendor/",
+        "/tmp/",
+        "/log/"
+      ].freeze
+
+      def id
+        "fs.shell_crlf"
+      end
+
+      def run(ctx)
+        root = ctx.fetch(:root)
+        offenders = []
+
+        Dir.glob(File.join(root, "**", "*.sh"), File::FNM_DOTMATCH).each do |path|
+          next unless File.file?(path)
+          next if ignored?(path)
+
+          offenders << rel(path, root) if File.binread(path).include?("\r\n")
+        end
+
+        if offenders.empty?
+          pass("No CRLF line endings in .sh files")
+        else
+          fail(
+            "CRLF line endings found in shell scripts",
+            files: offenders.sort,
+            hint: "Convert to LF (e.g. with git) and enforce via .gitattributes: *.sh text eol=lf"
+          )
+        end
+      end
+
+      private
+
+      def ignored?(path)
+        DEFAULT_IGNORES.any? { |seg| path.include?(seg) }
+      end
+
+      def rel(path, root)
+        path.delete_prefix(root + File::SEPARATOR)
+      end
+    end
+  end
+end

data/lib/docktor_rails/cli.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "thor"
+
+require_relative "version"
+require_relative "preflight/runner"
+require_relative "reporters/text_reporter"
+require_relative "reporters/json_reporter"
+
+module DocktorRails
+  class CLI < Thor
+    class_option :root, type: :string, desc: "Project root to scan (default: current directory)"
+    class_option :format, type: :string, default: "text", desc: "Output format: text|json"
+    class_option :output, type: :string, desc: "Write output to a file (useful with --format json)"
+    class_option :verbose, type: :boolean, default: false, desc: "Show passing checks"
+    class_option :quiet, type: :boolean, default: false, desc: "Only show errors/warnings and the summary"
+    class_option :no_color, type: :boolean, default: false, desc: "Disable colored output"
+
+    desc "diagnose", "Run preflight checks (read-only)"
+    def diagnose
+      report = Preflight::Runner.new(root: root_dir).run
+
+      io = output_io
+      render_report(report, io)
+
+      exit(report.fetch(:status) == :fail ? 1 : 0)
+    rescue StandardError => e
+      $stderr.puts("docktor_rails error: #{e.class}: #{e.message}")
+      exit(2)
+    ensure
+      io&.close if io && io != $stdout
+    end
+
+    desc "up", "Run preflight checks, then print the suggested docker compose commands"
+    def up
+      report = Preflight::Runner.new(root: root_dir).run
+
+      Reporters::TextReporter.new(
+        color: color_enabled?,
+        verbose: options[:verbose],
+        quiet: options[:quiet]
+      ).render(report)
+      exit(1) if report.fetch(:status) == :fail
+
+      puts
+      puts "Preflight passed. Next:" 
+      puts "  docker compose up"
+    rescue StandardError => e
+      $stderr.puts("docktor_rails error: #{e.class}: #{e.message}")
+      exit(2)
+    end
+
+    desc "version", "Print version"
+    def version
+      puts DocktorRails::VERSION
+    end
+
+    private
+
+    def output_io
+      path = options[:output]
+      return $stdout unless path
+
+      File.open(path, "w")
+    end
+
+    def render_report(report, io)
+      case options[:format]
+      when "json"
+        Reporters::JsonReporter.new(io: io).render(report, tool_version: DocktorRails::VERSION)
+      else
+        Reporters::TextReporter.new(
+          io: io,
+          color: color_enabled?,
+          verbose: options[:verbose],
+          quiet: options[:quiet]
+        ).render(report)
+      end
+    end
+
+    def color_enabled?
+      return false if options[:no_color]
+
+      $stdout.tty?
+    end
+
+    def root_dir
+      options[:root] ? File.expand_path(options[:root]) : Dir.pwd
+    end
+  end
+end

data/lib/docktor_rails/compose.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module DocktorRails
+  module Compose
+    CANDIDATES = ["compose.yml", "docker-compose.yml"].freeze
+
+    def self.find_file(root)
+      CANDIDATES.map { |f| File.join(root, f) }.find { |p| File.file?(p) }
+    end
+
+    def self.load_file(path)
+      data = YAML.safe_load(File.read(path), aliases: true)
+      data.is_a?(Hash) ? data : {}
+    rescue Psych::Exception => e
+      raise DocktorRails::Error, "Invalid compose YAML in #{File.basename(path)}: #{e.message}"
+    end
+
+    def self.services(doc)
+      doc.fetch("services", {}) || {}
+    end
+  end
+end

data/lib/docktor_rails/dotenv.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module DocktorRails
+  class Dotenv
+    def self.parse_file(path)
+      return {} unless File.file?(path)
+
+      parse(File.read(path))
+    end
+
+    def self.parse(content)
+      env = {}
+      content.each_line do |line|
+        line = line.strip
+        next if line.empty? || line.start_with?("#")
+
+        key, value = line.split("=", 2)
+        next if key.nil? || key.empty?
+
+        value = "" if value.nil?
+        value = value.strip
+        value = value[1..-2] if (value.start_with?("\"") && value.end_with?("\"")) || (value.start_with?("'") && value.end_with?("'"))
+        env[key] = value
+      end
+      env
+    end
+  end
+end

data/lib/docktor_rails/guidance.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module DocktorRails
+  module Guidance
+    def self.hint_for(result, platform)
+      return result.hint if result.hint
+
+      id = result.id
+      status = result.status
+      return nil if status == :pass
+
+      case id
+      when "fs.shell_crlf", "compose.entrypoint_sanity"
+        crlf_hint(platform)
+      when "compose.healthchecks"
+        "Add compose healthchecks so readiness is deterministic across machines (then you can wait on health status instead of sleeps)."
+      when "env.rails_master_key"
+        "Provide config/master.key (local dev), or set RAILS_MASTER_KEY (CI/prod), or add it to .env.docker."
+      when "compose.env_file_present"
+        "Ensure each env_file referenced in compose exists (or remove the reference)."
+      when "compose.build_paths"
+        "Fix compose build paths: ensure build.context directories exist and build.dockerfile paths resolve correctly."
+      when "compose.entrypoint_exec"
+        entrypoint_exec_hint(platform)
+      when "compose.platform_risk"
+        "If teammates use different CPU architectures (arm64 vs amd64), consider multi-arch images or removing hard platform pins unless necessary."
+      else
+        nil
+      end
+    end
+
+    def self.crlf_hint(platform)
+      if platform&.windows?
+        "CRLF usually comes from Windows checkouts. Add .gitattributes: '*.sh text eol=lf', then run: git add --renormalize ."
+      else
+        "Convert scripts to LF and enforce via .gitattributes: '*.sh text eol=lf'"
+      end
+    end
+
+    def self.entrypoint_exec_hint(platform)
+      if platform&.windows?
+        "Executable bit/shebang checks are not meaningful on Windows hosts. Prefer running via WSL2 for Linux-like behavior."
+      else
+        "Ensure entrypoint scripts are executable (chmod +x) and start with a shebang (e.g. #!/usr/bin/env bash)."
+      end
+    end
+  end
+end

data/lib/docktor_rails/platform.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module DocktorRails
+  class Platform
+    attr_reader :os, :arch
+
+    def initialize(os:, arch:)
+      @os = os
+      @arch = arch
+    end
+
+    def self.detect
+      new(os: detect_os, arch: detect_arch)
+    end
+
+    def windows?
+      os == :windows
+    end
+
+    def macos?
+      os == :macos
+    end
+
+    def linux?
+      os == :linux
+    end
+
+    def arm64?
+      arch == :arm64
+    end
+
+    def amd64?
+      arch == :amd64
+    end
+
+    def to_h
+      { os: os.to_s, arch: arch.to_s }
+    end
+
+    def label
+      "#{os} #{arch}"
+    end
+
+    def self.detect_os
+      p = RUBY_PLATFORM
+      return :windows if p.match?(/mswin|mingw|cygwin/i)
+      return :macos if p.match?(/darwin/i)
+      return :linux if p.match?(/linux/i)
+
+      :unknown
+    end
+
+    def self.detect_arch
+      cpu = RbConfig::CONFIG["host_cpu"].to_s.downcase
+      return :arm64 if cpu.match?(/arm64|aarch64/)
+      return :amd64 if cpu.match?(/x86_64|amd64/)
+
+      :unknown
+    end
+  end
+end

data/lib/docktor_rails/preflight/runner.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "../platform"
+
+require_relative "../checks/compose_file_present"
+require_relative "../checks/compose_build_paths"
+require_relative "../checks/compose_env_file_present"
+require_relative "../checks/compose_entrypoint_sanity"
+require_relative "../checks/compose_entrypoint_exec"
+require_relative "../checks/shell_scripts_crlf"
+require_relative "../checks/compose_healthchecks"
+require_relative "../checks/compose_platform_risk"
+require_relative "../checks/rails_master_key_required"
+
+module DocktorRails
+  module Preflight
+    class Runner
+      DEFAULT_CHECKS = [
+        Checks::ComposeFilePresent,
+        Checks::ComposeBuildPaths,
+        Checks::ComposeEnvFilePresent,
+        Checks::ComposeEntrypointSanity,
+        Checks::ComposeEntrypointExec,
+        Checks::ShellScriptsCrlf,
+        Checks::ComposeHealthchecks,
+        Checks::ComposePlatformRisk,
+        Checks::RailsMasterKeyRequired
+      ].freeze
+
+      def initialize(root: Dir.pwd, checks: DEFAULT_CHECKS)
+        @root = root
+        @checks = checks
+      end
+
+      def run
+        platform = Platform.detect
+        ctx = { root: @root, platform: platform }
+
+        results = @checks.map do |check_class|
+          check_class.new.run(ctx)
+        end
+
+        summary = {
+          pass: results.count(&:pass?),
+          warn: results.count(&:warn?),
+          fail: results.count(&:fail?)
+        }
+
+        status = if summary[:fail].positive?
+          :fail
+        elsif summary[:warn].positive?
+          :warn
+        else
+          :pass
+        end
+
+        {
+          root: @root,
+          platform: platform,
+          status: status,
+          summary: summary,
+          checks: results
+        }
+      end
+    end
+  end
+end

data/lib/docktor_rails/reporters/json_reporter.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../guidance"
+
+module DocktorRails
+  module Reporters
+    class JsonReporter
+      SCHEMA_VERSION = 1
+
+      def initialize(io: $stdout)
+        @io = io
+      end
+
+      def render(report, tool_version:)
+        platform = report[:platform]
+
+        checks = report.fetch(:checks).map do |r|
+          h = r.to_h
+          hint = Guidance.hint_for(r, platform)
+          h[:hint] = hint if hint && !h.key?(:hint)
+          h
+        end
+
+        payload = {
+          schema_version: SCHEMA_VERSION,
+          tool: { name: "docktor_rails", version: tool_version },
+          context: {
+            root: report[:root],
+            host: platform&.to_h
+          },
+          status: report.fetch(:status).to_s,
+          summary: report.fetch(:summary),
+          checks: checks
+        }
+
+        @io.write(JSON.pretty_generate(payload))
+        @io.write("\n")
+      end
+    end
+  end
+end

data/lib/docktor_rails/reporters/text_reporter.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "pastel"
+
+require_relative "../guidance"
+
+module DocktorRails
+  module Reporters
+    class TextReporter
+      def initialize(io: $stdout, color: true, verbose: false, quiet: false)
+        @io = io
+        @pastel = Pastel.new(enabled: color)
+        @verbose = verbose
+        @quiet = quiet
+      end
+
+      def render(report)
+        @root = report[:root]
+        @platform = report[:platform]
+
+        unless @quiet
+          @io.puts "docktor_rails — preflight check"
+          @io.puts @pastel.dim("host: #{@platform&.label || "unknown"}")
+          @io.puts @pastel.dim("root: #{@root}") if @root
+          @io.puts "—" * 46
+        end
+
+        checks = report.fetch(:checks)
+        render_group("Errors", checks.select(&:fail?))
+        render_group("Warnings", checks.select(&:warn?))
+        render_group("Passed", checks.select(&:pass?)) if @verbose && !@quiet
+
+        @io.puts "—" * 46 unless @quiet
+        s = report.fetch(:summary)
+        @io.puts "#{s.fetch(:fail)} errors · #{s.fetch(:warn)} warnings · #{s.fetch(:pass)} passed"
+      end
+
+      private
+
+      def render_group(title, results)
+        return if results.empty?
+
+        @io.puts @pastel.bold(title) unless @quiet
+        results.each do |result|
+          @io.puts format_line(result)
+          render_details(result)
+        end
+        @io.puts unless @quiet
+      end
+
+      def format_line(result)
+        case result.status
+        when :pass
+          @pastel.green("✅  #{result.message}")
+        when :warn
+          @pastel.yellow("⚠️   #{result.message}")
+        else
+          @pastel.red("❌  #{result.message}")
+        end
+      end
+
+      def render_details(result)
+        files = Array(result.files).compact
+        hint = Guidance.hint_for(result, @platform)
+
+        return if files.empty? && hint.nil?
+
+        if files.any?
+          rendered = files.first(8).join(", ")
+          rendered += " …" if files.length > 8
+          @io.puts @pastel.dim("    files: #{rendered}")
+        end
+
+        @io.puts @pastel.dim("    hint: #{hint}") if hint
+      end
+    end
+  end
+end

data/lib/docktor_rails/result.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module DocktorRails
+  Result = Struct.new(:id, :status, :message, :files, :hint, keyword_init: true) do
+    def to_h
+      h = {
+        id: id,
+        status: status.to_s,
+        message: message,
+        files: Array(files).compact
+      }
+      h[:hint] = hint if hint
+      h.delete(:files) if h[:files].empty?
+      h
+    end
+
+    def pass?
+      status == :pass
+    end
+
+    def warn?
+      status == :warn
+    end
+
+    def fail?
+      status == :fail
+    end
+  end
+end

data/lib/docktor_rails/version.rb

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

data/lib/docktor_rails.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "docktor_rails/version"
+require_relative "docktor_rails/platform"
+require_relative "docktor_rails/guidance"
+require_relative "docktor_rails/cli"
+
+module DocktorRails
+  class Error < StandardError; end
+end

data/sig/docktor_rails.rbs

@@ -0,0 +1,4 @@
+module DocktorRails
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,134 @@
+--- !ruby/object:Gem::Specification
+name: docktor_rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- FAllS
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-06-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pastel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: fakefs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Diagnose common cross-machine Docker/Compose issues in Rails apps (CRLF,
+  missing files/env, healthcheck/readiness risks) with CI-friendly output.
+email:
+- abdullah_alavi@hotmail.com
+executables:
+- docktor_rails
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/docktor_rails
+- lib/docktor_rails.rb
+- lib/docktor_rails/checks/base_check.rb
+- lib/docktor_rails/checks/compose_build_paths.rb
+- lib/docktor_rails/checks/compose_entrypoint_exec.rb
+- lib/docktor_rails/checks/compose_entrypoint_sanity.rb
+- lib/docktor_rails/checks/compose_env_file_present.rb
+- lib/docktor_rails/checks/compose_file_present.rb
+- lib/docktor_rails/checks/compose_healthchecks.rb
+- lib/docktor_rails/checks/compose_platform_risk.rb
+- lib/docktor_rails/checks/rails_master_key_required.rb
+- lib/docktor_rails/checks/shell_scripts_crlf.rb
+- lib/docktor_rails/cli.rb
+- lib/docktor_rails/compose.rb
+- lib/docktor_rails/dotenv.rb
+- lib/docktor_rails/guidance.rb
+- lib/docktor_rails/platform.rb
+- lib/docktor_rails/preflight/runner.rb
+- lib/docktor_rails/reporters/json_reporter.rb
+- lib/docktor_rails/reporters/text_reporter.rb
+- lib/docktor_rails/result.rb
+- lib/docktor_rails/version.rb
+- sig/docktor_rails.rbs
+homepage: https://github.com/fallS/docktor_rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/fallS/docktor_rails
+  source_code_uri: https://github.com/fallS/docktor_rails
+  changelog_uri: https://github.com/fallS/docktor_rails/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Preflight checks for Rails Docker/Compose dev environments
+test_files: []