karst 0.1.0

data/lib/karst/web/populations_panel.rb

@@ -0,0 +1,391 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "securerandom"
+require_relative "../access/population_preview"
+
+module Karst
+  module Web
+    # The local approval surface for Karst::Access::PopulationDiscovery:
+    # browse the application-defined groups Karst found, approve the ones
+    # Karst may try, optionally preview one, and see which approvals are no
+    # longer doing anything. Approving is the whole workflow -- generating
+    # Ruby configuration is kept as an advanced export path, not the way a
+    # developer is expected to finish.
+    #
+    # Kept as a pure renderer, exactly like Karst::Web::Panel: every value
+    # this module needs (the discovery result, the approved entries, stale
+    # approvals, an optional storage error, an optional generated snippet, an
+    # optional single preview) is computed by Karst::Web::Middleware and
+    # passed in, so this file never touches Active Record, the filesystem, or
+    # Karst.config directly.
+    # rubocop:disable Metrics/ModuleLength
+    module PopulationsPanel
+      CANDIDATE_SEPARATOR = "::"
+
+      # Why an approved entry currently does nothing (see
+      # Karst::Access::ApprovedPopulations.stale). Reported rather than
+      # silently ignored -- and never repaired automatically, since the fix
+      # is always a decision about the application, not about Karst.
+      STALE_REASONS = {
+        not_discovered: "no longer a discovered scope on this model — not used",
+        no_principal_source: "not part of a configured user source — not used"
+      }.freeze
+      private_constant :STALE_REASONS
+
+      STYLE = <<~CSS
+        :root{color-scheme:light dark}
+        *{box-sizing:border-box}
+        body{font:16px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",system-ui,sans-serif;max-width:48rem;margin:2rem auto;padding:0 1.25rem;color:#1a1a1a;background:#fff}
+        h1{font-size:1.4rem;margin:0 0 1rem}
+        h2{font-size:1.1rem;margin:1.5rem 0 .5rem}
+        h3{font-size:.85rem;text-transform:uppercase;letter-spacing:.05em;color:#555;margin:1.5rem 0 .6rem;border-bottom:1px solid #e2e2e2;padding-bottom:.35rem}
+        a{color:#2563eb}
+        .lead{margin:.4rem 0 1rem}
+        .hint{color:#8a5b00;font-size:.85rem;margin:.4rem 0}
+        .warning{color:#8a5b00;font-size:.85rem;margin:.4rem 0;border:1px solid #eacb6b;background:#fff7e0;border-radius:.4rem;padding:.6rem .8rem}
+        .saved{color:#0f5132;font-size:.9rem;margin:.4rem 0;border:1px solid #a6d9bb;background:#e6f4ea;border-radius:.4rem;padding:.6rem .8rem}
+        .search-box{margin:1rem 0}
+        .search-box label{display:flex;flex-direction:column;font-size:.78rem;font-weight:600;gap:.25rem;color:#444}
+        .search-box input{font:inherit;padding:.5rem .6rem;border:1px solid #ccc;border-radius:.3rem;max-width:24rem}
+        button{font:inherit;padding:.35rem .65rem;border:1px solid #ccc;border-radius:.35rem;background:#f4f4f4;cursor:pointer}
+        button:hover{background:#eaeaea}
+        button:focus-visible,input:focus-visible,summary:focus-visible,a:focus-visible{outline:2px solid #2563eb;outline-offset:2px}
+        button.primary{background:#202124;border-color:#202124;color:#fff;font-weight:600;padding:.65rem 1.15rem;font-size:.95rem;margin-top:1rem}
+        button.primary:hover{background:#3a3b3e}
+        .approved-summary{border:1px solid #ddd;border-radius:.5rem;padding:.75rem 1rem}
+        .approved-model{margin:.4rem 0}
+        .approved-model strong{display:block}
+        .approved-model ul{margin:.2rem 0 0;padding-left:1.2rem}
+        .approved-model .stale{color:#8a5b00;font-size:.85rem}
+        details.model-group{border:1px solid #e2e2e2;border-radius:.4rem;padding:.5rem .8rem;margin:.5rem 0}
+        details.model-group summary{cursor:pointer;font-weight:600;display:flex;gap:.6rem;align-items:baseline;flex-wrap:wrap}
+        details.model-group summary .count{font-weight:400;color:#666;font-size:.85rem}
+        details.model-group summary .badge{font-weight:400;font-size:.72rem;color:#0f5132;background:#e6f4ea;border-radius:.6rem;padding:.05rem .5rem}
+        .candidate-list{list-style:none;margin:.6rem 0 0;padding:0}
+        .candidate-row{display:flex;align-items:center;gap:.6rem;padding:.3rem 0;flex-wrap:wrap}
+        .candidate-row label{display:flex;align-items:center;gap:.4rem;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:.92rem}
+        .preview{flex-basis:100%;margin:.2rem 0 .3rem 1.6rem;font-size:.85rem;color:#444}
+        .preview.error{color:#8a5b00}
+        .snippet{margin:.6rem 0}
+        .snippet textarea{width:100%;min-height:6rem;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:.85rem;padding:.5rem;border:1px solid #ccc;border-radius:.3rem}
+        details.advanced{border:1px solid #e2e2e2;border-radius:.4rem;padding:.5rem .8rem;margin:1.5rem 0}
+        details.advanced summary{cursor:pointer;font-size:.9rem}
+        code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:.9em}
+        small{color:#666}
+        @media (prefers-color-scheme:dark){
+          body{background:#16171a;color:#e4e4e6}
+          a{color:#7aa2f7}
+          h3{color:#a7a7ad;border-color:#2c2d31}
+          .search-box input,.snippet textarea{background:#1f2023;border-color:#3a3b3e;color:#e4e4e6}
+          button{background:#26272b;border-color:#3a3b3e;color:#e4e4e6}
+          button:hover{background:#303136}
+          button.primary{background:#e4e4e6;border-color:#e4e4e6;color:#16171a}
+          button.primary:hover{background:#c9c9cc}
+          .approved-summary,details.model-group,details.advanced{border-color:#33343a}
+          .hint,.warning,.approved-model .stale{color:#d8a63d}
+          .warning{background:#3a2f0d;border-color:#6b5423}
+          .saved{background:#123822;border-color:#1f5c37;color:#7fd8a4}
+          details.model-group summary .badge{background:#123822;color:#7fd8a4}
+        }
+      CSS
+      private_constant :STYLE
+
+      SEARCH_SCRIPT = <<~JS
+        (function () {
+          var input = document.getElementById("karst-population-search");
+          if (!input) return;
+          var groups = document.querySelectorAll(".model-group");
+          input.addEventListener("input", function () {
+            var query = input.value.trim().toLowerCase();
+            groups.forEach(function (details) {
+              var model = (details.getAttribute("data-model") || "").toLowerCase();
+              var modelMatches = query === "" || model.indexOf(query) !== -1;
+              var rows = details.querySelectorAll(".candidate-row");
+              var anyRowMatches = false;
+              rows.forEach(function (row) {
+                var name = (row.getAttribute("data-name") || "").toLowerCase();
+                var rowMatches = query === "" || modelMatches || name.indexOf(query) !== -1;
+                row.style.display = rowMatches ? "" : "none";
+                if (rowMatches) anyRowMatches = true;
+              });
+              var show = query === "" || modelMatches || anyRowMatches;
+              details.style.display = show ? "" : "none";
+              if (query !== "" && show) details.open = true;
+            });
+          });
+        })();
+      JS
+      private_constant :SEARCH_SCRIPT
+
+      COPY_SCRIPT = <<~JS
+        (function () {
+          var button = document.getElementById("karst-copy-snippet");
+          var field = document.getElementById("karst-snippet-code");
+          if (!button || !field || !navigator.clipboard) return;
+          button.addEventListener("click", function () {
+            navigator.clipboard.writeText(field.value).then(function () {
+              button.textContent = "Copied";
+              setTimeout(function () { button.textContent = "Copy"; }, 1500);
+            }, function () {});
+          });
+        })();
+      JS
+      private_constant :COPY_SCRIPT
+
+      # rubocop:disable Metrics/ClassLength
+      class << self
+        # `approved` and each entry of `stale` are anything exposing
+        # #model_name/#method_name -- in practice
+        # Karst::Access::PopulationApprovals::Entry.
+        # rubocop:disable Metrics/ParameterLists
+        def render(discovery:, approved: [], stale: [], snippet: nil, preview: nil, storage_path: nil,
+                   storage_error: nil, saved: false)
+          nonce = SecureRandom.hex(16)
+          state = { approved: approved, stale: stale, snippet: snippet, preview: preview,
+                    storage_path: storage_path, storage_error: storage_error, saved: saved }
+          [200, headers(nonce), [document(discovery, state, nonce)]]
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        private
+
+        def headers(nonce)
+          csp = "default-src 'none'; style-src 'unsafe-inline'; script-src 'nonce-#{nonce}'; frame-ancestors 'none'"
+          {
+            "content-type" => "text/html; charset=utf-8", "cache-control" => "no-store",
+            "x-robots-tag" => "noindex, nofollow", "x-frame-options" => "DENY", "content-security-policy" => csp
+          }
+        end
+
+        # The per-candidate Preview and the advanced snippet export submit
+        # through their own form, referenced by `form=` rather than nested
+        # inside the approval form (HTML forbids nesting): pressing either
+        # therefore cannot smuggle checkbox state into a save, so the only
+        # way to change what Karst may execute is the explicit approve
+        # button.
+        def document(discovery, state, nonce)
+          <<~HTML
+            <!DOCTYPE html>
+            <html lang="en"><head><meta charset="utf-8"><title>Karst — Candidate groups</title>
+            <style>#{STYLE}</style>
+            </head><body>
+            <h1>Karst</h1>
+            <p><a href="/karst">&larr; Back to route evidence</a></p>
+            <h2>Candidate groups</h2>
+            <p class="lead">Approving a group lets Karst try a few existing users from it when the ordinary sample
+            fails. Approving is not a claim that the group grants access — only running an analysis against a route
+            shows what actually happens.</p>
+            #{saved_notice(state[:saved])}
+            #{storage_error(state[:storage_error])}
+            #{load_warning(discovery)}
+            <form id="karst-secondary" method="post" action="/karst/populations"></form>
+            <form method="post" action="/karst/populations">
+            #{search_box}
+            #{approved_section(state[:approved], state[:stale])}
+            #{model_groups_section(discovery, state[:approved], state[:preview])}
+            <button type="submit" name="save_approvals" value="1" class="primary">Approve selected groups</button>
+            </form>
+            #{advanced_section(state[:snippet])}
+            #{storage_note(state[:storage_path])}
+            <script nonce="#{nonce}">#{SEARCH_SCRIPT}#{COPY_SCRIPT}</script>
+            </body></html>
+          HTML
+        end
+
+        def saved_notice(saved)
+          return "" unless saved
+
+          "<p class=\"saved\" role=\"status\">Approvals saved.</p>"
+        end
+
+        def storage_error(error)
+          return "" unless error
+
+          "<p class=\"warning\" role=\"alert\">#{escape(error)}</p>"
+        end
+
+        def storage_note(path)
+          return "" unless path
+
+          "<p><small>Approvals are stored locally in <code>#{escape(path)}</code> as plain model and " \
+            "scope names — no user data, no Ruby. Delete that file to reset every approval.</small></p>"
+        end
+
+        def load_warning(discovery)
+          return "" unless discovery.load_warning
+
+          "<p class=\"warning\" role=\"alert\">#{escape(discovery.load_warning)}</p>"
+        end
+
+        def search_box
+          <<~HTML
+            <div class="search-box">
+            <label>Search groups or models
+            <input type="search" id="karst-population-search" placeholder="e.g. admin, User, subscription">
+            </label>
+            </div>
+          HTML
+        end
+
+        # -- Approved summary --------------------------------------------------
+
+        def approved_section(approved, stale)
+          body = if approved.empty?
+                   "<p>No groups approved yet.</p>"
+                 else
+                   approved.group_by(&:model_name).sort.map do |model_name, group|
+                     approved_model(model_name, group, stale)
+                   end.join
+                 end
+          "<section class=\"approved-summary\"><h3>Approved (#{approved.size})</h3>#{body}</section>"
+        end
+
+        def approved_model(model_name, entries, stale)
+          items = entries.sort_by { |entry| entry.method_name.to_s }.map do |entry|
+            "<li>#{escape(entry.method_name)}#{stale_note(entry, stale)}</li>"
+          end.join
+          "<div class=\"approved-model\"><strong>#{escape(model_name)}</strong><ul>#{items}</ul></div>"
+        end
+
+        def stale_note(entry, stale)
+          match = stale.find { |item, _reason| same_candidate?(item, entry) }
+          return "" unless match
+
+          " <span class=\"stale\">— #{escape(STALE_REASONS.fetch(match.last, 'not used'))}</span>"
+        end
+
+        def same_candidate?(left, right)
+          left.model_name.to_s == right.model_name.to_s && left.method_name.to_s == right.method_name.to_s
+        end
+
+        # -- Model groups ------------------------------------------------------
+
+        def model_groups_section(discovery, approved, preview)
+          groups = discovery.model_groups.reject { |group| group.candidate_names.empty? }
+          body = if groups.empty?
+                   "<p>No candidate groups were discovered.</p>"
+                 else
+                   groups.map { |group| model_group(group, approved, preview) }.join
+                 end
+          "<section class=\"model-groups\"><h3>Available models</h3>#{body}</section>"
+        end
+
+        def model_group(group, approved, preview)
+          approved_names = approved.select { |entry| entry.model_name == group.model_name }
+                                   .map { |entry| entry.method_name.to_s }
+          open = approved_names.any? ? " open" : ""
+          rows = group.candidate_names.map { |name| candidate_row(group, name, approved_names, preview) }.join
+          <<~HTML
+            <details class="model-group" data-model="#{escape(group.model_name)}"#{open}>
+            <summary>#{model_summary(group)}</summary>
+            <ul class="candidate-list">#{rows}</ul>
+            </details>
+          HTML
+        end
+
+        def model_summary(group)
+          count = group.candidate_names.size
+          "#{escape(group.model_name)} <span class=\"count\">#{count} group#{'s' unless count == 1}</span>" \
+            "#{principal_badge(group)}"
+        end
+
+        def principal_badge(group)
+          return "" unless group.principal_source
+
+          "<span class=\"badge\">user source: #{escape(group.principal_source)}</span>"
+        end
+
+        def candidate_row(group, method_name, approved_names, preview)
+          key = candidate_key(group.model_name, method_name)
+          checked = approved_names.include?(method_name.to_s)
+          box = "<input type=\"checkbox\" name=\"population[]\" value=\"#{escape(key)}\"#{' checked' if checked}>"
+          preview_button = "<button type=\"submit\" form=\"karst-secondary\" name=\"preview\" " \
+                           "value=\"#{escape(key)}\">Preview</button>"
+          label = "<label>#{box} #{escape(method_name)}</label>"
+          "<li class=\"candidate-row\" data-name=\"#{escape(method_name)}\">#{label}" \
+            "#{preview_button}#{preview_result(group, method_name, preview)}</li>"
+        end
+
+        def preview_result(group, method_name, preview)
+          unless preview && preview.model_name == group.model_name && preview.method_name.to_s == method_name.to_s
+            return ""
+          end
+
+          preview.resolved ? preview_success(preview) : preview_failure(preview)
+        end
+
+        def preview_success(preview)
+          return "<p class=\"preview\">Preview: no matching records currently.</p>" if preview.records.empty?
+
+          labels = preview.records.map { |record| record_label(record) }.join(", ")
+          "<p class=\"preview\">Preview (up to #{Access::PopulationPreview::PREVIEW_LIMIT}): #{escape(labels)}</p>"
+        end
+
+        def preview_failure(preview)
+          "<p class=\"preview error\">Preview: #{escape(preview.error)}.</p>"
+        end
+
+        # Deliberately generic -- "ModelName #id" only, never an arbitrary
+        # attribute dump, regardless of whether the previewed model happens
+        # to be a configured principal source. A discovered candidate may
+        # belong to any application model, not only ones a developer has
+        # already reviewed for what is safe to display.
+        def record_label(record)
+          primary_key = record.class.respond_to?(:primary_key) ? record.class.primary_key : "id"
+          "#{record.class.name} ##{record.public_send(primary_key)}"
+        end
+
+        # -- Advanced: Ruby export ---------------------------------------------
+
+        # Approving is the workflow; this stays available for an application
+        # that would rather commit its populations as reviewable Ruby (a
+        # shared or CI environment, where a machine-local approval file is
+        # deliberately not consulted).
+        def advanced_section(snippet)
+          <<~HTML
+            <details class="advanced"#{' open' if snippet}><summary>Advanced: export approvals as Ruby
+            configuration</summary>
+            <p><small>Explicit <code>config.principal_populations</code> keeps working exactly as before and always
+            takes precedence over an approval of the same name. Karst never writes to your application's files.
+            </small></p>
+            <button type="submit" form="karst-secondary" name="generate_snippet" value="1">Generate snippet from
+            approvals</button>
+            #{snippet_section(snippet)}
+            </details>
+          HTML
+        end
+
+        def snippet_section(snippet)
+          return "" unless snippet
+
+          <<~HTML
+            <div class="snippet">
+            <textarea id="karst-snippet-code" readonly>#{escape(snippet.code)}</textarea>
+            <p><button type="button" id="karst-copy-snippet">Copy</button></p>
+            #{unwired_note(snippet)}
+            </div>
+          HTML
+        end
+
+        def unwired_note(snippet)
+          return "" if snippet.unwired.empty?
+
+          names = snippet.unwired.map { |c| "#{c.model_name}.#{c.method_name}" }.join(", ")
+          "<p class=\"hint\">#{snippet.unwired.size} approved group(s) are not part of a configured " \
+            "user source yet and were left out of the snippet above: #{escape(names)}.</p>"
+        end
+
+        def candidate_key(model_name, method_name)
+          "#{model_name}#{CANDIDATE_SEPARATOR}#{method_name}"
+        end
+
+        def escape(value)
+          CGI.escapeHTML(value.to_s)
+        end
+      end
+      # rubocop:enable Metrics/ClassLength
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end

data/lib/karst/web/route_lookup.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "uri"
+require "active_support/core_ext/string/inflections"
+
+module Karst
+  module Web
+    # Establishes route context for a manually entered application path. Rails'
+    # router is the authority: Karst does not infer a controller or action from
+    # the shape of the URL.
+    class RouteLookup
+      Result = Struct.new(:params, :limitation, keyword_init: true)
+
+      def initialize(path:, http_method:, application: Rails.application)
+        @path = path.to_s.strip
+        @http_method = http_method.to_s.strip.upcase
+        @application = application
+      end
+
+      def call
+        path = local_path
+        recognized = @application.routes.recognize_path(path, method: method)
+        return limitation("the recognized route did not identify a controller and action") unless complete?(recognized)
+
+        Result.new(params: recognized_params(recognized, path))
+      rescue URI::InvalidURIError
+        limitation("Path must be a valid local application path.")
+      rescue ActionController::RoutingError
+        limitation("Rails could not recognize that path and method. Karst will not guess the route.")
+      rescue StandardError => e
+        limitation("Rails route recognition was unavailable (#{e.class}). Karst will not guess the route.")
+      end
+
+      private
+
+      def complete?(recognized)
+        !recognized[:controller].to_s.empty? && !recognized[:action].to_s.empty?
+      end
+
+      def recognized_params(recognized, path)
+        {
+          "controller" => "#{recognized[:controller].to_s.camelize}Controller",
+          "action" => recognized[:action].to_s, "method" => method, "path" => path
+        }
+      end
+
+      def local_path
+        raw = @path.split("?", 2).first
+        uri = URI.parse(raw)
+        valid = uri.relative? && raw.start_with?("/") && !raw.start_with?("//")
+        raise URI::InvalidURIError unless valid
+
+        raw
+      end
+
+      def method
+        @http_method.empty? ? "GET" : @http_method
+      end
+
+      def limitation(message)
+        Result.new(params: { "method" => method, "path" => @path }, limitation: message)
+      end
+    end
+  end
+end

data/lib/karst.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# On Rails 6.1, active_support/logger_thread_safe_level.rb references the
+# bare ::Logger constant before active_support/logger.rb gets around to
+# requiring "logger" itself -- a load-order bug in that Rails series, not a
+# version conflict (it reproduces with Ruby's own bundled logger release,
+# not just newer ones). A full Rails boot usually papers over it by sheer
+# luck of some other gem having required "logger" first; requiring it here
+# up front means `require "karst"` never depends on that luck.
+require "logger"
+
+require_relative "karst/version"
+require_relative "karst/configuration"
+require_relative "karst/identity"
+require_relative "karst/access/sweep"
+require_relative "karst/access/principal_source"
+require_relative "karst/access/principal_sampler"
+require_relative "karst/access/principal_selection"
+require_relative "karst/access/search"
+require_relative "karst/access/resource_evidence"
+require_relative "karst/access/candidate_population"
+require_relative "karst/access/population_discovery"
+require_relative "karst/access/population_approvals"
+require_relative "karst/access/approved_populations"
+require_relative "karst/access/population_preview"
+require_relative "karst/access/population_config_snippet"
+require_relative "karst/access/principal_source_selection"
+require_relative "karst/access/selected_principal_sources"
+
+# Public entry point for Karst configuration.
+module Karst
+  @ownership_mutex = Mutex.new
+
+  private_constant :Configuration
+
+  class << self
+    def configure
+      yield config
+    end
+
+    def config
+      @ownership_mutex.synchronize { @config ||= Configuration.new }
+    end
+
+    # The single switch that turns Karst's whole development surface off:
+    # /karst, the page badge, `bin/rails karst:verify`, and the MCP
+    # verify_access tool all refuse to run when this is false. Defaults to
+    # development/test only, so an application that never configures Karst
+    # at all still cannot expose it in production.
+    def enabled?
+      config.enabled
+    end
+  end
+end
+
+require_relative "karst/railtie" if defined?(Rails::Railtie)

data/lib/rails/commands/karst/boot.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Rails
+  module Command
+    module Karst
+      # Shared by every Karst Rails::Command: boots the host application the
+      # same way Rails' own commands do (Rails::Command::Actions#boot_application!
+      # on Rails >= 7.1, #require_application_and_environment! before that),
+      # without depending on either method name existing across Karst's whole
+      # supported Rails range. `require_application!` (from
+      # Rails::Command::Actions, already included into Rails::Command::Base)
+      # plus Rails.application.require_environment! is exactly what both of
+      # those version-specific wrappers do internally.
+      module Boot
+        private
+
+        def boot_karst_application!
+          require_application!
+          Rails.application.require_environment! if defined?(APP_PATH)
+        end
+      end
+    end
+  end
+end

data/lib/rails/commands/karst/mcp/mcp_command.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "rails/command"
+require "karst/mcp/server"
+require_relative "../boot"
+
+module Rails
+  module Command
+    module Karst
+      # Rails command entry point for Karst's MCP server: `bin/rails karst:mcp`.
+      # Boots the host application once, the same way any other Karst Rails
+      # command does (see Karst::Boot), then serves verify_access tool calls
+      # over stdio for the lifetime of the process -- never a second
+      # application copy per call.
+      class McpCommand < Base
+        include Karst::Boot
+
+        desc "Run Karst's MCP server over stdio, exposing the verify_access tool"
+        def perform(*)
+          boot_karst_application!
+          ::Karst::Mcp::Server.run!
+        end
+      end
+    end
+  end
+end

data/lib/rails/commands/karst/verify/verify_command.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rails/command"
+require "karst/cli/verification"
+require_relative "../boot"
+
+module Rails
+  module Command
+    module Karst
+      # Rails command entry point for the shared Access::Search adapter.
+      class VerifyCommand < Base
+        include Karst::Boot
+
+        class_option :json, type: :boolean, default: false, desc: "Emit stable JSON evidence"
+
+        desc "Verify bounded GET access to a local application path"
+        def perform(*arguments)
+          method, path = parse(arguments)
+          boot_karst_application!
+          exit(::Karst::CLI::Verification.new(path: path, http_method: method, json: options[:json]).call)
+        rescue ArgumentError => e
+          document = { schema_version: 1, error: { type: "input_error", message: e.message } }
+          puts(options[:json] ? JSON.generate(document) : "Karst cannot verify this route:\n#{e.message}")
+          exit(2)
+        end
+
+        private
+
+        def parse(arguments)
+          raise ArgumentError, "a local application path is required" if arguments.empty?
+          return ["GET", arguments.first] if arguments.size == 1
+          raise ArgumentError, "expected METHOD PATH" unless arguments.size == 2
+
+          arguments
+        end
+      end
+    end
+  end
+end

data/lib/tasks/karst.rake

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+namespace :karst do
+  desc "List zero-argument scopes declared directly in application model source. Never executes them."
+  task populations: :environment do
+    require "karst/access/population_discovery"
+    require "karst/access/population_approvals"
+
+    result = Karst::Access::PopulationDiscovery.new.call
+    approvals = Karst::Access::PopulationApprovals.load
+    groups = result.model_groups.reject { |group| group.candidate_names.empty? }
+
+    puts "Warning: #{result.load_warning}\n\n" if result.load_warning
+    puts "Warning: #{approvals.error}\n\n" if approvals.error
+    puts "No candidate scopes were discovered." if groups.empty?
+
+    groups.each do |group|
+      label = group.principal_source ? " (principal source: #{group.principal_source})" : ""
+      puts "#{group.model_name}#{label} -- #{group.candidate_names.size} scope(s)"
+      group.candidate_names.each do |name|
+        puts "  #{name}#{' [approved]' if approvals.approved?(group.model_name, name)}"
+      end
+    end
+
+    puts "", <<~NOTES
+      These are discovered scopes only -- Karst has not verified any of them return a usable relation,
+      and none of this grants access or is wired into sampling on its own.
+      Only scopes declared directly on application models are included; concern-defined scopes may not appear.
+      Approve the ones Karst may try at /karst/populations. Approvals are stored locally in
+      #{Karst::Access::PopulationApprovals.display_path}; delete that file to reset them.
+      config.principal_populations remains supported and always takes precedence.
+    NOTES
+  end
+end