docktor_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3e9a0546a0a1bfb8849cd3c5f8cd2767f5a49ac7c3e8077fb1be9f964e494fc9
+  data.tar.gz: '0099dfd0a1ad6f689a02c321a75e3e6e95a619abd17186becc0630ddae2c5ce4'
+SHA512:
+  metadata.gz: 69695f70efc8e1aee5a28ee5696e14244430c3fc251ff414097d400508bc2f1e940f526b9ed7d14aa82d8f97d9d3ceae185dbf1d6960cb9aa05c891ec2c9557a
+  data.tar.gz: f8c1911b3b59b0b3bec51d9033f3bb6d1f6264fb9cca7deb2c013ed34e07d4ea15b567b5c78c780dd62335f30168f58d3f18f1f5f47dfe113daea2c455c3778a

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.0
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-06-11
+
+- Initial release
+- Added preflight checks for Compose file presence, build path validity, env_file presence, entrypoint sanity/exec, CRLF in shell scripts, db/redis healthcheck warnings, platform pin risk, and Rails master key availability.
+- Added `--root` for scanning a target directory.
+- Added `--format json` output with context (host OS/arch, root).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 FAllS
+
+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,70 @@
+# DocktorRails
+DocktorRails is a tiny preflight checker for Rails Docker/Compose dev environments.
+It catches common cross-machine issues early (CRLF shell scripts, missing compose-referenced files, build path mistakes, platform pinning risk) and provides CI-friendly JSON output.
+
+## Installation
+Add it to your Rails app:
+
+```bash
+bundle add docktor_rails
+```
+
+## Usage
+Run in your project root:
+
+```bash
+bundle exec docktor_rails diagnose
+```
+
+Scan another directory (useful in mono-repos):
+
+```bash
+bundle exec docktor_rails diagnose --root ../some_app
+```
+
+CI/automation (JSON):
+
+```bash
+bundle exec docktor_rails diagnose --format json --output preflight.json
+```
+
+Options:
+- `--verbose`: show passing checks
+- `--quiet`: only show errors/warnings + summary (good for CI logs)
+
+## Exit codes
+- `0`: no failing checks
+- `1`: one or more failing checks
+- `2`: tool/internal error
+
+## GitHub Actions example
+
+```yaml
+name: Preflight
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  preflight:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+      - run: bundle exec docktor_rails diagnose --format json --output preflight.json
+      - if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docktor-rails-preflight
+          path: preflight.json
+```
+
+## Contributing
+Issues and pull requests are welcome.
+
+## License
+MIT

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[spec]
+
+# Optional lint task (not required for build/publish)
+begin
+  require "rubocop/rake_task"
+  RuboCop::RakeTask.new
+  task lint: :rubocop
+rescue LoadError
+  # rubocop not installed
+end

data/exe/docktor_rails

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "docktor_rails"
+
+DocktorRails::CLI.start(ARGV)

data/lib/docktor_rails/checks/base_check.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../result"
+
+module DocktorRails
+  module Checks
+    class BaseCheck
+      def id
+        raise NotImplementedError
+      end
+
+      def name
+        id
+      end
+
+      def run(_ctx)
+        raise NotImplementedError
+      end
+
+      private
+
+      def pass(message, files: nil, hint: nil)
+        Result.new(id: id, status: :pass, message: message, files: files, hint: hint)
+      end
+
+      def warn(message, files: nil, hint: nil)
+        Result.new(id: id, status: :warn, message: message, files: files, hint: hint)
+      end
+
+      def fail(message, files: nil, hint: nil)
+        Result.new(id: id, status: :fail, message: message, files: files, hint: hint)
+      end
+    end
+  end
+end

data/lib/docktor_rails/checks/compose_build_paths.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "base_check"
+require_relative "../compose"
+
+module DocktorRails
+  module Checks
+    class ComposeBuildPaths < BaseCheck
+      def id
+        "compose.build_paths"
+      end
+
+      def run(ctx)
+        root = ctx.fetch(:root)
+        compose_path = Compose.find_file(root)
+        return pass("No compose file found (skipping build path check)") unless compose_path
+
+        doc = Compose.load_file(compose_path)
+        services = Compose.services(doc)
+
+        problems = []
+
+        services.each do |svc_name, svc|
+          next unless svc.is_a?(Hash)
+
+          build = svc["build"]
+          next if build.nil?
+
+          context, dockerfile = extract_build(build)
+          context ||= "."
+
+          context_abs = File.expand_path(context, root)
+          unless Dir.exist?(context_abs)
+            problems << "#{svc_name}: build.context missing (#{context})"
+            next
+          end
+
+          dockerfile ||= "Dockerfile"
+          dockerfile_abs = File.expand_path(dockerfile, context_abs)
+          unless File.file?(dockerfile_abs)
+            problems << "#{svc_name}: build.dockerfile missing (#{File.join(context, dockerfile)})"
+          end
+        end
+
+        if problems.empty?
+          pass("Compose build paths look valid")
+        else
+          fail("Compose build path issues detected", files: problems)
+        end
+      end
+
+      private
+
+      def extract_build(build)
+        case build
+        when String
+          [build, nil]
+        when Hash
+          [build["context"], build["dockerfile"]]
+        else
+          [nil, nil]
+        end
+      end
+    end
+  end
+end

data/lib/docktor_rails/checks/compose_entrypoint_exec.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "base_check"
+require_relative "../compose"
+
+module DocktorRails
+  module Checks
+    class ComposeEntrypointExec < BaseCheck
+      def id
+        "compose.entrypoint_exec"
+      end
+
+      def run(ctx)
+        root = ctx.fetch(:root)
+        platform = ctx[:platform]
+
+        if platform&.windows?
+          return pass("Windows host: skipping executable/shebang checks")
+        end
+
+        compose_path = Compose.find_file(root)
+        return pass("No compose file found (skipping entrypoint exec check)") unless compose_path
+
+        doc = Compose.load_file(compose_path)
+        services = Compose.services(doc)
+
+        entrypoint_files = services.flat_map do |_svc_name, svc|
+          next [] unless svc.is_a?(Hash)
+
+          ep = svc["entrypoint"]
+          ep = normalize_entrypoint(ep)
+          next [] unless ep
+
+          file = entrypoint_file_candidate(ep)
+          file ? [file] : []
+        end
+
+        entrypoint_files.uniq!
+        return pass("No entrypoint file paths detected") if entrypoint_files.empty?
+
+        problems = []
+
+        entrypoint_files.each do |file|
+          abs = File.expand_path(file, root)
+          next unless File.file?(abs) # existence handled elsewhere
+
+          problems << "#{file}: not executable" unless File.executable?(abs)
+
+          first = File.open(abs, "rb", &:readline) rescue ""
+          problems << "#{file}: missing shebang" unless first.start_with?("#!")
+        end
+
+        if problems.empty?
+          pass("Entrypoint executable/shebang OK")
+        else
+          fail("Entrypoint executable/shebang issues detected", files: problems)
+        end
+      end
+
+      private
+
+      def normalize_entrypoint(value)
+        case value
+        when Array
+          value.first
+        when String
+          value.strip
+        else
+          nil
+        end
+      end
+
+      def entrypoint_file_candidate(entrypoint)
+        first = entrypoint.split(/\s+/).first
+        return nil if first.nil? || first.empty?
+
+        looks_like_path = first.include?("/") || first.end_with?(".sh") || first.start_with?(".")
+        looks_like_path ? first : nil
+      end
+    end
+  end
+end

data/lib/docktor_rails/checks/compose_entrypoint_sanity.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "base_check"
+require_relative "../compose"
+
+module DocktorRails
+  module Checks
+    class ComposeEntrypointSanity < BaseCheck
+      def id
+        "compose.entrypoint_sanity"
+      end
+
+      def run(ctx)
+        root = ctx.fetch(:root)
+        compose_path = Compose.find_file(root)
+        return pass("No compose file found (skipping entrypoint check)") unless compose_path
+
+        doc = Compose.load_file(compose_path)
+        services = Compose.services(doc)
+
+        entrypoints = services.flat_map do |svc_name, svc|
+          next [] unless svc.is_a?(Hash)
+
+          ep = svc["entrypoint"]
+          ep = normalize_entrypoint(ep)
+          next [] unless ep
+
+          [{ service: svc_name, entrypoint: ep }]
+        end
+
+        return pass("No compose entrypoints referenced") if entrypoints.empty?
+
+        failures = []
+        entrypoints.each do |ep|
+          file = entrypoint_file_candidate(ep.fetch(:entrypoint))
+          next unless file
+
+          abs = File.expand_path(file, root)
+          unless abs.start_with?(File.expand_path(root) + File::SEPARATOR)
+            failures << { file: file, message: "entrypoint points outside repo root" }
+            next
+          end
+
+          unless File.file?(abs)
+            failures << { file: file, message: "file not found" }
+            next
+          end
+
+          if File.binread(abs).include?("\r\n")
+            failures << { file: file, message: "CRLF line endings" }
+          end
+        end
+
+        if failures.empty?
+          pass("Entrypoint files look sane")
+        else
+          files = failures.map { |f| f.fetch(:file) }
+          fail("Compose entrypoint issues detected", files: files, hint: "Ensure entrypoint scripts exist and use LF line endings (not CRLF).")
+        end
+      end
+
+      private
+
+      def normalize_entrypoint(value)
+        case value
+        when Array
+          value.first
+        when String
+          value.strip
+        else
+          nil
+        end
+      end
+
+      def entrypoint_file_candidate(entrypoint)
+        return nil if entrypoint.nil? || entrypoint.empty?
+
+        # Strings like "bash -lc ..." are commands, not file paths.
+        first = entrypoint.split(/\s+/).first
+        return nil if first.nil? || first.empty?
+
+        looks_like_path = first.include?("/") || first.end_with?(".sh") || first.start_with?(".")
+        looks_like_path ? first : nil
+      end
+    end
+  end
+end

data/lib/docktor_rails/checks/compose_env_file_present.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "base_check"
+require_relative "../compose"
+
+module DocktorRails
+  module Checks
+    class ComposeEnvFilePresent < BaseCheck
+      def id
+        "compose.env_file_present"
+      end
+
+      def run(ctx)
+        root = ctx.fetch(:root)
+        compose_path = Compose.find_file(root)
+        return pass("No compose file found (skipping env_file check)") unless compose_path
+
+        doc = Compose.load_file(compose_path)
+        services = Compose.services(doc)
+
+        missing = []
+        services.each do |_name, svc|
+          next unless svc.is_a?(Hash)
+
+          env_file = svc["env_file"]
+          files = case env_file
+          when String then [env_file]
+          when Array then env_file
+          else []
+          end
+
+          files.each do |f|
+            next unless f.is_a?(String)
+            path = File.expand_path(f, root)
+            missing << f unless File.file?(path)
+          end
+        end
+
+        if missing.empty?
+          pass("All compose env_file entries exist")
+        else
+          fail("Missing compose env_file files", files: missing.uniq.sort)
+        end
+      end
+    end
+  end
+end

data/lib/docktor_rails/checks/compose_file_present.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "base_check"
+
+module DocktorRails
+  module Checks
+    class ComposeFilePresent < BaseCheck
+      CANDIDATES = ["compose.yml", "docker-compose.yml"].freeze
+
+      def id
+        "compose.file_present"
+      end
+
+      def run(ctx)
+        root = ctx.fetch(:root)
+        found = CANDIDATES.map { |f| File.join(root, f) }.find { |p| File.file?(p) }
+
+        if found
+          pass("Compose file present", files: [relative_to_root(found, root)])
+        else
+          fail("No compose.yml or docker-compose.yml found", hint: "Add a compose.yml (or docker-compose.yml) at the repo root.")
+        end
+      end
+
+      private
+
+      def relative_to_root(path, root)
+        path.delete_prefix(root + File::SEPARATOR)
+      end
+    end
+  end
+end

data/lib/docktor_rails/checks/compose_healthchecks.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "base_check"
+require_relative "../compose"
+
+module DocktorRails
+  module Checks
+    class ComposeHealthchecks < BaseCheck
+      def id
+        "compose.healthchecks"
+      end
+
+      def run(ctx)
+        root = ctx.fetch(:root)
+        compose_path = Compose.find_file(root)
+        return pass("No compose file found (skipping healthcheck check)") unless compose_path
+
+        doc = Compose.load_file(compose_path)
+        services = Compose.services(doc)
+
+        targets = %w[db redis].select { |name| services.key?(name) }
+        return pass("No db/redis services detected") if targets.empty?
+
+        missing = targets.reject do |name|
+          svc = services[name]
+          svc.is_a?(Hash) && svc.key?("healthcheck") && !svc["healthcheck"].nil?
+        end
+
+        if missing.empty?
+          pass("Healthchecks present for db/redis")
+        else
+          warn("Missing healthchecks for: #{missing.join(", ")}", hint: "Add compose healthchecks so readiness is deterministic across machines.")
+        end
+      end
+    end
+  end
+end

data/lib/docktor_rails/checks/compose_platform_risk.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "base_check"
+require_relative "../compose"
+
+module DocktorRails
+  module Checks
+    class ComposePlatformRisk < BaseCheck
+      def id
+        "compose.platform_risk"
+      end
+
+      def run(ctx)
+        root = ctx.fetch(:root)
+        platform = ctx[:platform]
+        compose_path = Compose.find_file(root)
+        return pass("No compose file found (skipping platform check)") unless compose_path
+
+        return pass("Unknown host architecture (skipping platform risk)") if platform.nil? || platform.arch == :unknown
+
+        doc = Compose.load_file(compose_path)
+        services = Compose.services(doc)
+
+        pins = services.filter_map do |name, svc|
+          next unless svc.is_a?(Hash)
+          p = svc["platform"]
+          next unless p.is_a?(String)
+          [name, p]
+        end
+
+        return pass("No compose platform pins") if pins.empty?
+
+        risky = pins.select { |_name, p| mismatch?(platform, p) }
+
+        if risky.empty?
+          pass("Compose platform pins match host")
+        else
+          warn("Compose platform pins may not match this host", files: risky.map { |n, p| "#{n}: #{p}" })
+        end
+      end
+
+      private
+
+      def mismatch?(platform, pin)
+        pin = pin.downcase
+        return platform.arm64? && pin.include?("amd64")
+        return platform.amd64? && (pin.include?("arm64") || pin.include?("aarch64"))
+
+        false
+      end
+    end
+  end
+end

data/lib/docktor_rails/checks/rails_master_key_required.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "base_check"
+require_relative "../dotenv"
+
+module DocktorRails
+  module Checks
+    class RailsMasterKeyRequired < BaseCheck
+      def id
+        "env.rails_master_key"
+      end
+
+      def run(ctx)
+        root = ctx.fetch(:root)
+
+        encrypted_files = encrypted_credentials_files(root)
+        return pass("No encrypted credentials detected") if encrypted_files.empty?
+
+        # Satisfy via file (common for local dev).
+        master_key_path = File.join(root, "config", "master.key")
+        if File.file?(master_key_path) && !File.read(master_key_path).strip.empty?
+          return pass("master.key present", files: ["config/master.key"])
+        end
+
+        # Or via environment variable (common for CI/prod).
+        if ENV.key?("RAILS_MASTER_KEY") && !ENV.fetch("RAILS_MASTER_KEY").to_s.empty?
+          return pass("RAILS_MASTER_KEY is set in ENV")
+        end
+
+        # Or via dotenv file commonly used for docker/compose flows.
+        dotenv_path = File.join(root, ".env.docker")
+        dotenv = Dotenv.parse_file(dotenv_path)
+        if dotenv.key?("RAILS_MASTER_KEY") && !dotenv.fetch("RAILS_MASTER_KEY").to_s.empty?
+          return pass("RAILS_MASTER_KEY present in .env.docker", files: [".env.docker"])
+        end
+
+        fail(
+          "Missing master key for encrypted credentials",
+          files: encrypted_files,
+          hint: "Provide config/master.key (local), or set RAILS_MASTER_KEY (CI/prod), or add it to .env.docker."
+        )
+      end
+
+      private
+
+      def encrypted_credentials_files(root)
+        files = []
+
+        default = File.join(root, "config", "credentials.yml.enc")
+        files << "config/credentials.yml.enc" if File.file?(default)
+
+        # Rails also supports per-environment credentials in config/credentials/*.yml.enc
+        Dir.glob(File.join(root, "config", "credentials", "*.yml.enc")).each do |path|
+          rel = path.delete_prefix(root + File::SEPARATOR)
+          files << rel
+        end
+
+        files.uniq
+      end
+    end
+  end
+end