rails-agent-kit 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a76627b569e56f98f6e73636bcad9c04907c5b78a8efecec7989a65111ee1045
-  data.tar.gz: e8330c54dec1898177123c346e237b6b0cc4265aeebc337208b8bdecc00d2d5e
+  metadata.gz: d9ca6b38fb66d82ec0da3f7b0db4177e7c6757155488948b7502519ba40cc7ff
+  data.tar.gz: 6d265f395ab75b55bc0568136d9b9aa507b4f2608fef99917ed9dd00d6350eb8
 SHA512:
-  metadata.gz: cfe28fdedbe2391c946c06ce4c0265bc735572b6f61de61546c52d577c346faa5d4bdddf2bd23c97551c1a9b917760e2b0cd5acef6e0a231f71d8205eaff1e39
-  data.tar.gz: 8d6978a64aa800220d23748be96bf1ba8ad219673b2d1e06311999df8f04a336270371fa1608bbf882ac5fc54dedcc6c9af794c79a99999fb98df80c0c5784d4
+  metadata.gz: ffee9ca2d65c332c37c099445da8da27628808a1d034f7632c72b15d3c9157735b87ddd48abdfe6698915bcb62cec76a790b168e4330945d74d9b7166d3d0051
+  data.tar.gz: 031ca8d4042bbd2df644fb6a8c84317e3d2a5d91e9cf9ad45ea805f89341c159d6453c1c9e29cbc26fa274278875a12206f31054595861cf144b488ac2a72100

data/CHANGELOG.md

@@ -7,6 +7,52 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-26
+
+rails-agent-kit 0.3.0 adds `rails_project_info`, one small call that tells your agent which stack the app uses,
+and makes `rails_schema` read real-world schemas: enums, constraints, composite keys, views and other schemas,
+with warnings instead of silent gaps. Both parsers are now tested against `rails new` apps on Rails 7.2, 8.0 and
+8.1 and the Mastodon and Forem schemas.
+
+### Upgrading
+
+No action needed. A few `rails_schema` answers change shape, which agents read without changes: virtual
+columns report their real `type` (with `virtual: true`) instead of `"virtual"`, tables dumped as `public.users`
+are named `users`, and check constraints are listed under `check_constraints` instead of as phantom columns.
+Run `rails-agent-kit install-skills` again to get the skill's "call `rails_project_info` first" step.
+
+### Added
+
+- **`rails_project_info`, the first call of a session.** One answer of about 1 KB says what kind of Rails app
+  this is: Rails, Ruby and `load_defaults` versions, `api_only`, database adapter and multi-DB layout, test
+  framework and test data, auth and authorization, jobs, cache and cable backends, frontend, serializers, lint
+  and deploy tools, mounted engines, notable gems and where tests, factories and policies live. It reads
+  `Gemfile.lock` and config files without booting the app, and unknown values are `null`. The server
+  instructions and the Rails 8 skill tell the agent to call it first. By @afurm. (#10)
+- **`rails_schema` reads the rest of a real schema.** Postgres enums (`create_enum`, with each `t.enum` column's
+  `enum_type` and `values`), check, exclusion and unique constraints, composite primary keys, `create_schema` and
+  tables in other schemas, expression indexes, scenic views (with indexes on materialized views) and SQLite
+  full-text search tables. Virtual columns report their real type with `virtual`, `as` and `stored`. By @afurm. (#9)
+- **Warnings instead of silent gaps.** A line inside `create_table` the parser doesn't understand, or a top-level
+  statement it skips (a trigger, an `execute`), is listed in `warnings` with its line number, in every
+  `rails_schema` answer. By @afurm. (#9)
+- **Engine routes say where they're mounted.** Routes listed under an engine in `bin/rails routes --expanded`
+  carry `engine` and `mounted_at`, since their paths are relative to the mount point. By @afurm. (#9)
+- **Tested against real apps.** A test corpus of `rails new` apps on Rails 7.2, 8.0 and 8.1 (SQLite and
+  PostgreSQL, with Devise, Sidekiq::Web, Active Storage and a mounted engine) plus the Mastodon and Forem schemas.
+  Table, column and route counts must match what the booted app and PostgreSQL report. By @afurm. (#9)
+
+### Fixed
+
+- **`t.check_constraint` is no longer read as a column** named after its expression, which added phantom columns
+  to tables with check constraints. By @afurm. (#9)
+- **Expression indexes are no longer dropped.** `t.index "lower(email)"` and `add_index` with an SQL expression
+  containing quotes were skipped; they're now listed with the expression. By @afurm. (#9)
+- **Tables dumped as `public.users`** (apps with several schemas on the search path) are reported as `users`,
+  so `table: "users"` finds them; enums get the same treatment. By @afurm. (#9)
+- **Statements that span several lines** (long `create_table` options, multi-line defaults) and heredocs are
+  parsed as one statement, and escaped characters in string defaults (`\n`, `\"`) are unescaped. By @afurm. (#9)
+
 ## [0.2.0] - 2026-10-23
 
 rails-agent-kit 0.2.0 keeps large schemas out of your agent's context and makes setup one command:
@@ -79,6 +125,7 @@ you can keep that config; `rails-agent-kit init` only adds what's missing.
 - `rails-agent-kit install-skills [--agent cursor|claude] [--force]`, which installs the bundled skills into an app.
 - CI on Ruby 3.2, 3.3 and 3.4.
 
-[Unreleased]: https://github.com/afurm/rails-agent-kit/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/afurm/rails-agent-kit/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/afurm/rails-agent-kit/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/afurm/rails-agent-kit/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/afurm/rails-agent-kit/releases/tag/v0.1.0

data/README.md

@@ -18,7 +18,7 @@ routes, plus a Rails 8 skill that tells the agent to check them before it writes
 </div>
 
 > [!NOTE]
-> rails-agent-kit is early (v0.2.0), and the API may change before 1.0. Using it? Tell us how it went in
+> rails-agent-kit is early (v0.3.0), and the API may change before 1.0. Using it? Tell us how it went in
 > [Discussions](https://github.com/afurm/rails-agent-kit/discussions) or [open an issue](https://github.com/afurm/rails-agent-kit/issues).
 
 ---
@@ -29,6 +29,8 @@ Agents writing Rails code guess all the time. *Is it `user.full_name` or `user.n
 the helper `post_comments_path` or `comments_path`?* Each wrong guess is broken code and another review round.
 rails-agent-kit lets the agent ask your app.
 
+* **Stack:** Rails and Ruby versions, database, test framework, auth, jobs, frontend and deploy tools in one
+  small answer, read from `Gemfile.lock` and config files, so the agent uses what the app already uses.
 * **Schema:** tables, columns, indexes and foreign keys from `db/schema.rb`, parsed statically. It never boots
   the app or connects to a database. `db/structure.sql` gets a best-effort parse.
 * **Schema overview and search:** a compact overview by default, several tables
@@ -219,14 +221,16 @@ rails-agent-kit install-skills --root /path/to/your/rails/app --agent gemini   #
 
 ## Tools
 
-Both tools are read-only and return JSON.
+All three tools are read-only and return JSON.
 
 | Tool | Parameters | Returns | Boots the app? |
 | --- | --- | --- | --- |
+| `rails_project_info` | None | Rails, Ruby and `load_defaults` versions, `api_only`, database adapter and databases, test framework and data, auth, authorization, jobs/cache/cable backends, frontend, serializers, lint and deploy tools, mounted engines, notable gems and key paths. Unknown values are `null` | **No.** Reads `Gemfile.lock` and config files |
 | `rails_schema` | All optional. `table`: one exact name, an array or a comma-separated list. `search`: case-insensitive part of a table or column name. `detail`: `overview` or `full` | With no arguments, a compact overview (each table's column count, non-default primary key and foreign key targets). With `table`, full columns (type, null, default, limit, …), indexes and foreign keys. With `search`, the matching tables and columns | **No.** Parses `db/schema.rb` statically, with a best-effort fallback to `db/structure.sql` |
 | `rails_routes` | `filter` (optional, case-insensitive substring of name, path, verb or `controller#action`) | Each route's name, verb, path, `controller#action` and source location | **Yes.** Runs `bin/rails routes --expanded`. If that fails or times out, it explains why and returns the raw `config/routes.rb` |
 
-Responses are compact (single-line) JSON. Agents usually call `rails_schema` with no arguments first, so that
+Responses are compact (single-line) JSON. Agents call `rails_project_info` first (about 1 KB), then usually
+`rails_schema` with no arguments, so that
 answer stays small even on large apps: a generated 300-table schema gives about 23 KB, where the full dump is
 over 1 MB. Any `rails_schema` answer over 60 KB comes back as the overview plus a note on how to narrow the
 request (`truncated: true`).
@@ -269,8 +273,8 @@ rails-agent-kit --root . --routes-file tmp/routes.txt
 
 ## Agent skill: Rails 8 conventions
 
-[`skills/rails-8-conventions/SKILL.md`](skills/rails-8-conventions/SKILL.md) makes the agent check `rails_schema`,
-`rails_routes` and `Gemfile.lock` before it edits code. It then follows the Rails 8 defaults: `params.expect`, the
+[`skills/rails-8-conventions/SKILL.md`](skills/rails-8-conventions/SKILL.md) makes the agent check `rails_project_info`,
+`rails_schema` and `rails_routes` before it edits code. It then follows the Rails 8 defaults: `params.expect`, the
 built-in authentication generator, `rate_limit`, Solid Queue/Cache/Cable, Hotwire with importmap/Propshaft,
 reversible migrations, and tests in the framework the app already uses. It also covers a paired Next.js
 frontend.

data/lib/rails_agent_kit/project_info.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "erb"
+require "yaml"
+
+module RailsAgentKit
+  # Answers "what kind of Rails app is this?" from Gemfile.lock, config files and the directory layout, without
+  # booting the app. Every value comes from a file in the app; anything that can't be read from one is nil.
+  class ProjectInfo
+    # [field, gem or detector => reported name]. The first matching entries win, in this order.
+    CHOICES = {
+      js: { "importmap-rails" => "importmap", "jsbundling-rails" => "jsbundling", "vite_rails" => "vite",
+            "vite_ruby" => "vite", "shakapacker" => "shakapacker", "webpacker" => "webpacker" },
+      assets: { "propshaft" => "propshaft", "sprockets-rails" => "sprockets", "sprockets" => "sprockets" },
+      css: { "tailwindcss-rails" => "tailwind", "cssbundling-rails" => "cssbundling", "dartsass-rails" => "sass",
+             "sassc-rails" => "sass", "bootstrap" => "bootstrap" },
+      views: { "view_component" => "view_component", "phlex-rails" => "phlex" },
+      serializers: { "jbuilder" => "jbuilder", "alba" => "alba", "blueprinter" => "blueprinter",
+                     "active_model_serializers" => "active_model_serializers",
+                     "jsonapi-serializer" => "jsonapi-serializer", "oj_serializers" => "oj_serializers" },
+      authorization: { "pundit" => "pundit", "cancancan" => "cancancan", "action_policy" => "action_policy" },
+      auth_gems: { "devise" => "devise", "rodauth-rails" => "rodauth", "sorcery" => "sorcery",
+                   "clearance" => "clearance" },
+      job_gems: { "solid_queue" => "solid_queue", "sidekiq" => "sidekiq", "good_job" => "good_job",
+                  "resque" => "resque", "delayed_job_active_record" => "delayed_job" },
+      factories: { "factory_bot_rails" => "factory_bot", "factory_bot" => "factory_bot", "fabrication" => "fabrication" }
+    }.freeze
+    HOTWIRE = { "turbo-rails" => "turbo", "stimulus-rails" => "stimulus" }.freeze
+    QUALITY = %w[rubocop-rails-omakase standard rubocop rubocop-rails brakeman bundler-audit erb_lint herb].freeze
+    NOTABLE = %w[
+      pagy kaminari will_paginate ransack pg_search searchkick paper_trail audited logidze friendly_id aasm
+      money-rails noticed flipper rack-attack strong_migrations annotaterb annotate image_processing aws-sdk-s3
+      stripe pay mission_control-jobs activeadmin administrate avo rolify discard paranoia acts_as_list ancestry
+      store_model sentry-ruby honeybadger rollbar appsignal skylight lograge solid_errors
+    ].freeze
+    PATHS = {
+      tests: %w[spec test], factories: %w[spec/factories test/factories], fixtures: %w[spec/fixtures test/fixtures],
+      policies: %w[app/policies], components: %w[app/components app/views/components],
+      serializers: %w[app/serializers app/blueprints app/resources], services: %w[app/services],
+      graphql: %w[app/graphql], javascript: %w[app/javascript]
+    }.freeze
+
+    def initialize(root)
+      @root = File.expand_path(root)
+      @sources = []
+    end
+
+    def call
+      unless file?("Gemfile") || file?("config/application.rb")
+        return { error: "No Gemfile or config/application.rb in #{@root}, so this doesn't look like a Rails app." }
+      end
+
+      @specs, @deps = read_lockfile
+      info = {
+        rails: @specs["rails"] || @specs["railties"],
+        ruby: ruby,
+        load_defaults: application_rb&.[](/^\s*config\.load_defaults\s+["']?([\d.]+)/, 1),
+        api_only: application_rb ? application_rb.match?(/^\s*config\.api_only\s*=\s*true/) : nil,
+        database: database,
+        test: test_stack,
+        auth: auth,
+        authorization: pick(:authorization),
+        jobs: jobs,
+        cache: cache,
+        cable: cable,
+        frontend: frontend,
+        serializers: pick(:serializers),
+        graphql: gem?("graphql"),
+        quality: presence(QUALITY.select { |g| gem?(g) }),
+        deploy: deploy,
+        engines: engines,
+        gems: presence(NOTABLE.select { |g| gem?(g) }.to_h { |g| [g, @specs[g]] }),
+        paths: presence(paths)
+      }
+      info[:sources] = @sources.uniq
+      info
+    end
+
+    private
+
+    # Gemfile.lock specs (name => version) and direct dependencies. Without a lockfile, the Gemfile's gem lines.
+    def read_lockfile
+      text = read("Gemfile.lock")
+      if text.nil?
+        gemfile = read("Gemfile").to_s
+        names = gemfile.scan(/^\s*gem\s+["']([^"']+)["']/).flatten
+        return [names.to_h { |n| [n, nil] }, names]
+      end
+
+      specs = {}
+      deps = []
+      section = nil
+      text.each_line do |line|
+        section = line.strip if line.match?(/\A[A-Z]/)
+        if section == "GEM" && (m = line.match(/\A {4}([^\s(]+) \(([^)]+)\)\s*\z/))
+          specs[m[1]] ||= m[2].sub(/-(?:x86|arm|aarch|universal|java|x64|mingw).*\z/, "")
+        elsif section == "DEPENDENCIES" && (m = line.match(/\A {2}([^\s(!]+)/))
+          deps << m[1]
+        end
+      end
+      [specs, deps]
+    end
+
+    def gem?(name)
+      @deps.include?(name) || (@deps.empty? && @specs.key?(name))
+    end
+
+    def pick(field, choices = CHOICES.fetch(field))
+      found = choices.select { |gem, _| gem?(gem) }.values.uniq
+      found.size > 1 ? found : found.first
+    end
+
+    def ruby
+      env = RubyEnv.new(@root)
+      required, source = env.requirement
+      if required.nil? && (lock = read("Gemfile.lock")) && (m = lock.match(/^RUBY VERSION\n\s+ruby ([\d.]+)/))
+        required = m[1]
+        source = "Gemfile.lock"
+      end
+      return nil if required.nil?
+
+      @sources << source
+      { version: required, source: source }
+    end
+
+    def application_rb
+      return @application_rb if defined?(@application_rb)
+
+      @application_rb = read("config/application.rb")
+    end
+
+    def production_rb
+      return @production_rb if defined?(@production_rb)
+
+      @production_rb = read("config/environments/production.rb")
+    end
+
+    def database
+      config = yaml("config/database.yml")
+      return nil unless config.is_a?(Hash)
+
+      adapters = []
+      multi = {}
+      config.each do |env, value|
+        next unless value.is_a?(Hash) && env != "default"
+
+        if value.key?("adapter") || value.key?("database") || value.key?("url")
+          adapters << value["adapter"]
+        else
+          dbs = value.select { |_, db| db.is_a?(Hash) }
+          adapters.concat(dbs.values.map { |db| db["adapter"] })
+          multi[env] = dbs.keys if dbs.size > 1
+        end
+      end
+      adapters = adapters.compact.uniq
+      { adapter: adapters.size > 1 ? adapters : adapters.first, databases: presence(multi) }.compact
+    end
+
+    def test_stack
+      framework = if file?("spec/rails_helper.rb") || file?("spec/spec_helper.rb") then "rspec"
+                  elsif file?("test/test_helper.rb") then "minitest"
+                  elsif gem?("rspec-rails") then "rspec"
+                  end
+      data = pick(:factories)
+      data ||= "fixtures" if Dir.glob(File.join(@root, "{test,spec}/fixtures/**/*.yml")).any?
+      system = gem?("capybara") ? "capybara" : nil
+      system ||= "cuprite" if gem?("cuprite")
+      { framework: framework, data: data, system: system }
+    end
+
+    def auth
+      found = []
+      if file?("app/controllers/concerns/authentication.rb") && file?("app/models/session.rb")
+        found << "rails_authentication"
+      end
+      found.concat(CHOICES[:auth_gems].select { |gem, _| gem?(gem) }.values)
+      found.size > 1 ? found : found.first
+    end
+
+    def jobs
+      configured = [production_rb, application_rb].compact.filter_map do |text|
+        text[/^\s*config\.active_job\.queue_adapter\s*=\s*:(\w+)/, 1]
+      end.first
+      configured || pick(:job_gems)
+    end
+
+    def cache
+      production_rb&.[](/^\s*config\.cache_store\s*=\s*:(\w+?)(?:_store)?\b/, 1)
+    end
+
+    def cable
+      config = yaml("config/cable.yml")
+      config.is_a?(Hash) && config["production"].is_a?(Hash) ? config["production"]["adapter"] : nil
+    end
+
+    def frontend
+      return nil if application_rb&.match?(/^\s*config\.api_only\s*=\s*true/) && pick(:js).nil?
+
+      hotwire = HOTWIRE.select { |gem, _| gem?(gem) }.values
+      @sources << "config/importmap.rb" if file?("config/importmap.rb")
+      { js: pick(:js), assets: pick(:assets), hotwire: presence(hotwire), css: pick(:css), views: pick(:views) }
+    end
+
+    def deploy
+      found = []
+      found << "kamal" if file?("config/deploy.yml") || gem?("kamal")
+      found << "docker" if file?("Dockerfile")
+      found << "procfile" if file?("Procfile")
+      found << "fly" if file?("fly.toml")
+      found << "render" if file?("render.yaml")
+      found << "heroku" if file?("app.json")
+      presence(found)
+    end
+
+    # `mount Engine => "/path"` and `mount Engine, at: "/path"` lines in config/routes.rb.
+    def engines
+      routes = read("config/routes.rb")
+      return nil if routes.nil?
+
+      mounts = routes.scan(/^\s*mount\s+([A-Z][\w:]*(?:\.\w+)?)\s*(?:=>|,\s*at:)\s*["']([^"']+)["']/)
+      presence(mounts.map { |engine, at| { engine: engine, at: at } })
+    end
+
+    def paths
+      PATHS.filter_map do |key, candidates|
+        dir = candidates.find { |path| File.directory?(File.join(@root, path)) }
+        [key, dir] if dir
+      end.to_h
+    end
+
+    def yaml(path)
+      text = read(path)
+      return nil if text.nil?
+
+      YAML.safe_load(text.gsub(/<%.*?%>/m, "erb"), aliases: true)
+    rescue Psych::Exception
+      nil
+    end
+
+    def file?(path)
+      File.file?(File.join(@root, path))
+    end
+
+    def read(path)
+      full = File.join(@root, path)
+      return nil unless File.file?(full)
+
+      @sources << path
+      File.read(full)
+    end
+
+    def presence(value)
+      value.nil? || value.empty? ? nil : value
+    end
+  end
+end

data/lib/rails_agent_kit/routes_parser.rb

@@ -3,8 +3,13 @@
 module RailsAgentKit
   # Parses the output of `bin/rails routes --expanded` (preferred) or the
   # default table output of `bin/rails routes`.
+  #
+  # Routes of a mounted engine are listed after a `[ Routes for Blorgh::Engine ]` (expanded) or
+  # `Routes for Blorgh::Engine:` (table) line and get `engine` and, when the mount is found, `mounted_at`,
+  # because their paths are relative to where the engine is mounted.
   class RoutesParser
     HEADER = /\A--\[\s*Route\s+\d+\s*\]-*\s*\z/
+    SECTION = /\A\[?\s*Routes for (\S+?)\s*(?:\]|:)\s*\z/
     FIELD  = /\A([^|]+?)\s*\|\s?(.*)\z/
     KEYS = {
       "Prefix" => :name,
@@ -38,7 +43,12 @@ module RailsAgentKit
       verb_at = header.index("Verb")
       uri_at = header.index("URI Pattern")
       action_at = header.index("Controller#Action")
-      lines.drop(lines.index(header) + 1).filter_map do |line|
+      engine = nil
+      routes = lines.drop(lines.index(header) + 1).filter_map do |line|
+        if (m = SECTION.match(line.strip))
+          engine = m[1] == "application" ? nil : m[1]
+          next
+        end
         next if line.strip.empty? || line.length <= uri_at
 
         # Long values can push later columns right, so split the tail on whitespace.
@@ -47,18 +57,26 @@ module RailsAgentKit
         path, action = line[uri_at..].strip.split(/\s+/, 2)
         next if path.nil? || !path.start_with?("/")
 
-        normalize({ name: name.empty? ? nil : name, verb: verb, path: path, action: action&.strip })
+        route = { name: name.empty? ? nil : name, verb: verb, path: path, action: action&.strip }
+        route[:engine] = engine if engine
+        normalize(route)
       end
+      add_mount_points(routes)
     end
 
     def parse_expanded
       routes = []
       current = nil
+      engine = nil
       @output.each_line do |raw|
         line = raw.chomp
-        if HEADER.match?(line.strip)
+        if (m = SECTION.match(line.strip))
+          routes << current if current
+          current = nil
+          engine = m[1] == "application" ? nil : m[1]
+        elsif HEADER.match?(line.strip)
           routes << current if current
-          current = {}
+          current = engine ? { engine: engine } : {}
         elsif current && (m = FIELD.match(line))
           key = KEYS[m[1].strip] || m[1].strip.downcase.gsub(/\W+/, "_").to_sym
           value = m[2].strip
@@ -66,7 +84,15 @@ module RailsAgentKit
         end
       end
       routes << current if current
-      routes.map { |r| normalize(r) }
+      add_mount_points(routes.map { |r| normalize(r) })
+    end
+
+    # The app route that mounts an engine has the engine's class name as its action, e.g. `Blorgh::Engine`.
+    def add_mount_points(routes)
+      mounts = routes.each_with_object({}) do |r, h|
+        h[r[:action]] ||= r[:path] if !r[:engine] && r[:action]&.end_with?("::Engine")
+      end
+      routes.each { |r| r[:mounted_at] = mounts[r[:engine]] if r[:engine] && mounts[r[:engine]] }
     end
 
     def normalize(route)

data/lib/rails_agent_kit/ruby_env.rb

@@ -56,6 +56,11 @@ module RailsAgentKit
       end
     end
 
+    # The version the app asks for and the file that says so (relative to the app root), or nil.
+    def requirement
+      required_version
+    end
+
     # A one-line explanation for a Result that wasn't found.
     def self.missing_message(result)
       hint = format(INSTALL_HINTS.fetch(result.manager || "rbenv"), result.required_version.sub(/\A[~><=\s]+/, ""))

data/lib/rails_agent_kit/schema_inspector.rb

@@ -106,7 +106,10 @@ module RailsAgentKit
         entry[:references] = refs if refs.any?
         entry
       end
-      meta(result).merge(detail: "overview", table_count: tables.size, hint: OVERVIEW_HINT, tables: tables)
+      out = meta(result).merge(detail: "overview", table_count: tables.size, hint: OVERVIEW_HINT, tables: tables)
+      out[:enums] = result[:enums] if result[:enums]
+      out[:views] = result[:views].map { |v| v[:name] } if result[:views]
+      out
     end
 
     def search_result(result, search)
@@ -131,8 +134,9 @@ module RailsAgentKit
       guard_size(out, result)
     end
 
+    # Parser warnings travel with every answer: they mark statements that are missing from the result.
     def meta(result)
-      result.slice(:source, :version, :note)
+      result.slice(:source, :version, :note, :warnings)
     end
 
     def guard_size(out, result)

data/lib/rails_agent_kit/schema_parser.rb

@@ -1,22 +1,45 @@
 # frozen_string_literal: true
 
 module RailsAgentKit
-  # Parses db/schema.rb statically (no eval, no app boot) into tables, columns,
-  # indexes and foreign keys.
+  # Parses db/schema.rb statically (no eval, no app boot) into tables, columns, indexes, constraints,
+  # foreign keys, enums and views.
+  #
+  # The parser works on statements rather than raw lines: a statement that spans several lines (open
+  # brackets, a trailing comma, a method chain or a heredoc) is joined first. It never drops anything
+  # silently: a line inside `create_table` or a top-level statement it doesn't understand is reported in
+  # `warnings` with its line number, so callers know the result may be incomplete.
   class SchemaParser
-    Result = Struct.new(:version, :extensions, :tables, :foreign_keys, keyword_init: true) do
+    Result = Struct.new(:version, :extensions, :schemas, :enums, :tables, :foreign_keys, :views, :warnings,
+                        keyword_init: true) do
       def to_h
-        { version: version, extensions: extensions, tables: tables, foreign_keys: foreign_keys }
+        out = { version: version, extensions: extensions }
+        out[:schemas] = schemas if schemas.any?
+        out[:enums] = enums if enums.any?
+        out[:tables] = tables
+        out[:foreign_keys] = foreign_keys
+        out[:views] = views if views.any?
+        out[:warnings] = warnings if warnings.any?
+        out
       end
     end
 
-    CREATE_TABLE = /\A\s*create_table\s+["']([^"']+)["'](?:\s*,\s*(.*?))?\s+do\s*\|(\w+)\|\s*\z/
-    COLUMN       = /\A\s*(\w+)\.(\w+)\s+["']([^"']+)["']\s*(?:,\s*(.*))?\z/
-    T_INDEX      = /\A\s*(\w+)\.index\s+(\[[^\]]*\]|["'][^"']*["'])\s*(?:,\s*(.*))?\z/
-    ADD_INDEX    = /\A\s*add_index\s+["']([^"']+)["']\s*,\s*(\[[^\]]*\]|["'][^"']*["'])\s*(?:,\s*(.*))?\z/
-    ADD_FK       = /\A\s*add_foreign_key\s+["']([^"']+)["']\s*,\s*["']([^"']+)["']\s*(?:,\s*(.*))?\z/
-    EXTENSION    = /\A\s*enable_extension\s+["']([^"']+)["']/
-    VERSION_RE   = /define\(\s*version:\s*([\d_]+)\s*\)/
+    Statement = Struct.new(:text, :line, :heredoc, keyword_init: true)
+
+    CREATE_TABLE  = /\Acreate_table\s+["']([^"']+)["'](?:\s*,\s*(.*?))?\s+do\s*\|(\w+)\|\z/m
+    COLUMN        = /\A(\w+)\.(\w+)\s+["']([^"']+)["']\s*(?:,\s*(.*))?\z/m
+    T_INDEX       = /\A(\w+)\.index\s+(.*)\z/m
+    T_CONSTRAINT  = /\A(\w+)\.(check|exclusion|unique)_constraint\s+(.*)\z/m
+    ADD_INDEX     = /\Aadd_index\s+["']([^"']+)["']\s*,\s*(.*)\z/m
+    ADD_FK        = /\Aadd_foreign_key\s+["']([^"']+)["']\s*,\s*["']([^"']+)["']\s*(?:,\s*(.*))?\z/m
+    ADD_CHECK     = /\Aadd_check_constraint\s+["']([^"']+)["']\s*,\s*(.*)\z/m
+    EXTENSION     = /\Aenable_extension\s+["']([^"']+)["']/
+    CREATE_SCHEMA = /\Acreate_schema\s+["']([^"']+)["']/
+    CREATE_ENUM   = /\Acreate_enum\s+["']([^"']+)["']\s*,\s*(\[.*\])/m
+    CREATE_VIEW   = /\Acreate_view\s+["']([^"']+)["'](?:\s*,\s*(.*))?\z/m
+    VIRTUAL_TABLE = /\Acreate_virtual_table\s+["']([^"']+)["']\s*,\s*["']([^"']+)["']\s*,\s*(\[.*\])/m
+    VERSION_RE    = /define\(\s*version:\s*([\d_]+)\s*\)/
+    DEFINE        = /\AActiveRecord::Schema(?:\[[\d.]+\])?\.define\b/
+    HEREDOC       = /<<([~-]?)(["'`]?)([A-Za-z_]\w*)\2/
 
     def self.parse_file(path)
       new(File.read(path)).parse
@@ -27,86 +50,191 @@ module RailsAgentKit
     end
 
     def parse
-      tables = []
-      foreign_keys = []
-      extensions = []
-      version = @source[VERSION_RE, 1]&.delete("_")
-      current = nil
-      block_var = nil
-
-      @source.each_line do |raw|
-        line = strip_comment(raw).rstrip
-        next if line.strip.empty?
-
-        if current
-          if line.strip == "end"
-            tables << current
-            current = nil
-          elsif (m = T_INDEX.match(line)) && m[1] == block_var
-            current[:indexes] << build_index(current[:name], m[2], m[3])
-          elsif (m = COLUMN.match(line)) && m[1] == block_var
-            current[:columns] << build_column(m[2], m[3], m[4])
-          end
-          next
-        end
+      @tables = []
+      @foreign_keys = []
+      @extensions = []
+      @schemas = []
+      @enums = {}
+      @views = []
+      @warnings = []
+      @table = nil
+      @block_var = nil
+      @depth = 0 # open `do` blocks outside create_table (other than the define block)
 
-        if (m = CREATE_TABLE.match(line))
-          opts = parse_options(m[2])
-          block_var = m[3]
-          current = { name: m[1], primary_key: primary_key_for(opts), columns: [], indexes: [] }
-          current[:comment] = opts[:comment] if opts[:comment]
-          if current[:primary_key]
-            current[:columns] << { name: current[:primary_key], type: id_type(opts), null: false, primary_key: true }
-          end
-        elsif (m = ADD_INDEX.match(line))
-          index = build_index(m[1], m[2], m[3])
-          table = tables.find { |t| t[:name] == m[1] }
-          table ? table[:indexes] << index : nil
-        elsif (m = ADD_FK.match(line))
-          opts = parse_options(m[3])
-          fk = { from_table: m[1], to_table: m[2] }
-          fk[:column] = opts[:column] || "#{singularize(m[2])}_id"
-          fk[:primary_key] = opts[:primary_key] if opts[:primary_key]
-          fk[:on_delete] = opts[:on_delete] if opts[:on_delete]
-          fk[:on_update] = opts[:on_update] if opts[:on_update]
-          fk[:name] = opts[:name] if opts[:name]
-          foreign_keys << fk
-        elsif (m = EXTENSION.match(line))
-          extensions << m[1]
-        end
-      end
+      statements.each { |st| @table ? table_statement(st) : top_level_statement(st) }
+      finish_table(@table) if @table
 
-      Result.new(version: version, extensions: extensions, tables: tables, foreign_keys: foreign_keys)
+      enums = @enums.map { |name, values| { name: name, values: values } }
+      Result.new(version: @source[VERSION_RE, 1]&.delete("_"), extensions: @extensions, schemas: @schemas,
+                 enums: enums, tables: @tables, foreign_keys: @foreign_keys, views: @views, warnings: @warnings)
     end
 
     private
 
+    # --- statements -----------------------------------------------------------------------------------
+
+    def table_statement(st)
+      text = st.text
+      if text == "end"
+        finish_table(@table)
+        @table = nil
+      elsif (m = T_INDEX.match(text)) && m[1] == @block_var
+        @table[:indexes] << build_index(@table[:name], m[2])
+      elsif (m = T_CONSTRAINT.match(text)) && m[1] == @block_var
+        add_constraint(@table, m[2], m[3])
+      elsif (m = COLUMN.match(text)) && m[1] == @block_var
+        @table[:columns] << build_column(m[2], m[3], m[4])
+      else
+        warn(st, "not understood inside create_table #{@table[:name].inspect}, so it is missing from the result")
+      end
+    end
+
+    def top_level_statement(st)
+      text = st.text
+      case text
+      when CREATE_TABLE then start_table(Regexp.last_match)
+      when ADD_INDEX then add_index(Regexp.last_match, st)
+      when ADD_FK then add_foreign_key(Regexp.last_match)
+      when ADD_CHECK then add_check_constraint(Regexp.last_match, st)
+      when EXTENSION then @extensions << Regexp.last_match(1)
+      when CREATE_SCHEMA then @schemas << Regexp.last_match(1)
+      when CREATE_ENUM then @enums[table_name(Regexp.last_match(1))] = Array(parse_value(Regexp.last_match(2))).map(&:to_s)
+      when CREATE_VIEW then add_view(Regexp.last_match)
+      when VIRTUAL_TABLE then add_virtual_table(Regexp.last_match)
+      when DEFINE then nil
+      when "end" then @depth -= 1 if @depth.positive?
+      else
+        # A statement with its own block (e.g. hair_trigger's create_trigger ... do) ends with its own `end`.
+        @depth += 1 if text.match?(/\bdo(\s*\|[^|]*\|)?\z/)
+        warn(st, "skipped: only tables, indexes, constraints, foreign keys, enums and views are read")
+      end
+    end
+
+    def start_table(match)
+      opts = parse_options(match[2])
+      @block_var = match[3]
+      @table = { name: table_name(match[1]), primary_key: primary_key_for(opts), columns: [], indexes: [] }
+      @table[:comment] = opts[:comment] if opts[:comment]
+      return unless @table[:primary_key].is_a?(String)
+
+      @table[:columns] << { name: @table[:primary_key], type: id_type(opts), null: false, primary_key: true }
+    end
+
+    def finish_table(table)
+      if table[:primary_key].is_a?(Array)
+        table[:columns].each { |c| c[:primary_key] = true if table[:primary_key].include?(c[:name]) }
+      end
+      table[:columns].each do |c|
+        c[:values] = @enums[c[:enum_type]] if c[:enum_type] && @enums.key?(c[:enum_type]) && !c.key?(:values)
+      end
+      @tables << table
+    end
+
+    # Indexes can also belong to a materialized view (scenic's `create_view ..., materialized: true`).
+    def add_index(match, st)
+      name = table_name(match[1])
+      index = build_index(name, match[2])
+      target = find_table(name) || @views.find { |v| v[:name] == name }
+      return warn(st, "index on unknown table #{match[1].inspect}") unless target
+
+      (target[:indexes] ||= []) << index
+    end
+
+    def add_foreign_key(match)
+      opts = parse_options(match[3])
+      fk = { from_table: table_name(match[1]), to_table: table_name(match[2]) }
+      fk[:column] = opts[:column] || "#{singularize(match[2].split('.').last)}_id"
+      %i[primary_key on_delete on_update name].each { |k| fk[k] = opts[k] if opts[k] }
+      fk[:deferrable] = opts[:deferrable] if opts.key?(:deferrable)
+      @foreign_keys << fk
+    end
+
+    def add_check_constraint(match, st)
+      table = find_table(table_name(match[1]))
+      return warn(st, "check constraint on unknown table #{match[1].inspect}") unless table
+
+      add_constraint(table, "check", match[2])
+    end
+
+    def add_constraint(table, kind, src)
+      args = split_top_level(src)
+      constraint = { expression: parse_value(args.shift.to_s) }
+      constraint.merge!(parse_options(args.join(", ")).slice(:name, :using, :where, :deferrable, :nulls_not_distinct))
+      constraint[:columns] = Array(constraint.delete(:expression)) if kind == "unique" && src.start_with?("[")
+      (table[:"#{kind}_constraints"] ||= []) << constraint
+    end
+
+    def add_view(match)
+      opts = parse_options(match[2])
+      view = { name: table_name(match[1]) }
+      view[:materialized] = true if opts[:materialized] == true
+      @views << view
+    end
+
+    # SQLite full-text search tables (Rails 8 `create_virtual_table "posts_search", "fts5", ["title"]`).
+    def add_virtual_table(match)
+      columns = Array(parse_value(match[3])).map { |name| { name: name.to_s, type: "text", null: true } }
+      @tables << { name: match[1], primary_key: nil, virtual: match[2], columns: columns, indexes: [] }
+    end
+
+    # With several schemas on the search path Rails dumps every table and enum qualified ("public.users").
+    # Names in the default `public` schema are reported plain; other schemas keep the prefix.
+    def table_name(name)
+      name.delete_prefix("public.")
+    end
+
+    def find_table(name)
+      @tables.find { |t| t[:name] == name } || (@table if @table && @table[:name] == name)
+    end
+
+    def warn(st, message)
+      @warnings << { line: st.line, statement: abbreviate(st.text), message: message }
+    end
+
+    def abbreviate(text)
+      one_line = text.gsub(/\s+/, " ")
+      one_line.length > 120 ? "#{one_line[0, 117]}..." : one_line
+    end
+
+    # --- building ---------------------------------------------------------------------------------------
+
     def build_column(type, name, opts_src)
       opts = parse_options(opts_src)
-      col = { name: name, type: type, null: opts.key?(:null) ? opts[:null] : true }
-      %i[default limit precision scale array comment].each { |k| col[k] = opts[k] if opts.key?(k) }
+      if type == "virtual"
+        col = { name: name, type: opts[:type]&.to_s || "virtual", null: opts.key?(:null) ? opts[:null] : true }
+        col[:virtual] = true
+        col[:as] = opts[:as] if opts.key?(:as)
+        col[:stored] = opts[:stored] if opts.key?(:stored)
+      else
+        col = { name: name, type: type, null: opts.key?(:null) ? opts[:null] : true }
+      end
+      %i[default limit precision scale array comment enum_type collation].each { |k| col[k] = opts[k] if opts.key?(k) }
+      col[:enum_type] = table_name(col[:enum_type].to_s) if col[:enum_type]
       col
     end
 
-    def build_index(table, cols_src, opts_src)
-      opts = parse_options(opts_src)
-      columns = parse_value(cols_src)
+    # `src` is the column list (an array, one name, or an SQL expression string) followed by options.
+    def build_index(table, src)
+      args = split_top_level(src)
+      columns = parse_value(args.shift.to_s)
+      opts = parse_options(args.join(", "))
       index = { table: table, name: opts[:name], columns: Array(columns), unique: opts[:unique] == true }
-      %i[where using order].each { |k| index[k] = opts[k] if opts.key?(k) }
+      %i[where using order opclass include nulls_not_distinct].each { |k| index[k] = opts[k] if opts.key?(k) }
       index
     end
 
     def primary_key_for(opts)
       return nil if opts[:id] == false
-      return nil if opts[:primary_key].is_a?(Array)
+      return opts[:primary_key].map(&:to_s) if opts[:primary_key].is_a?(Array)
 
       opts[:primary_key] || "id"
     end
 
     def id_type(opts)
-      case opts[:id]
+      case (id = opts[:id])
       when nil, true then "bigint"
-      else opts[:id].to_s
+      when /\A\{(.*)\}\z/m then parse_options(Regexp.last_match(1))[:type]&.to_s || "bigint"
+      else id.to_s
       end
     end
 
@@ -118,12 +246,84 @@ module RailsAgentKit
       end
     end
 
+    # --- lexing -----------------------------------------------------------------------------------------
+
+    # Splits the source into statements: comments removed, continuation lines joined, heredoc bodies attached
+    # to the statement that opened them.
+    def statements
+      lines = @source.lines
+      out = []
+      i = 0
+      while i < lines.size
+        start = i
+        text = strip_comment(lines[i]).strip
+        i += 1
+        next if text.empty?
+
+        heredoc = +""
+        loop do
+          # Heredoc bodies follow the line that opens them; skip to their terminators.
+          text.scan(HEREDOC).each do |_, _, id|
+            while i < lines.size
+              body_line = lines[i]
+              i += 1
+              break if body_line.strip == id
+
+              heredoc << body_line
+            end
+          end
+          break unless continues?(text) && i < lines.size
+
+          nxt = strip_comment(lines[i]).strip
+          i += 1
+          text = "#{text} #{nxt}".strip
+        end
+        if text.match?(/\A#{HEREDOC}\z/) && out.any?
+          # A heredoc on its own line is the body of the block the previous statement opened.
+          out.last.heredoc = "#{out.last.heredoc}#{heredoc}"
+          next
+        end
+        out << Statement.new(text: text, line: start + 1, heredoc: heredoc.empty? ? nil : heredoc)
+      end
+      out
+    end
+
+    # True while brackets are open, or the line ends with `,`, `.` or `\`, or opens a lambda/hash.
+    def continues?(text)
+      depth = 0
+      in_str = nil
+      text.each_char.with_index do |ch, idx|
+        if in_str
+          in_str = nil if ch == in_str && !escaped?(text, idx)
+          next
+        end
+        case ch
+        when '"', "'" then in_str = ch
+        when "[", "{", "(" then depth += 1
+        when "]", "}", ")" then depth -= 1
+        end
+      end
+      return true if in_str || depth.positive?
+
+      text.end_with?(",", ".", "\\", "||", "&&")
+    end
+
+    def escaped?(text, idx)
+      backslashes = 0
+      j = idx - 1
+      while j >= 0 && text[j] == "\\"
+        backslashes += 1
+        j -= 1
+      end
+      backslashes.odd?
+    end
+
     # Removes a trailing `# comment` that is not inside a string literal.
     def strip_comment(line)
       in_str = nil
       line.each_char.with_index do |ch, i|
         if in_str
-          in_str = nil if ch == in_str && line[i - 1] != "\\"
+          in_str = nil if ch == in_str && !escaped?(line, i)
         elsif ch == '"' || ch == "'"
           in_str = ch
         elsif ch == "#"
@@ -140,7 +340,7 @@ module RailsAgentKit
       split_top_level(src).each_with_object({}) do |part, h|
         if (m = part.match(/\A\s*(\w+):\s*(.*)\z/m))
           h[m[1].to_sym] = parse_value(m[2].strip)
-        elsif (m = part.match(/\A\s*["'](\w+)["']\s*=>\s*(.*)\z/m))
+        elsif (m = part.match(/\A\s*:?["']?(\w+)["']?\s*=>\s*(.*)\z/m))
           h[m[1].to_sym] = parse_value(m[2].strip)
         end
       end
@@ -154,7 +354,7 @@ module RailsAgentKit
       when "nil" then nil
       when /\A-?\d+\z/ then s.to_i
       when /\A-?\d+\.\d+\z/ then s.to_f
-      when /\A"(.*)"\z/m then Regexp.last_match(1).gsub('\\"', '"')
+      when /\A"(.*)"\z/m then unescape(Regexp.last_match(1))
       when /\A'(.*)'\z/m then Regexp.last_match(1)
       when /\A:(\w+)\z/ then Regexp.last_match(1)
       when /\A\[(.*)\]\z/m then split_top_level(Regexp.last_match(1)).map { |v| parse_value(v) }
@@ -162,6 +362,16 @@ module RailsAgentKit
       end
     end
 
+    def unescape(str)
+      str.gsub(/\\(.)/) do
+        case Regexp.last_match(1)
+        when "n" then "\n"
+        when "t" then "\t"
+        else Regexp.last_match(1)
+        end
+      end
+    end
+
     def split_top_level(src)
       parts = []
       depth = 0
@@ -169,7 +379,7 @@ module RailsAgentKit
       buf = +""
       src.each_char.with_index do |ch, i|
         if in_str
-          in_str = nil if ch == in_str && src[i - 1] != "\\"
+          in_str = nil if ch == in_str && !escaped?(src, i)
           buf << ch
           next
         end

data/lib/rails_agent_kit/server.rb

@@ -14,11 +14,12 @@ module RailsAgentKit
         name: "rails-agent-kit",
         version: RailsAgentKit::VERSION,
         instructions: "Ground truth about the Rails app at #{context[:root]}. Check it before guessing model " \
-                      "attributes or URL helpers. rails_schema with no arguments lists every table (column counts " \
+                      "attributes, URL helpers or libraries. Call rails_project_info first: Rails and Ruby " \
+                      "versions, database, test framework, auth, jobs and frontend stack. rails_schema with no arguments lists every table (column counts " \
                       "and foreign key targets); then pass table: (one name or an array) for columns, indexes " \
                       "and foreign keys, or search: to find a column by name. rails_routes lists HTTP routes; " \
                       "pass filter: to narrow them.",
-        tools: [Tools::RailsSchema, Tools::RailsRoutes],
+        tools: [Tools::RailsProjectInfo, Tools::RailsSchema, Tools::RailsRoutes],
         server_context: context
       )
     end
@@ -41,6 +42,26 @@ module RailsAgentKit
       end
     end
 
+    class RailsProjectInfo < MCP::Tool
+      extend Helpers
+
+      tool_name "rails_project_info"
+      description "What kind of Rails app this is, read from Gemfile.lock and config files without booting it: " \
+                  "Rails, Ruby and load_defaults versions, api_only, database adapter and databases, test " \
+                  "framework and test data, auth and authorization, jobs, cache and cable backends, frontend " \
+                  "(importmap or bundler, assets, Hotwire, CSS, components), serializers, lint and deploy tools, " \
+                  "mounted engines, notable gems and where tests, factories, policies and components live. " \
+                  "Unknown values are null. Call it first."
+      input_schema(properties: {})
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true, open_world_hint: false)
+
+      def self.call(server_context:)
+        root = context_value(server_context, :root) || Dir.pwd
+        result = ProjectInfo.new(root).call
+        json_response(result, error: result.key?(:error))
+      end
+    end
+
     class RailsSchema < MCP::Tool
       extend Helpers
 

data/lib/rails_agent_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsAgentKit
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/rails_agent_kit.rb

@@ -7,10 +7,11 @@ require_relative "rails_agent_kit/schema_inspector"
 require_relative "rails_agent_kit/routes_parser"
 require_relative "rails_agent_kit/ruby_env"
 require_relative "rails_agent_kit/routes_inspector"
+require_relative "rails_agent_kit/project_info"
 require_relative "rails_agent_kit/skill_installer"
 require_relative "rails_agent_kit/client_config"
 
-# Gives coding agents ground truth about a Rails app (schema, routes) over MCP.
+# Gives coding agents ground truth about a Rails app (stack, schema, routes) over MCP.
 module RailsAgentKit
   class Error < StandardError; end
 

data/skills/rails-8-conventions/SKILL.md

@@ -28,7 +28,9 @@ change the code the way this app already does things.
 - **Routes:** call the `rails_routes` MCP tool (pass `filter:`) before you use a
   `*_path`/`*_url` helper, link, form `url:` or redirect. Without it, read
   `config/routes.rb` or run `bin/rails routes -g <term>`.
-- **Stack:** read `Gemfile.lock` before you pick a library. Use what the app already
+- **Stack:** call the `rails_project_info` MCP tool first, before you pick a library or
+  write a test. It reports the Rails and Ruby versions, database, test framework, auth,
+  jobs and frontend stack. Without it, read `Gemfile.lock`. Use what the app already
   uses (RSpec or Minitest, Sidekiq or Solid Queue, Pundit, Devise or the built-in
   auth generator, importmap or jsbundling). Don't add a gem when the app or Rails
   already covers it.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-agent-kit
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Andrii Furmanets
@@ -39,6 +39,7 @@ files:
 - exe/rails-agent-kit
 - lib/rails_agent_kit.rb
 - lib/rails_agent_kit/client_config.rb
+- lib/rails_agent_kit/project_info.rb
 - lib/rails_agent_kit/routes_inspector.rb
 - lib/rails_agent_kit/routes_parser.rb
 - lib/rails_agent_kit/ruby_env.rb