rails-ai-context 5.35.0 → 5.35.2

data/docs/adr/0008-query-runs-only-where-it-can-guard.md

@@ -0,0 +1,38 @@
+# rails_query runs only on a database family it can guard
+
+Status: accepted
+
+`rails_query` promises two guards the database itself enforces: a read-only transaction and a statement timeout. Each database server spells both differently, and some cannot give one at all, so the tool runs a statement only where it knows the spelling. A **database family** is that knowledge: one per kind of database, told by the adapter's name, and the only place a database's read-only and timeout rules live. `rails_query` reads the name from the database's configuration, before any connection opens.
+
+## Decision
+
+- Three families: PostgreSQL (PostGIS too), MySQL (Trilogy and MariaDB too) and SQLite. Any other adapter gets a refusal that names it before anything reaches the database. Statistics answers (table sizes, row estimates, index usage) say "not available" for it instead.
+- A family is claimed by the adapter's name alone, as `adapter_name` and database.yml spell it. CockroachDB's adapter subclasses PostgreSQL's, but it has no `EXPLAIN (FORMAT JSON)` and its own read-only rules, so it is refused until someone verifies them.
+- The timeout per family:
+  - PostgreSQL: `SET LOCAL statement_timeout` inside the read-only transaction, at one millisecond or more, since zero turns the timeout off.
+  - MySQL: the session's `max_execution_time`, read first, set for the statement and restored after. The `MAX_EXECUTION_TIME` hint binds only the outermost SELECT and leaves a statement that starts with WITH or EXPLAIN with no bound, so it is not used.
+  - MariaDB: the session's `max_statement_time`, read first, set for the statement and restored after. MariaDB ignores the MySQL hint and has no `max_execution_time`.
+  - SQLite: a forked child with a deadline, since sqlite3-ruby holds the interpreter lock while a statement steps and nothing in the process can end it. A statement runs on the app's own connection in five cases: an in-memory database, a platform without `fork`, a statement the child cannot prepare, a transaction open on that connection, and, while that connection holds a temp object or an attachment, a statement that names one of them, the temp catalog or schema, or calls a pragma function or `dbstat`. There a watchdog's interrupt ends a statement that returns rows slowly.
+- What bounds each kind of statement a call sends:
+  - The query and `explain: true` have `query_timeout` to themselves: `statement_timeout` on PostgreSQL, the session's statement limit with `lock_wait_timeout` on MySQL and MariaDB, the child's deadline on SQLite.
+  - The reads beside the query (the schema, the PostgreSQL plan with its `pg_proc` lookup, the column trace) run in a block the family bounds the same way. They share a second `query_timeout`, and each is charged the time it ran. On SQLite they run on the app's own connection with no statement limit, and a wait on another writer ends at its busy timeout.
+  - `rails_runtime_info`'s table sizes, index usage and pending migrations each run in such a block with `query_timeout` of their own.
+- Stated limits of the bound:
+  - SQLite cannot end one long step on the app's own connection: an interrupt lands only between two rows. That run is reported as one without a time limit.
+  - PostgreSQL has no client read timeout. `statement_timeout` is the server's to keep, so a server that goes silent after it connects is not ended by the client. A leased MySQL or MariaDB connection gets a `read_timeout` of twice `query_timeout` plus 5 seconds unless its entry sets one.
+  - MySQL and MariaDB take `lock_wait_timeout` in whole seconds. It is set because their statement limit does not cover `EXPLAIN` or `SHOW`, and a wait on a lock ends at `query_timeout` rounded up to the next second.
+  - MySQL's statement limit holds `SELECT` only, so the gate refuses `SHOW` with a `WHERE` clause on every family.
+- A timeout is recognised by `ActiveRecord::QueryAborted` (QueryCanceled, StatementTimeout) or by the database's native code. MariaDB's 1969 has no Rails class in any version. Message text is never read, so a missing column named "timeout" is reported as an SQL error.
+- The statement checks before execution stay on every family. MySQL's read-only transaction lets `FOR SHARE`, `LOCK IN SHARE MODE`, `INTO @var` and `INTO OUTFILE` through, so it cannot be the only guard.
+- Only PostgreSQL traces a result column to its table column, through the statement's plan, so there a statement runs only with a plan. MySQL, MariaDB and SQLite have no such trace. There a view is checked by the definition the database stores and refused when it names a secret column, and a `*` inside a subquery is refused when the statement names a table that holds one. A PostgreSQL materialized view stores its rows, so the plan traces none of its columns either, and it is held to the same view rule.
+- A guarded read leaves an open transaction as it found it: a savepoint on PostgreSQL, and a refusal on MySQL and MariaDB, which cannot make an open transaction read-only.
+
+## Consequences
+
+Apps on SQL Server, Oracle or CockroachDB have no `rails_query`. On SQL Server and Oracle the `LIMIT` its row cap appends is a syntax error, so a query without its own row limit fails there. Supporting another database means adding a family with its own read-only and timeout spelling, verified against a real server.
+
+## Alternatives not taken
+
+- **Running other adapters on the statement checks alone**: the tool's description promises database-level guards, and a check on text is not one.
+- **Classifying by class ancestry**: it would admit a database whose guards nobody has run.
+- **Injecting the MySQL hint after a WITH list**: it needs a parse of the statement to find the outermost SELECT. The session variable needs none, and it bounds EXPLAIN ANALYZE too.

data/docs/adr/0009-dbhub-shapes-in-ruby.md

@@ -0,0 +1,26 @@
+# rails_query stays in Ruby and takes dbhub's shapes
+
+Status: accepted
+
+bytebase/dbhub is a database MCP server: one connector per kind of database, named sources, a single read-only policy, and two tools by default. The 2026-10 architecture review read this gem through it and asked whether `rails_query` should hand its work to dbhub outright.
+
+## Decision
+
+- `rails_query` stays the gem's own. dbhub needs Node 22.5 or later, while this gem is pure Ruby. dbhub connects by DSN; `rails_query` runs on the app's own connection, so database.yml, SSL settings, SQLite extensions and app-registered functions all apply. dbhub returns column values unredacted, and the **secret column** rule is this tool's main safety property. The production guard and the static-tier refusal would also go.
+- The shapes come over:
+  - one adapter per **database family** (dbhub's connector), ADR-0008;
+  - one list of **app databases** with the primary first (dbhub's named sources);
+  - one module deciding what a statement may do (dbhub's access policy): the **SQL gate**, with the **secret column** rule beside it;
+  - one answer to which tools are served;
+  - a short default tool list, through **config sections** (ADR-0010).
+- A non-primary database is reached through a `database` argument on the tools that run SQL. dbhub registers `execute_sql_<source>` per source. Here a tool per database would add tool definitions to every turn and go stale when database.yml changes under a running server.
+
+## Consequences
+
+A user who needs write access, or a database the Rails app does not own, can run dbhub beside this gem. `rails_query` keeps its read-only guards and its secret column rule for the app's own databases either way.
+
+## Alternatives not taken
+
+- **dbhub as rails_query's backend**: it would add Node to a pure Ruby gem, connect by DSN where `rails_query` uses the app's own connection, and return secret columns unredacted. Each of those is a property `rails_query` documents.
+- **dbhub's two-tool default**: the answers here are computed (callback order, strong params lineage, filter chains). A bare search tool would hand that work back to the model.
+- **Tool annotations derived from an access policy**: there is no write mode here, so a constant read-only hint is correct.

data/docs/adr/0010-one-config-tool-with-sections.md

@@ -0,0 +1,32 @@
+# One config tool with sections
+
+Status: accepted
+
+Eleven tools each read one payload section and take no target: `rails_get_config`, `_autoload`, `_engines`, `_active_support`, `_conventions`, `_gems`, `_frontend_stack`, `_api`, `_env`, `_env_config` and `_i18n`. Every one costs a full definition in `tools/list` on every turn: together about 8,800 characters, or a fifth of what all 45 cost before this decision. A client reads that list whether or not the app's configuration is asked about.
+
+## Decision
+
+- `rails_get_config` takes a `section`: `app` (the default, and what the tool answered before: database, auth, assets, cache, queue, Action Cable, initializers, middleware), `gems`, `frontend`, `api`, `engines`, `conventions`, `autoload`, `active_support`, `env`, `env_config` and `i18n`. The other ten tools leave `tools/list`.
+- The old names keep working wherever a name is typed:
+  - the CLI resolves `gems`, `rails_get_gems`, `frontend_stack` and the rest to their section;
+  - the MCP server answers a call to a retired name from its section and says which call to make instead, with the arguments that section reads.
+- `skip_tools` naming one of the ten retired tools turns its section off, and `rails_get_config` turns off the `app` section. A skip that hid the process environment keeps hiding it after an upgrade, and a skip that hid the overview still hides only the overview. The tool leaves `tools/list` only when every section is off.
+- With `app` off there is no default, so `section` is required: the published schema and the description say so, and a call with none is answered with the sections that are on.
+- A custom tool named `rails_get_config` takes the built-in's place when `skip_tools` lists that name, as a custom tool takes any skipped built-in's. The ten sections go with the built-in, and a retired name is then an unknown tool.
+- A custom tool that reuses a retired name is served as its own tool. The gem's own hints still mean the built-in section.
+- Each section's parameters ride on the one tool (`detail`, `category`, `offset`, `limit`, `environment`, `locale`). A parameter the asked section does not read is named in the answer as ignored.
+- The ten classes stay in the gem as the sections' renderers. Ruby that calls `RailsAiContext::Tools::GetGems.call` keeps working; only the MCP surface changes.
+
+## Consequences
+
+The change ships in 5.35.1, with migration notes. That number was the maintainer's choice, made outside the rule in `docs/RELEASING.md` step 1, which rules out a patch number for a release with an Added entry or a Changed entry a consumer can observe. What makes it tenable is that every retired name still answers on the CLI and over MCP, with a line naming the new call, so a prompt or a script that names one keeps working.
+
+The removal shows wherever tool names are listed or reported. `tools/list` and `tool --list` hold 35 names. The CLI's `--json` output reports `rails_get_config` for a retired name. `Tools::BaseTool.registered_tools` no longer lists the ten classes. The session context records a section call under the new name.
+
+The section names are public interface from here on, like the tool names before them: renaming one keeps the old name as an alias.
+
+## Alternatives not taken
+
+- **Keeping the ten tools beside the new section argument**: the definitions are the cost being removed.
+- **A new tool name such as `rails_get_stack`**: `rails_get_config` already answered the default section, so its callers see no change.
+- **Splitting into two tools (stack and configuration)**: two definitions where one carries the same sections, and a line between the two that every reader would have to learn.

data/docs/index.md

@@ -4,7 +4,7 @@ title: Home
 
 # rails-ai-context Documentation
 
-**45 MCP tools that give AI agents live access to your Rails app.**
+**35 MCP tools that give AI agents live access to your Rails app.**
 
 Works with Claude Code, Cursor, GitHub Copilot, OpenCode, and Codex CLI.
 
@@ -23,7 +23,7 @@ Works with Claude Code, Cursor, GitHub Copilot, OpenCode, and Codex CLI.
 
 | Guide | Description |
 |:------|:------------|
-| **[Tools Reference](TOOLS.md)** | All 45 tools with every parameter |
+| **[Tools Reference](TOOLS.md)** | All 35 tools with every parameter |
 | **[Configuration](CONFIGURATION.md)** | 40+ config options with defaults |
 | **[CLI Reference](CLI.md)** | Commands and argument syntax |
 | **[Introspectors](INTROSPECTORS.md)** | All 40 introspectors and AST engine |

data/exe/rails-ai-context

@@ -92,10 +92,11 @@ TYPED_IN_ENV = "RAILS_AI_CONTEXT_TYPED_IN"
 # `context` either.
 MCP_REFRESH_FLAG_SINCE = "5.33.0"
 
-# After one of these tools' names `--environment` is its filter, never RAILS_ENV: this is
-# decided before boot, when no tool schema can load. cli_smoke_spec holds it to the schemas.
-ENVIRONMENT_PARAM_TOOLS = %w[env_config].freeze
+# The tool names and `config` sections whose `--environment` is their own filter and leaves RAILS_ENV alone.
+# Decided before boot, when no tool schema can load; cli_smoke_spec holds the list to the schemas.
+ENVIRONMENT_FILTER_OWNERS = %w[env_config].freeze
 
+require "rbconfig"
 require "shellwords"
 require "thor"
 
@@ -237,10 +238,20 @@ class RailsAiContextCLI < Thor
         return
       end
 
+      # Value-taking class options land in args too.
+      @app_path_override = extract_value_flag!(args, "--app-path")
+      # `--app-path --help` names no path: the flag took the help flag for its value.
+      if %w[--help -h].include?(@app_path_override)
+        @app_path_override = nil
+        args << "--help"
+      end
+
       if args.include?("--help") || args.include?("-h")
+        # The app's configuration file says which tools and sections it serves; reading it boots nothing.
+        root = app_root.resolve(cwd: Dir.pwd, app_path: @app_path_override || options[:app_path]).root
         entry_boot.require_gem_without_app!
-        tool_class = ::RailsAiContext::CLI::ToolRunner.new(name, []).tool_class
-        puts ::RailsAiContext::CLI::ToolRunner.tool_help(tool_class)
+        ::RailsAiContext::Configuration.auto_load!(root || Dir.pwd)
+        puts ::RailsAiContext::CLI::ToolRunner.new(name, []).help
         return
       end
 
@@ -252,11 +263,15 @@ class RailsAiContextCLI < Thor
       json_mode = true if args.delete("--json")
       json_mode = true if args.delete("-j")
 
-      # Value-taking class options land in args too. A tool that declares `environment`
-      # keeps it: booting in the env it filters for fails where the app has no database.
-      @app_path_override = extract_value_flag!(args, "--app-path")
+      # A tool that declares `environment` keeps it: booting in the env it filters for fails where the app has no database.
       environment_flag = extract_value_flag!(args, "--environment")
-      if environment_flag && ENVIRONMENT_PARAM_TOOLS.include?(name.to_s.delete_prefix("rails_").delete_prefix("get_"))
+      short = name.to_s.delete_prefix("rails_").delete_prefix("get_")
+      # Read here because the tool parses its own arguments after boot, and the section decides
+      # which env boots: the last one named, as the tool reads it.
+      section = args.each_with_index.filter_map do |arg, at|
+        arg == "--section" ? args[at + 1] : (arg.split("=", 2).last if arg.start_with?("--section=", "section="))
+      end.last
+      if environment_flag && (ENVIRONMENT_FILTER_OWNERS.include?(short) || (short == "config" && ENVIRONMENT_FILTER_OWNERS.include?(section.to_s.downcase)))
         args.push("--environment", environment_flag)
       else
         @environment_override = environment_flag

data/lib/generators/rails_ai_context/install/install_generator.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "fileutils"
+require "pathname"
 require "json"
 require "open3"
 require "shellwords"

data/lib/rails_ai_context/app_databases.rb

@@ -0,0 +1,377 @@
+# frozen_string_literal: true
+
+require "did_you_mean"
+
+module RailsAiContext
+  # Every database the app has, listed once per run: the primary, the rest of the running environment's,
+  # those only another environment configures, then dumps no environment claims. Both tiers list the same.
+  module AppDatabases
+    class Error < RailsAiContext::Error; end
+    class UnknownDatabase < Error; end
+    class NotHere < Error; end
+    class NotBooted < Error; end
+    class Missing < Error; end
+    class InMemory < Error; end
+
+    # reason: what stopped the connection. advice: what to do about it.
+    class Unreachable < Error
+      attr_reader :reason, :advice
+
+      def initialize(name, reason, advice)
+        @reason = reason
+        @advice = advice
+        super("The #{name} database cannot be reached: #{reason}. #{advice}")
+      end
+    end
+
+    class AdapterMissing < Unreachable; end
+
+    # The owner of a pool leased for another database. Rails names a pool by its owner.
+    class LeaseOwner
+      def self.primary_class?
+        false
+      end
+
+      def self.current_preventing_writes
+        false
+      end
+    end
+
+    # Seconds a leased MySQL connection waits for an answer past twice query_timeout.
+    READ_MARGIN = 5
+
+    Dump = Data.define(:format, :path)
+
+    # environments: every one that configures it, in file order.
+    Database = Data.define(:name, :environments, :here, :primary, :replica, :tasks, :adapter, :adapter_default,
+                           :family, :dump, :migrate_dirs, :config) do
+      # Its database.yml entry by string key, or {} for a database only a dump names.
+      def settings
+        AppDatabases.settings_of(config)
+      end
+
+      # Raises Unreachable, naming the database, when no connection to it answers.
+      def with_connection(&block)
+        with_pool do |pool|
+          AppDatabases.reaching(name, adapter) { pool.with_connection(&:verify!) }
+          pool.with_connection(&block)
+        end
+      end
+
+      # Raises unless this process can lease the database. Connects to nothing.
+      def reachable!
+        raise NotHere, not_here_message unless here
+        raise NotBooted, "The #{name} database needs the booted app to connect, and this is the static tier." if RailsAiContext.static_tier? || !config.respond_to?(:configuration_hash)
+
+        return AppDatabases.present!(name, ActiveRecord::Base.connection_db_config) if primary
+        # A lease would open a new, empty database beside the one the app's own process holds.
+        raise InMemory, in_memory_message if DatabaseFile.in_memory?(config)
+
+        AppDatabases.present!(name, config)
+      end
+
+      # The primary is the app's own pool. Any other database gets a handler of its own
+      # per lease, so the app's pools are never touched and no two leases share a pool.
+      def with_pool
+        reachable!
+        return yield(ActiveRecord::Base.connection_pool) if primary
+
+        handler = ActiveRecord::ConnectionAdapters::ConnectionHandler.new
+        begin
+          yield AppDatabases.reaching(name, adapter) { handler.establish_connection(connecting_in_time, owner_name: LeaseOwner) }
+        ensure
+          release(handler)
+        end
+      end
+
+      # { pending: [{ version:, name: }, ...] } read through the lease, or { error: exception }.
+      def pending_migrations(dirs = migrate_dirs)
+        with_connection { |connection| { pending: AppDatabases.bounded(connection) { MigrationStatus.pending_on(connection.pool, dirs) } } }
+      rescue ActiveRecord::NoDatabaseError => e
+        { error: Missing.new(e.message) }
+      rescue Unreachable => e
+        { error: e.cause.is_a?(ActiveRecord::NoDatabaseError) ? Missing.new(e.cause.message) : e }
+      rescue StandardError => e
+        { error: e }
+      end
+
+      private
+
+      # Rails 7.0 verifies each connection as it disconnects a pool, which reconnects to a server that
+      # stopped answering. Thrown away first, no connection is left to verify. Never replaces the block's error.
+      def release(handler)
+        handler.retrieve_connection_pool(LeaseOwner.name)&.connections&.each(&:throw_away!)
+        handler.remove_connection_pool(LeaseOwner.name)
+      rescue StandardError => e
+        RailsAiContext.debug_fail(e, nil, label: "AppDatabases release")
+      end
+
+      # A server that never answers would hold the lease for as long as its driver waits. Where the entry
+      # sets no limit of its own, connecting ends at query_timeout and a MySQL read above the statement's budget.
+      def connecting_in_time
+        return config if family.sqlite?
+
+        budget = RailsAiContext.configuration.query_timeout
+        limits = { connect_timeout: budget.ceil }
+        limits[:read_timeout] = (2 * budget).ceil + READ_MARGIN if family.mysql?
+        settings = config.configuration_hash
+        added = limits.reject { |key, _| settings[key] }
+        return config if added.empty?
+
+        ActiveRecord::DatabaseConfigurations::HashConfig.new(config.env_name, config.name, settings.merge(added))
+      end
+
+      def in_memory_message
+        "The #{name} database lives in memory, inside the process that created it. " \
+          "A connection from here would open a new, empty database, so it cannot be read."
+      end
+
+      def not_here_message
+        if environments.empty?
+          "The #{name} database is only a committed dump: no environment in config/database.yml configures it, so there is nothing to connect to."
+        else
+          "The #{name} database is configured in #{AppDatabases.environment_phrase(environments)}. " \
+            "This process runs in #{RailsAiContext.environment_name}, so it cannot be reached from here."
+        end
+      end
+    end
+
+    class List
+      include Enumerable
+
+      def initialize(databases)
+        @databases = databases.freeze
+      end
+
+      def each(&block)
+        @databases.each(&block)
+      end
+
+      def primary
+        find(&:primary)
+      end
+
+      # The databases past the primary that Rails dumps and migrates.
+      def secondaries
+        reject { |db| db.primary || db.replica || !db.tasks }
+      end
+
+      def here
+        select(&:here)
+      end
+
+      def names
+        map(&:name)
+      end
+
+      def [](name)
+        find { |db| db.name == name.to_s }
+      end
+
+      # The database a dump's name stands for. No name is the primary, and so is "primary" where no entry carries it.
+      def of_dump_name(name)
+        return primary if name.nil?
+
+        self[name] || (primary if name.to_s == "primary")
+      end
+
+      # nil or "" is the primary.
+      def fetch(name)
+        return primary if name.nil? || name.to_s.empty?
+
+        found = self[name]
+        return found if found
+
+        guess = ::DidYouMean::SpellChecker.new(dictionary: names).correct(name.to_s).first
+        raise UnknownDatabase, "No database named #{name}.#{" Did you mean #{guess}?" if guess} This app has: #{names.join(', ')}"
+      end
+
+      def find_by_dump(path)
+        find { |db| db.dump&.path == path.to_s }
+      end
+    end
+
+    DUMP_GLOBS = { ruby: "*_schema.rb", sql: "*_structure.sql" }.freeze
+    ADAPTER_GEMS = { "postgresql" => "the pg gem", "postgis" => "the activerecord-postgis-adapter gem", "mysql2" => "the mysql2 gem",
+                     "trilogy" => "the trilogy gem", "sqlite3" => "the sqlite3 gem" }.freeze
+
+    module_function
+
+    # "production", or "staging and production".
+    def environment_phrase(environments)
+      environments.to_sentence(words_connector: ", ", two_words_connector: " and ", last_word_connector: " and ")
+    end
+
+    # A connection to the named database for the block. No name is the app's own connection.
+    def lease(root, name, &block)
+      return self.for(root).fetch(name).with_connection(&block) unless name.to_s.empty?
+
+      own = ActiveRecord::Base.connection_db_config
+      present!(own.name, own)
+      reaching(own.name, own.adapter) { ActiveRecord::Base.connection.verify! }
+      yield ActiveRecord::Base.connection
+    end
+
+    # Runs the block that connects. What stops it is raised as Unreachable.
+    def reaching(name, adapter)
+      yield
+    rescue Error
+      raise
+    rescue StandardError, LoadError => e
+      raise unreachable(name, adapter, e)
+    end
+
+    # Names the database a connection did not reach, says what stopped it, and gives advice that fits.
+    def unreachable(name, adapter, error)
+      if error.is_a?(LoadError) || error.is_a?(ActiveRecord::AdapterNotFound)
+        gem = ADAPTER_GEMS.fetch(adapter.to_s) { "the gem that provides the #{adapter} adapter" }
+        return AdapterMissing.new(name, "its #{adapter} adapter did not load", "Add #{gem} to the Gemfile and run `bundle install`.")
+      end
+
+      advice = if DatabaseFamily.of(adapter).sqlite? then "Check the file its config/database.yml entry names."
+      elsif error.is_a?(ActiveRecord::NoDatabaseError) then "Run `bin/rails db:create` or `bin/rails db:prepare` to create it."
+      else "Start its server, or fix its settings in config/database.yml."
+      end
+      Unreachable.new(name, error.message.lines.first.to_s.strip.chomp("."), advice)
+    end
+
+    # A read that ends at query_timeout, so a locked table cannot hold the answer. A family with no limit runs it as it is.
+    def bounded(connection, &read)
+      family = DatabaseFamily.of(connection)
+      family.known? ? family.bounded(connection, timeout: RailsAiContext.configuration.query_timeout, &read) : read.call
+    end
+
+    # Connecting to a SQLite file that is not there would create it, so this raises first.
+    def present!(name, db_config)
+      return unless DatabaseFile.missing?(db_config)
+
+      raise Missing, "The #{name} database does not exist yet: its SQLite file #{db_config.database} is not there, " \
+        "and nothing was created. Run `bin/rails db:prepare` to create it."
+    end
+
+    def for(root)
+      root = root.to_s
+      environments = booted_environments(root)
+      tier = environments ? :booted : :static
+      RunCache.fetch([ :app_databases, root, tier ]) do
+        environments ||= static_environments(root)
+        build(environments: with_environment_file(root, environments), current: RailsAiContext.environment_name, root: root, dumps: dump_files(root),
+              primary: (connected_name if tier == :booted))
+      end
+    end
+
+    # environments: { env => { name => settings Hash or db_config } } in file order. dumps: [format, path] of each
+    # secondary-looking dump on disk. primary: the database ActiveRecord::Base is connected to, when the app is booted.
+    def build(environments:, current:, root:, dumps:, primary: nil)
+      own = environments[current] || {}
+      first = DatabaseYml.primary_name_in(own)
+      primary_name = own.key?(primary) ? primary : first
+      configured = ->(name) { environments.select { |_, found| found.key?(name) }.keys }
+      listed = own.map do |name, value|
+        database(root, name, value, here: true, primary: name == primary_name, first: name == first, environments: configured.call(name))
+      end
+      listed = listed.partition(&:primary).flatten
+
+      environments.each do |env_name, found|
+        next if env_name == current
+
+        other_primary = DatabaseYml.primary_name_in(found)
+        found.each do |name, value|
+          next if listed.any? { |db| db.name == name }
+
+          is_primary = listed.none?(&:primary) && name == other_primary
+          # Another environment's first database is its primary under another name, which this app already lists.
+          next if name == other_primary && !is_primary
+
+          listed << database(root, name, value, here: false, primary: is_primary, first: is_primary, environments: configured.call(name))
+        end
+      end
+
+      claimed = listed.filter_map { |db| db.dump&.path } + Introspectors::SchemaDumpPath.candidates(root).map(&:last)
+      dumps.each do |format, path|
+        next if claimed.include?(path)
+
+        name = File.basename(path).sub(/_(schema\.rb|structure\.sql)\z/, "")
+        next if listed.any? { |db| db.name == name }
+
+        listed << orphan(root, name, format, path)
+      end
+      List.new(listed)
+    end
+
+    # first: its environment's first entry, whose dump Rails names schema.rb.
+    def database(root, name, value, here:, primary:, first:, environments:)
+      settings = settings_of(value)
+      adapter, from_default = value.respond_to?(:adapter) ? [ value.adapter, false ] : DatabaseYml.adapter(name, settings)
+      replica = !!settings["replica"]
+      tasks = tasks?(settings)
+      dump = first ? primary_dump(root) : Introspectors::SchemaDumpPath.secondary(root, name, settings)
+      # Rails writes no dump for a database it runs no tasks on, so only a committed one counts.
+      dump = nil unless tasks || (dump && File.exist?(dump.last))
+      Database.new(name: name, environments: environments, here: here, primary: primary, replica: replica, tasks: tasks,
+                   adapter: adapter, adapter_default: from_default, family: DatabaseFamily.of(adapter),
+                   dump: (Dump.new(*dump) if dump),
+                   migrate_dirs: Introspectors::MigrationReplay.configured_dirs(root, settings) || [ File.join(root, "db", "migrate") ],
+                   config: value)
+    end
+
+    def orphan(root, name, format, path)
+      Database.new(name: name, environments: [], here: false, primary: false, replica: false, tasks: true,
+                   adapter: nil, adapter_default: false, family: DatabaseFamily.of(nil), dump: Dump.new(format, path),
+                   migrate_dirs: [ File.join(root, "db", "#{name}_migrate") ], config: nil)
+    end
+
+    # HashConfig#database_tasks?: a replica runs none, and neither does database_tasks: false or with no value.
+    def tasks?(settings)
+      !settings["replica"] && !!settings.fetch("database_tasks", true)
+    end
+
+    def settings_of(value)
+      value = value.configuration_hash if value.respond_to?(:configuration_hash)
+      value.is_a?(Hash) ? value.transform_keys(&:to_s) : {}
+    end
+
+    def primary_dump(root)
+      Introspectors::SchemaDumpPath.present(root) || Introspectors::SchemaDumpPath.candidates(root).first
+    end
+
+    def connected_name
+      ActiveRecord::Base.connection_db_config.name
+    rescue StandardError => e
+      RailsAiContext.debug_fail(e, nil, label: "connected_name")
+    end
+
+    # ActiveRecord's configurations describe the app booted at Rails.root; any other root is read from its file.
+    def booted_environments(root)
+      return nil if RailsAiContext.static_tier? || !defined?(ActiveRecord::Base) || !defined?(Rails.root) || Rails.root.to_s != root
+
+      configs = ActiveRecord::Base.configurations.configurations
+      return nil if configs.empty?
+
+      configs.each_with_object({}) { |config, found| (found[config.env_name] ||= {})[config.name] = config }
+    rescue StandardError => e
+      RailsAiContext.debug_fail(e, nil, label: "booted_environments")
+    end
+
+    # Rails builds the primary from DATABASE_URL when the file has no entry for the environment.
+    def static_environments(root)
+      environments = (DatabaseYml.file(root) || {}).transform_values { |config| DatabaseYml.databases_in(config) }.reject { |_, found| found.empty? }
+      current = RailsAiContext.environment_name
+      environments = environments.merge(current => { "primary" => {} }) if !environments.key?(current) && !ENV["DATABASE_URL"].to_s.empty?
+      environments
+    end
+
+    # An environment has a config/environments file. Any other key holds an anchor (`default: &default`).
+    def with_environment_file(root, environments)
+      files = Dir.glob(File.join(root, "config/environments/*.rb")).map { |path| File.basename(path, ".rb") }
+      return environments if files.empty?
+
+      current = RailsAiContext.environment_name
+      environments.select { |env_name, _| env_name == current || files.include?(env_name) }
+    end
+
+    def dump_files(root)
+      DUMP_GLOBS.flat_map { |format, glob| Dir.glob(File.join(root, "db", glob)).sort.map { |path| [ format, path ] } }
+    end
+  end
+end

data/lib/rails_ai_context/app_kind.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "yaml"
+
 module RailsAiContext
   # Detects app-level facts that change which introspection applies, from
   # artifacts that exist without booting (config files, Gemfile.lock).

data/lib/rails_ai_context/cli/app_root.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "rbconfig"
 require "shellwords"
 require_relative "entry_boot"
 require_relative "../safe_path"