rails-informant 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebe80aab76837ee09279a0831b344bca9072a873e48b70197868e54a7b5a6ceb
-  data.tar.gz: f637b4e6f460bbb982a2c3f51b49d87cb3fcaa8e6fd2c3547a694fc0f4fa70fc
+  metadata.gz: ef3e66d24feee02958d2d57db85411ec1e19db17fa0cc440936c3f2072016d7c
+  data.tar.gz: a43101bb80bffbad9d1a940d06e2a2d35bc5a8853a2978d5ada0dfdcbd87063d
 SHA512:
-  metadata.gz: '08bf946e26795a53d035667fad63f91ccf5dda9497710a09d9e187d82ee35323ed64397b4761a8af6e81896d915df47e4a6b3f94777e5150fb3250262db6c5ba'
-  data.tar.gz: 8fe9bb913213f18310a90ff232f11c1317246b231aeec3c9afba80c4e253d017dff9e41a829d90df5beee43f9dade333eb4317c24831340b1fdeabf50e068b02
+  metadata.gz: 626124766b399453b846fb37ea492a9cc971206dafcbe5019e050b8adde854f20a55944c84f8906d03c5a55255530480c7599dd3aaf143ac37bc4aca743ae83a
+  data.tar.gz: 8fb18f7ab56d4044601224d6c7c20ffcc77944517738d2a7fded15470fc3a18bb83ae963b6784305145519166d54f887b39e84f34c7ff3b5e2623581fd85096c

data/lib/generators/rails_informant/skill/templates/informant-alerts.sh

@@ -1,61 +1,107 @@
 #!/usr/bin/env bash
-# Informant: On the first Claude Code prompt of a session, check for unresolved
-# production errors — unless that first prompt is the /informant command.
-# Requires: curl, jq
+# Informant: on the first Claude Code prompt of a session, surface two things —
+# an out-of-date Claude Code integration (drift), and unresolved production
+# errors — unless that first prompt is the /informant command. Either channel
+# may fire on its own; when both fire, they share one combined message with a
+# single pause instruction.
+# Requires: jq (and curl, for the production check)
 # Env vars: INFORMANT_PRODUCTION_URL, INFORMANT_PRODUCTION_TOKEN
 #           INFORMANT_PRODUCTION_PATH_PREFIX (optional, default: /informant)
 
 set -euo pipefail
 
-# Silent exit if env vars are missing or URL is not HTTPS
-[[ -z "${INFORMANT_PRODUCTION_URL:-}" ]] && exit 0
-[[ -z "${INFORMANT_PRODUCTION_TOKEN:-}" ]] && exit 0
-[[ "$INFORMANT_PRODUCTION_URL" == https://* ]] || exit 0
-
-# Silent exit if jq is not installed (needed to parse the hook payload)
+# Silent exit if jq is not installed (needed to parse the hook payload).
 command -v jq >/dev/null 2>&1 || exit 0
 
 # UserPromptSubmit delivers a JSON payload on stdin carrying session_id and prompt.
 payload=$(cat)
 session_id=$(printf '%s' "$payload" | jq -r '.session_id // empty' 2>/dev/null || true)
+prompt=$(printf '%s' "$payload" | jq -r '.prompt // empty' 2>/dev/null || true)
 
-# Run at most once per session, on the first prompt: a marker keyed by session_id
-# records that this session was handled, so later prompts short-circuit here before
-# parsing the prompt or doing network work. Require a token-shaped session_id (it is
-# interpolated into the path below) and stay silent when we can't record the marker,
-# rather than re-alerting on every later prompt of the session.
+# Require a token-shaped session_id (it is interpolated into the marker path below).
 [[ "$session_id" =~ ^[A-Za-z0-9_-]+$ ]] || exit 0
+
+# Is the committed Claude Code integration out of date? The Ruby channels (dev
+# boot warning, informant:doctor) write this flag under Rails.root/tmp. This hook
+# reads it relative to the session's working directory, assuming that cwd is the
+# Rails app root. In a monorepo where the Rails root is a subdirectory of the
+# session cwd, this channel stays silent — the boot warning and informant:doctor
+# still cover that case.
+drift=0
+[[ -e "tmp/rails-informant-drift" ]] && drift=1
+
+# Can we check production errors? Needs both env vars and an HTTPS URL.
+production=1
+[[ -z "${INFORMANT_PRODUCTION_URL:-}" ]] && production=0
+[[ -z "${INFORMANT_PRODUCTION_TOKEN:-}" ]] && production=0
+[[ "${INFORMANT_PRODUCTION_URL:-}" == https://* ]] || production=0
+
+# Nothing either channel could say → exit without claiming the session, so a
+# later prompt (e.g. once env vars are set) still gets its chance. This also
+# keeps a drift-free, production-unconfigured app a true silent no-op.
+[[ "$drift" -eq 0 && "$production" -eq 0 ]] && exit 0
+
+# Run at most once per session, on the first prompt: a marker keyed by session_id
+# records that this session was handled, so later prompts short-circuit here.
+# Stay silent when we can't record the marker, rather than re-firing every prompt.
 marker="${TMPDIR:-/tmp}/rails-informant-alert-${session_id}"
 [[ -e "$marker" ]] && exit 0
 : > "$marker" 2>/dev/null || exit 0
 
 # Stay quiet for the whole session when the first prompt is the /informant command —
-# the user is already triaging errors, so the startup alert would be redundant.
-prompt=$(printf '%s' "$payload" | jq -r '.prompt // empty' 2>/dev/null || true)
+# the user is already triaging, so these startup nudges would be redundant.
 [[ "$prompt" =~ ^/informant($|[[:space:]]) ]] && exit 0
 
-path_prefix="${INFORMANT_PRODUCTION_PATH_PREFIX:-/informant}"
-url="${INFORMANT_PRODUCTION_URL}${path_prefix}/api/v1/status"
-
-# Fetch status (silent on failure)
-response=$(curl -s -f \
-  --connect-timeout 3 \
-  --max-time 5 \
-  -H @- \
-  "$url" <<< "Authorization: Bearer ${INFORMANT_PRODUCTION_TOKEN}" \
-  2>/dev/null) || exit 0
-
-# Parse unresolved count (silent exit on a missing or non-numeric value)
-unresolved=$(echo "$response" | jq -r '.unresolved_count // 0' 2>/dev/null) || exit 0
-[[ "$unresolved" =~ ^[0-9]+$ ]] || exit 0
-[[ "$unresolved" -eq 0 ]] && exit 0
-
-# Format error summary
-label="error"
-[[ "$unresolved" -gt 1 ]] && label="errors"
-cat <<ALERT
-🚨 Informant: ${unresolved} unresolved ${label} in production
-$(echo "$response" | jq -r '.top_errors[]? | "  - \(.error_class) (\(.total_occurrences) \(if .total_occurrences == 1 then "occurrence" else "occurrences" end))"' 2>/dev/null || true)
-
-START your response by casually mentioning these errors, then ask the user if they want to investigate or continue with their request. Do NOT proceed with the user's request until they answer.
-ALERT
+# Assemble the data blocks first (the instruction comes last, on purpose).
+body=""
+
+if [[ "$drift" -eq 1 ]]; then
+  body+="🧭 Informant: this app's Claude Code integration is out of date.
+The installed rails-informant gem would now generate different .claude/ files than the ones committed here.
+Update it by running: bin/rails g rails_informant:skill
+"
+fi
+
+errors=0
+if [[ "$production" -eq 1 ]]; then
+  path_prefix="${INFORMANT_PRODUCTION_PATH_PREFIX:-/informant}"
+  url="${INFORMANT_PRODUCTION_URL}${path_prefix}/api/v1/status"
+
+  # Fetch status. A failure here must not suppress a pending drift nudge, so
+  # swallow the error into an empty response rather than exiting.
+  response=$(curl -s -f \
+    --connect-timeout 3 \
+    --max-time 5 \
+    -H @- \
+    "$url" <<< "Authorization: Bearer ${INFORMANT_PRODUCTION_TOKEN}" \
+    2>/dev/null) || response=""
+
+  if [[ -n "$response" ]]; then
+    unresolved=$(printf '%s' "$response" | jq -r '.unresolved_count // 0' 2>/dev/null || echo 0)
+    if [[ "$unresolved" =~ ^[0-9]+$ && "$unresolved" -gt 0 ]]; then
+      label="error"
+      [[ "$unresolved" -gt 1 ]] && label="errors"
+      [[ -n "$body" ]] && body+="
+"
+      body+="🚨 Informant: ${unresolved} unresolved ${label} in production
+$(printf '%s' "$response" | jq -r '.top_errors[]? | "  - \(.error_class) (\(.total_occurrences) \(if .total_occurrences == 1 then "occurrence" else "occurrences" end))"' 2>/dev/null || true)
+"
+      errors=1
+    fi
+  fi
+fi
+
+# Nothing to report (e.g. drift flag absent and zero unresolved errors).
+[[ -z "$body" ]] && exit 0
+
+# One conversational instruction, last — with a specific behavior, a concrete
+# question, and a single explicit pause (see the prompt-engineering notes).
+if [[ "$drift" -eq 1 && "$errors" -eq 1 ]]; then
+  instruction="START your response by casually mentioning both the out-of-date integration (show the one-command fix) and these production errors, then ask the user how they want to proceed — update, investigate, or continue. Do NOT proceed with their request until they answer."
+elif [[ "$drift" -eq 1 ]]; then
+  instruction="START your response by casually mentioning that the integration is out of date and showing the one-command fix, then ask the user whether to update it now or continue with their request. Do NOT proceed with their request until they answer."
+else
+  instruction="START your response by casually mentioning these errors, then ask the user if they want to investigate or continue with their request. Do NOT proceed with the user's request until they answer."
+fi
+
+printf '%s\n%s\n' "$body" "$instruction"

data/lib/generators/rails_informant/skill_generator.rb

@@ -1,8 +1,11 @@
 require "json"
 require "rails/generators"
+require "rails_informant/claude_integration_content"
 
 module RailsInformant
   class SkillGenerator < Rails::Generators::Base
+    Content = ClaudeIntegrationContent
+
     source_root File.expand_path("skill/templates", __dir__)
 
     def copy_skill_file
@@ -16,16 +19,15 @@ module RailsInformant
 
     def create_or_update_mcp_json
       mcp_path = File.join(destination_root, ".mcp.json")
-      informant_entry = { "command" => "informant-mcp" }
 
       if File.exist?(mcp_path)
         existing = JSON.parse(File.read(mcp_path))
         existing["mcpServers"] ||= {}
-        existing["mcpServers"]["informant"] = informant_entry
+        existing["mcpServers"]["informant"] = Content.mcp_entry
         create_file ".mcp.json", JSON.pretty_generate(existing) + "\n", force: true
       else
         create_file ".mcp.json", JSON.pretty_generate(
-          "mcpServers" => { "informant" => informant_entry }
+          "mcpServers" => { "informant" => Content.mcp_entry }
         ) + "\n"
       end
     rescue JSON::ParserError
@@ -34,31 +36,28 @@ module RailsInformant
 
     def create_or_update_settings_json
       settings_path = File.join(destination_root, ".claude", "settings.json")
-      hook_command = ".claude/hooks/informant-alerts.sh"
 
       if File.exist?(settings_path)
         existing = JSON.parse(File.read(settings_path))
-        existing["hooks"] ||= {}
-        existing["hooks"]["UserPromptSubmit"] ||= []
-
-        already_registered = existing["hooks"]["UserPromptSubmit"].any? do |entry|
-          entry["hooks"]&.any? { it["command"] == hook_command }
-        end
-
-        unless already_registered
-          existing["hooks"]["UserPromptSubmit"] << user_prompt_submit_hook(hook_command)
-        end
-
+        existing["hooks"] = migrate_informant_hooks(existing["hooks"])
+        # Coerce a hand-written non-array event value (a lone hook object, a string)
+        # to an array so registering never raises NoMethodError on <<.
+        existing["hooks"][Content::HOOK_EVENT] = [] unless existing["hooks"][Content::HOOK_EVENT].is_a?(Array)
+        existing["hooks"][Content::HOOK_EVENT] << Content.hook_registration
         create_file ".claude/settings.json", JSON.pretty_generate(existing) + "\n", force: true
       else
         create_file ".claude/settings.json", JSON.pretty_generate(
-          "hooks" => { "UserPromptSubmit" => [ user_prompt_submit_hook(hook_command) ] }
+          "hooks" => Content.expected_registrations
         ) + "\n"
       end
     rescue JSON::ParserError
       say "Could not parse existing .claude/settings.json — skipping hook setup.", :red
     end
 
+    def clear_drift_flag
+      RailsInformant::Integration.new(app_root: destination_root).write_drift_flag stale: false
+    end
+
     def print_next_steps
       say ""
       say "Claude Code integration installed!", :green
@@ -82,12 +81,18 @@ module RailsInformant
 
     private
 
-    def user_prompt_submit_hook(command)
-      {
-        "hooks" => [
-          { "type" => "command", "command" => command, "timeout" => 10 }
-        ]
-      }
+    # Remove every prior informant registration (matched by script path) from all
+    # event keys and drop keys left empty, so a re-run migrates a stale
+    # registration (e.g. a leftover SessionStart from an earlier gem version)
+    # instead of adding a second one alongside it. Unrelated hooks are preserved.
+    # Self-heals across future event-key changes rather than hardcoding an event.
+    def migrate_informant_hooks(hooks)
+      hooks = {} unless hooks.is_a?(Hash)
+      hooks.each_value do |entries|
+        entries.reject! { |entry| Content.informant_hook_entry?(entry) } if entries.is_a?(Array)
+      end
+      hooks.reject! { |_event, entries| entries.is_a?(Array) && entries.empty? }
+      hooks
     end
   end
 end

data/lib/rails_informant/claude_integration_content.rb

@@ -0,0 +1,77 @@
+require "json"
+
+module RailsInformant
+  # Single source of truth for the generated Claude Code integration content.
+  #
+  # Both SkillGenerator (generation) and Integration (drift detection) build
+  # their fragments here so the two can never silently diverge. Intentionally
+  # free of any rails/generators (Thor) dependency: Integration runs on the
+  # host-app boot path via the engine initializer, which must not load Thor.
+  module ClaudeIntegrationContent
+    # Paths, relative to the host app root, of the files the generator writes.
+    HOOK_SCRIPT_PATH = ".claude/hooks/informant-alerts.sh"
+    SKILL_PATH = ".claude/skills/informant/SKILL.md"
+    SETTINGS_PATH = ".claude/settings.json"
+    MCP_PATH = ".mcp.json"
+
+    # The command string a settings.json hook entry uses to invoke the script.
+    # Match-by-path detection keys on this value across every event key.
+    HOOK_COMMAND = HOOK_SCRIPT_PATH
+
+    # The event key the current gem registers the hook under.
+    HOOK_EVENT = "UserPromptSubmit"
+
+    module_function
+
+    # Directory of the installed gem, resolved from RubyGems rather than a
+    # generator's source_root so it works on the host-app boot path. Never
+    # RailsInformant::VERSION — that constant is env-driven and resolves to the
+    # 0.0.0.dev fallback in host apps.
+    def gem_dir
+      Gem.loaded_specs["rails-informant"].gem_dir
+    end
+
+    def templates_dir
+      File.join gem_dir, "lib", "generators", "rails_informant", "skill", "templates"
+    end
+
+    def hook_script
+      File.read File.join(templates_dir, "informant-alerts.sh")
+    end
+
+    def skill_markdown
+      File.read File.join(templates_dir, "SKILL.md")
+    end
+
+    # The informant server entry inside .mcp.json's "mcpServers".
+    def mcp_entry
+      { "command" => "informant-mcp" }
+    end
+
+    # A single UserPromptSubmit hook registration for settings.json.
+    def hook_registration
+      {
+        "hooks" => [
+          { "type" => "command", "command" => HOOK_COMMAND, "timeout" => 10 }
+        ]
+      }
+    end
+
+    # The informant-owned hooks map the generator produces: the registration
+    # keyed by its event. Detection compares the host app's extracted informant
+    # registrations against this, so a leftover entry under a different event key
+    # (e.g. a stale SessionStart) reads as drift.
+    def expected_registrations
+      { HOOK_EVENT => [ hook_registration ] }
+    end
+
+    # Whether a settings.json hook entry targets the informant script — the
+    # shared match-by-path predicate used by both generation (to sweep stale
+    # registrations) and detection (to extract the informant fragment).
+    def informant_hook_entry?(entry)
+      entry.is_a?(Hash) && Array(entry["hooks"]).any? do |hook|
+        hook.is_a?(Hash) && hook["command"] == HOOK_COMMAND
+      end
+    end
+  end
+end

data/lib/rails_informant/doctor.rb

@@ -0,0 +1,53 @@
+require "rails_informant/integration"
+
+module RailsInformant
+  # The informant:doctor channel: reports the integration state, prints the fix,
+  # refreshes the drift flag, and returns a process exit code (nonzero on stale
+  # or error) so it doubles as a CI signal. A thin wrapper over Integration that
+  # never raises out — a diagnostic must not crash the run it reports on.
+  class Doctor
+    def initialize(integration: Integration.new, io: $stdout)
+      @integration = integration
+      @io = io
+    end
+
+    def run
+      status = @integration.status
+      @integration.write_drift_flag stale: status == :stale
+      @io.puts report_for(status)
+      exit_code_for status
+    rescue StandardError => e
+      # An unexpected failure must exit nonzero, not 0 — a doctor wired into CI
+      # to gate drift must never report a false green when it could not check.
+      @io.puts "[Informant] doctor could not complete: #{e.message}"
+      1
+    end
+
+    private
+
+    def report_for(status)
+      case status
+      when :current
+        "[Informant] Claude Code integration is up to date."
+      when :not_installed
+        "[Informant] Claude Code integration is not installed — nothing to check."
+      when :stale
+        <<~REPORT.chomp
+          [Informant] Claude Code integration is OUT OF DATE.
+          The installed gem would generate different .claude/ files than this app has committed.
+          Fix: bin/rails g rails_informant:skill
+        REPORT
+      when :error
+        <<~REPORT.chomp
+          [Informant] Claude Code integration could not be verified.
+          .claude/settings.json or .mcp.json is present but is not valid JSON.
+          Fix that file by hand — re-running the generator skips unparseable files.
+        REPORT
+      end
+    end
+
+    def exit_code_for(status)
+      status == :stale || status == :error ? 1 : 0
+    end
+  end
+end

data/lib/rails_informant/engine.rb

@@ -56,6 +56,33 @@ module RailsInformant
       config.after_initialize { RailsInformant::Engine.validate_api_token! }
     end
 
+    initializer "rails_informant.check_integration_drift" do
+      config.after_initialize { RailsInformant::Engine.check_integration_drift! }
+    end
+
+    # Dev-only, warn-only nudge: when the committed .claude/ integration has
+    # drifted from what the installed gem would generate now, log the one-command
+    # fix and refresh the drift flag the hook reads. Silent when current,
+    # not_installed, error, or in production; never raises out (a drift check must
+    # not break boot).
+    def self.check_integration_drift!
+      return unless Rails.env.development? && (RailsInformant.server_mode? || RailsInformant.console_mode?)
+
+      integration = RailsInformant::Integration.new
+      status = integration.status
+      integration.write_drift_flag stale: status == :stale
+
+      return unless status == :stale
+
+      Rails.logger&.warn <<~MSG.squish
+        [Informant] Your Claude Code integration is out of date — the installed
+        gem would generate different .claude/ files than this app has committed.
+        Run `bin/rails g rails_informant:skill` to update it.
+      MSG
+    rescue StandardError
+      # Never break boot over a drift check.
+    end
+
     MINIMUM_TOKEN_LENGTH = 32
 
     def self.validate_api_token!

data/lib/rails_informant/integration.rb

@@ -0,0 +1,202 @@
+require "digest"
+require "fileutils"
+require "json"
+require "pathname"
+require "rails_informant/claude_integration_content"
+
+module RailsInformant
+  # Classifies the host app's committed Claude Code integration by comparing its
+  # live .claude/ files against what the installed gem would generate now. The
+  # detection primitive behind the three drift channels (boot warning, doctor,
+  # hook nudge); Rails-boot-independent and unit-testable in isolation.
+  #
+  # Internals may raise (missing gem spec, unreadable templates); each channel
+  # wraps a single top-level rescue so a drift check never breaks boot or CI.
+  # The one exception is #write_drift_flag, which is best-effort by nature and
+  # swallows its own IO failures.
+  class Integration
+    Content = ClaudeIntegrationContent
+
+    DRIFT_FLAG = "rails-informant-drift"
+
+    # Fixed order so the digest is deterministic across runs.
+    COMPONENTS = %w[hook mcp settings skill].freeze
+
+    def initialize(app_root: Rails.root)
+      @app_root = Pathname(app_root)
+    end
+
+    # :not_installed | :current | :stale | :error
+    #
+    # not_installed wins first so apps that use the gem only for error capture
+    # are never nagged. error (a present-but-unparseable settings.json/.mcp.json)
+    # is distinct from stale because re-running the generator skips unparseable
+    # files — it could never clear a stale reported on one.
+    def status
+      return :not_installed unless installed?
+      return :error if json_error?
+
+      live_digest == expected_digest ? :current : :stale
+    end
+
+    def installed?
+      hook_script_present? || settings_informant_present? || mcp_informant_present?
+    end
+
+    def stale?
+      status == :stale
+    end
+
+    # Display only — the drift decision uses the digest, not the version. Harmless
+    # that local path/git installs report 0.0.0.dev here; only published installs
+    # show a real number.
+    def gem_version
+      Gem.loaded_specs["rails-informant"]&.version&.to_s
+    end
+
+    def drift_flag_path
+      @app_root.join "tmp", DRIFT_FLAG
+    end
+
+    # Best-effort: the Ruby channels refresh this flag so the bash hook can read
+    # drift without loading Ruby. Never raises out — a read-only tmp/ must not
+    # break a dev boot or a doctor run.
+    def write_drift_flag(stale:)
+      if stale
+        FileUtils.mkdir_p drift_flag_path.dirname
+        drift_flag_path.write "The Claude Code integration is out of date. " \
+          "Run `bin/rails g rails_informant:skill` to update it.\n"
+      elsif drift_flag_path.exist?
+        drift_flag_path.delete
+      end
+    rescue SystemCallError
+      nil
+    end
+
+    private
+
+    def hook_path = @app_root.join(Content::HOOK_SCRIPT_PATH)
+    def skill_path = @app_root.join(Content::SKILL_PATH)
+    def settings_path = @app_root.join(Content::SETTINGS_PATH)
+    def mcp_path = @app_root.join(Content::MCP_PATH)
+
+    def hook_script_present? = hook_path.exist?
+
+    def settings_informant_present?
+      registrations = live_settings_registrations
+      registrations && !registrations.empty?
+    end
+
+    def mcp_informant_present?
+      !live_mcp_entry.nil?
+    end
+
+    def json_error?
+      parse_failed?(settings_path) || parse_failed?(mcp_path)
+    end
+
+    # --- digest -------------------------------------------------------------
+
+    def expected_digest
+      digest_of(
+        "hook" => normalize_text(Content.hook_script),
+        "skill" => normalize_text(Content.skill_markdown),
+        "settings" => canonical_json(Content.expected_registrations),
+        "mcp" => canonical_json(Content.mcp_entry)
+      )
+    end
+
+    def live_digest
+      digest_of(
+        "hook" => normalize_text(read_or_empty(hook_path)),
+        "skill" => normalize_text(read_or_empty(skill_path)),
+        "settings" => canonical_json(live_settings_registrations || {}),
+        "mcp" => canonical_json(live_mcp_entry || {})
+      )
+    end
+
+    def digest_of(components)
+      material = COMPONENTS.map { |name| "#{name}:#{components[name]}" }.join("\n")
+      Digest::SHA256.hexdigest material
+    end
+
+    # --- live extraction ----------------------------------------------------
+
+    # The informant-owned hook registrations, keyed by event, swept from every
+    # event key by script path. nil when settings.json is absent or unparseable.
+    def live_settings_registrations
+      settings = parsed_json(settings_path) or return nil
+      hooks = settings["hooks"]
+      return {} unless hooks.is_a?(Hash)
+
+      hooks.each_with_object({}) do |(event, entries), result|
+        next unless entries.is_a?(Array)
+
+        informant = entries.select { |entry| Content.informant_hook_entry?(entry) }
+        result[event] = informant unless informant.empty?
+      end
+    end
+
+    # The informant server entry from .mcp.json, or nil when absent/unparseable.
+    def live_mcp_entry
+      mcp = parsed_json(mcp_path) or return nil
+      mcp.dig "mcpServers", "informant"
+    end
+
+    # --- json / text helpers ------------------------------------------------
+
+    # Read and parse each JSON file at most once per instance. Instances are
+    # created fresh per channel call, so this both removes the redundant reads
+    # and lets installed?/json_error?/the digest classify from one consistent
+    # snapshot (no split read where one path sees the file valid and another a
+    # concurrent edit).
+    def json_state(path)
+      @_json_states ||= {}
+      @_json_states[path] ||= compute_json_state(path)
+    end
+
+    def compute_json_state(path)
+      return [ :absent, nil ] unless path.exist?
+
+      [ :ok, JSON.parse(path.read) ]
+    rescue JSON::ParserError
+      [ :error, nil ]
+    end
+
+    def parsed_json(path)
+      state, data = json_state(path)
+      state == :ok ? data : nil
+    end
+
+    def parse_failed?(path)
+      json_state(path).first == :error
+    end
+
+    def read_or_empty(path)
+      path.exist? ? path.read : ""
+    end
+
+    # Canonical JSON: recursively sort hash keys so a host-side key reorder in a
+    # JSON fragment does not read as drift.
+    def canonical_json(object)
+      JSON.generate deep_sort(object)
+    end
+
+    def deep_sort(object)
+      case object
+      when Hash then object.keys.sort.each_with_object({}) { |key, sorted| sorted[key] = deep_sort(object[key]) }
+      when Array then object.map { |element| deep_sort(element) }
+      else object
+      end
+    end
+
+    # Strip a leading BOM, normalize line endings, and trim trailing whitespace so
+    # host-side encoding noise (CRLF via .gitattributes, an EditorConfig
+    # trim/final-newline rule, a BOM-prepending editor) does not byte-diverge into
+    # a permanent stale. Content reformatting (reindentation, blank-line collapse)
+    # is intentionally out of scope — it would risk masking real drift.
+    def normalize_text(text)
+      text.delete_prefix("\uFEFF").gsub(/\r\n?/, "\n").split("\n", -1).map(&:rstrip).join("\n").sub(/\n+\z/, "")
+    end
+  end
+end

data/lib/rails_informant.rb

@@ -25,13 +25,16 @@ module RailsInformant
 
   autoload :BreadcrumbBuffer, "rails_informant/breadcrumb_buffer"
   autoload :BreadcrumbSubscriber, "rails_informant/breadcrumb_subscriber"
+  autoload :ClaudeIntegrationContent, "rails_informant/claude_integration_content"
   autoload :ContextBuilder, "rails_informant/context_builder"
   autoload :ContextFilter, "rails_informant/context_filter"
   autoload :Current, "rails_informant/current"
+  autoload :Doctor, "rails_informant/doctor"
   autoload :ErrorRecorder, "rails_informant/error_recorder"
   autoload :ErrorSubscriber, "rails_informant/error_subscriber"
   autoload :Event, "rails_informant/event"
   autoload :Fingerprint, "rails_informant/fingerprint"
+  autoload :Integration, "rails_informant/integration"
   autoload :StructuredEventSubscriber, "rails_informant/structured_event_subscriber"
 
   module Middleware

data/lib/tasks/rails_informant.rake

@@ -1,4 +1,9 @@
 namespace :informant do
+  desc "Report whether the Claude Code integration is current, stale, or not installed"
+  task doctor: :environment do
+    exit RailsInformant::Doctor.new.run
+  end
+
   desc "Purge resolved errors older than retention_days"
   task purge: :environment do
     RailsInformant::PurgeJob.perform_now

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-informant
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Daniel López Prat
@@ -136,15 +136,18 @@ files:
 - lib/rails_informant.rb
 - lib/rails_informant/breadcrumb_buffer.rb
 - lib/rails_informant/breadcrumb_subscriber.rb
+- lib/rails_informant/claude_integration_content.rb
 - lib/rails_informant/configuration.rb
 - lib/rails_informant/context_builder.rb
 - lib/rails_informant/context_filter.rb
 - lib/rails_informant/current.rb
+- lib/rails_informant/doctor.rb
 - lib/rails_informant/engine.rb
 - lib/rails_informant/error_recorder.rb
 - lib/rails_informant/error_subscriber.rb
 - lib/rails_informant/event.rb
 - lib/rails_informant/fingerprint.rb
+- lib/rails_informant/integration.rb
 - lib/rails_informant/mcp.rb
 - lib/rails_informant/mcp/base_tool.rb
 - lib/rails_informant/mcp/client.rb