gemchat 0.1.0

data/lib/gemchat/cli.rb

@@ -0,0 +1,731 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Gemchat
+  class CLI
+    # "matched" is absent from `search` and `vsearch` rows and present on
+    # `query` rows, where it names the arms that found the chunk. `project` only
+    # copies keys a row actually has, so it appears in hybrid JSON and nowhere
+    # else without being special-cased.
+    RESULT_KEYS = %w[gem_name gem_version source_type title class_name method_name signature source_path source_line url body score matched hosted].freeze
+
+    def self.start(argv, stdout: $stdout, stderr: $stderr)
+      new(stdout:, stderr:).run(argv)
+    end
+
+    def initialize(stdout: $stdout, stderr: $stderr)
+      @stdout = stdout
+      @stderr = stderr
+    end
+
+    def run(argv)
+      command = argv.shift
+      case command
+      when "init" then cmd_init(argv)
+      when "index" then cmd_index(argv)
+      when "reindex" then cmd_reindex(argv)
+      when "search" then cmd_search(argv)
+      when "embed" then cmd_embed(argv)
+      when "vsearch" then cmd_vsearch(argv)
+      when "query" then cmd_query(argv)
+      when "status" then cmd_status(argv)
+      when "version" then cmd_version
+      when nil, "help", "-h", "--help" then usage
+      else
+        @stderr.puts("unknown command: #{command}")
+        usage
+        1
+      end
+    rescue OptionParser::ParseError => e
+      @stderr.puts(e.message)
+      1
+    rescue Gemchat::Error => e
+      @stderr.puts("error: #{e.message}")
+      1
+    end
+
+    private
+
+    def cmd_init(argv)
+      opts = {yes: false, help: false, index: true, hosted: false}
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: gemchat init [options]"
+        o.on("-y", "--yes", "Do not prompt") { opts[:yes] = true }
+        o.on("--[no-]index", "Index immediately (default: on)") { |v| opts[:index] = v }
+        o.on("--hosted", "Record the hosted backend as this project's default") { opts[:hosted] = true }
+        o.on("-h", "--help") { opts[:help] = true }
+      end
+      parser.parse!(argv)
+      if opts[:help]
+        @stdout.puts(parser)
+        return 0
+      end
+
+      result = Init.new(stdout: @stdout, assume_yes: opts[:yes]).run
+
+      if result.changed?
+        result.added.each { |line| @stdout.puts("added to Gemfile: #{line}") }
+      else
+        @stdout.puts("Gemfile already declares gemchat; nothing to add")
+      end
+      @stdout.puts("trusted this project: #{Dir.pwd}")
+
+      if opts[:hosted]
+        manifest = Manifest.new
+        manifest.hosted = true
+        manifest.write
+        @stdout.puts("default backend: hosted (gemchat.org); `gemchat query` will use it")
+        @stdout.puts("  still needs a key: GEMCHAT_API_KEY, or #{Hosted.credentials_path}")
+      end
+
+      # Trust plus a manifest means the next bundle install is a no-op, so arm
+      # the hook before doing any work: a failed index must not leave the user
+      # thinking the plugin is live.
+      @stdout.puts("")
+      @stdout.puts("Run `bundle install` once to arm the plugin hook.")
+      @stdout.puts("It then indexes automatically whenever Gemfile.lock changes.")
+
+      return 0 unless opts[:index]
+
+      @stdout.puts("")
+      cmd_index([])
+    end
+
+    # The remediation `Store::IdentityError` names, so the error is actionable
+    # rather than just refusing.
+    def cmd_reindex(argv)
+      opts = {help: false}
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: gemchat reindex"
+        o.on("-h", "--help") { opts[:help] = true }
+      end
+      parser.parse!(argv)
+      if opts[:help]
+        @stdout.puts(parser)
+        return 0
+      end
+
+      store = Store.new
+      store.close
+      FileUtils.rm_f(store.path)
+      FileUtils.rm_rf(File.join(Gemchat.root, "ri"))
+      @stdout.puts("removed the old index and generated ri cache")
+      @stdout.puts("")
+      cmd_index([])
+    end
+
+    def cmd_index(argv)
+      opts = {include_transitive: false, dry_run: false, only: [], help: false, json: false, all_languages: false}
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: gemchat index [options]"
+        o.on("--all", "Include transitive dependencies") { opts[:include_transitive] = true }
+        o.on("--dry-run", "Report what would be indexed, write nothing") { opts[:dry_run] = true }
+        o.on("--only=GEMS", Array, "Comma-separated gems to index") { |g| opts[:only] = g }
+        o.on("--all-languages", "Also index translated documentation") { opts[:all_languages] = true }
+        o.on("--json", "Machine-readable summary on stdout") { opts[:json] = true }
+        o.on("-h", "--help") { opts[:help] = true }
+      end
+      parser.parse!(argv)
+      if opts[:help]
+        @stdout.puts(parser)
+        return 0
+      end
+
+      indexer = Indexer.new(store: Store.new, include_transitive: opts[:include_transitive],
+        all_languages: opts[:all_languages])
+      specs = indexer.lockfile_specs
+      unless opts[:only].empty?
+        wanted = Set.new(opts[:only])
+        specs = specs.select { |name, _version| wanted.member?(name) }
+      end
+
+      if opts[:dry_run]
+        @stdout.puts("lockfile: #{specs.size} gems (#{opts[:include_transitive] ? "all" : "direct"})")
+        specs.each { |name, version| @stdout.puts("  would index #{name} #{version}") }
+        return 0
+      end
+
+      results = specs.map { |name, version| index_one(indexer, name, version, quiet: opts[:json]) }
+      total = results.sum(&:chunks)
+      changed = results.count(&:changed?)
+      unchanged = results.count { |r| r.status == :unchanged }
+      generated = results.count { |r| r.ri_source == "generated" }
+      existing = results.count { |r| r.ri_source == "existing" }
+      failed = results.reject(&:ok?)
+
+      # An explicit index run is the thing that grants trust, so running it
+      # yourself is how a project opts in to the plugin's auto-indexing.
+      Trust.grant!(Dir.pwd, via: "gemchat index")
+      write_manifest(specs, opts[:include_transitive])
+
+      summary = {
+        "gems" => results.size,
+        "chunks" => total,
+        "changed" => changed,
+        "unchanged" => unchanged,
+        "failed" => failed.size
+      }
+
+      if opts[:json]
+        # The last line is the contract the plugin hook parses, so per-gem
+        # progress must not be interleaved with it.
+        @stdout.puts(JSON.generate(summary))
+      else
+        @stdout.puts("lockfile: #{results.size} gems (#{opts[:include_transitive] ? "all" : "direct"})")
+        @stdout.puts(format("%d gems · %d chunks written (ri: %d existing, %d generated)",
+          results.size, total, existing, generated))
+        @stdout.puts(format("%d changed, %d unchanged", changed, unchanged)) if unchanged.positive?
+      end
+
+      failed.each { |r| @stderr.puts("  #{r.name}: #{r.error}") }
+      failed.empty? ? 0 : 1
+    end
+
+    # Records what the index was built from, so the plugin can answer "is there
+    # anything to do?" by reading 64 bytes instead of opening SQLite.
+    def write_manifest(specs, _include_transitive)
+      digest = Lockfile.digest
+      return if digest.nil?
+
+      Manifest.new(Dir.pwd).record(digest, specs.to_h { |name, version|
+        [name, {"version" => version}]
+      }).write
+    end
+
+    def index_one(indexer, name, version, quiet: false)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = indexer.index_gem(name, version)
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+      unless quiet
+        label = if result.changed?
+          format("%6d chunks", result.chunks)
+        else
+          format("%6s", result.status)
+        end
+        @stdout.puts(format("  %-32s %s  %-8s %5.2fs", "#{name} #{version}", label, result.ri_source, elapsed))
+      end
+      result
+    end
+
+    def cmd_search(argv)
+      opts = {limit: 10, min_score: 0.0, json: false, help: false}
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: gemchat search QUERY [options]"
+        o.on("-n N", Integer, "Number of results") { |n| opts[:limit] = n }
+        o.on("--min-score F", Float, "Minimum score") { |f| opts[:min_score] = f }
+        o.on("--json", "JSON output") { opts[:json] = true }
+        o.on("-h", "--help") { opts[:help] = true }
+      end
+      parser.parse!(argv)
+      if opts[:help]
+        @stdout.puts(parser)
+        return 0
+      end
+
+      query = argv.join(" ").strip
+      raise Gemchat::Error, "a query is required" if query.empty?
+
+      results = Store.new.search(query, limit: opts[:limit], min_score: opts[:min_score])
+      if opts[:json]
+        @stdout.puts(JSON.pretty_generate(results.map { |row| project(row) }))
+      else
+        results.each_with_index { |row, i| @stdout.puts(format_result(i + 1, row)) }
+        @stdout.puts("no results") if results.empty?
+      end
+      0
+    end
+
+    def project(row)
+      RESULT_KEYS.each_with_object({}) do |key, out|
+        out[key] = row[key] if row.key?(key)
+      end
+    end
+
+    # The source is shown because it changes how a result should be read: an ri
+    # hit is a signature, a readme hit is prose. An agent that cannot tell them
+    # apart has to guess whether it is looking at an API or a tutorial.
+    def format_result(position, row)
+      detail = (row["signature"].to_s.empty? ? row["body"].to_s : row["signature"].to_s)
+      summary = detail.lines.first.to_s.strip[0, 100]
+      format("%2d. [%-14s %-9s %-7s] %s\n    %s%s",
+        position, row["gem_name"], row["gem_version"], row["source_type"],
+        row["title"], summary, citation(row))
+    end
+
+    # ri says a method exists; the Prism pass says where. Printed when present
+    # because it is the one thing a result cannot be used without and cannot be
+    # inferred from -- the line to open, and the file to open it in.
+    def citation(row)
+      path = row["source_path"].to_s
+      return "" if path.empty?
+
+      line = row["source_line"]
+      line ? "  (#{path}:#{line})" : "  (#{path})"
+    end
+
+    # `embed` is the only command that downloads a model, and it is explicit.
+    # Search stays BM25-only until it runs, so a fresh install is instantly
+    # useful and nothing silently pulls 146MB.
+    def cmd_embed(argv)
+      opts = {force: false, limit: nil, dry_run: false, help: false, json: false}
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: gemchat embed [options]"
+        o.on("--force", "Discard existing vectors and embed every chunk again") { opts[:force] = true }
+        o.on("--limit N", Integer, "Embed at most N chunks") { |n| opts[:limit] = n }
+        o.on("--dry-run", "Report what would be embedded") { opts[:dry_run] = true }
+        o.on("--json", "Machine-readable summary") { opts[:json] = true }
+        o.on("-h", "--help") { opts[:help] = true }
+      end
+      parser.parse!(argv)
+      if opts[:help]
+        @stdout.puts(parser)
+        return 0
+      end
+
+      name = Models.default
+      unless Models.installed?(name)
+        # Advisory only. A missing model must not stop the command: it is the
+        # one place the download can be triggered from.
+        Models.present(name)
+        @stdout.puts("downloading #{name} (#{Models.megabytes(name)}MB)…")
+        Models.download(name, stdout: @stdout)
+        @stdout.puts("")
+      end
+
+      store = Store.new
+      identity = Models.identity(name)
+      if opts[:force]
+        dropped = store.clear_vectors
+        @stdout.puts("discarded #{dropped} existing vector(s); embedding every chunk")
+      end
+
+      # Checked before selecting rows. Rows that already hold a vector are
+      # excluded from the work list, so with a mismatched model there is nothing
+      # to embed and the run would report "nothing to embed" -- true, and useless.
+      begin
+        store.assert_embedding_model!(Models.identity(name))
+      rescue Store::EmbeddingModelMismatch => e
+        @stderr.puts(e.message)
+        return 1
+      end
+
+      rows = store.unembedded_chunks(limit: opts[:limit])
+
+      if rows.empty?
+        if opts[:json]
+          @stdout.puts(JSON.generate({"embedded" => 0, "reason" => "up to date"}))
+        else
+          @stdout.puts("nothing to embed; every chunk already has a vector")
+        end
+        return 0
+      end
+
+      texts = rows.map { |r| r["searchable"] }
+      if opts[:dry_run]
+        @stdout.puts("#{rows.size} chunks would be embedded with #{identity}")
+        return 0
+      end
+
+      embedder = Embedder.build(name)
+      if embedder.null?
+        @stderr.puts("no usable embedder; run `gemchat embed` again")
+        return 1
+      end
+
+      # embed returns [index, vector] pairs because a batch can fail even after
+      # backoff; only the pairs that came back get written, and the rest stay
+      # pending for the next run rather than being misaligned onto the wrong row.
+      embedded = embedder.embed(texts)
+      written = store.store_embeddings(
+        embedded.map { |i, _| rows[i]["id"] },
+        embedded.map { |_, vector| vector },
+        identity: embedder.identity,
+        dimensions: embedder.dimensions
+      )
+
+      if opts[:json]
+        @stdout.puts(JSON.generate({"embedded" => written, "model" => embedder.identity}))
+      else
+        @stdout.puts("embedded #{written} chunks with #{embedder.identity} (#{embedder.dimensions}d)")
+      end
+      0
+    rescue Store::EmbeddingModelMismatch => e
+      @stderr.puts("error: #{e.message}")
+      1
+    end
+
+    def cmd_vsearch(argv)
+      opts = {limit: 10, help: false, json: false}
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: gemchat vsearch QUERY [options]"
+        o.on("-n N", Integer, "Number of results") { |n| opts[:limit] = n }
+        o.on("--json", "JSON output") { opts[:json] = true }
+        o.on("-h", "--help") { opts[:help] = true }
+      end
+      parser.parse!(argv)
+      if opts[:help]
+        @stdout.puts(parser)
+        return 0
+      end
+
+      query = argv.join(" ").strip
+      raise Gemchat::Error, "a query is required" if query.empty?
+
+      store = Store.new
+      unless store.meta("embed_model")
+        @stderr.puts("no vectors yet → run `gemchat embed`")
+        @stderr.puts("`gemchat search` still works; it uses BM25 and needs no model")
+        return 1
+      end
+
+      vector = embed_query(query)
+      return 1 if vector.nil?
+
+      results = store.vector_search(vector, limit: opts[:limit])
+      emit(results, opts)
+    end
+
+    # `gemchat query` — hybrid, with the type chosen by a leading token.
+    #
+    # The three types are not synonyms for "how to spell the query". They pick
+    # which arms run, because the two engines fail in opposite directions:
+    # measured on the rake index, BM25 returns *no results at all* for a
+    # natural-language question, and a vector search is measurably worse than
+    # BM25 at an exact identifier. So the default sends a question to both arms
+    # and fuses, `lex:` sends identifiers to BM25 alone, and `vec:` sends a
+    # paraphrase to the vector arm alone.
+    #
+    # Degrades to BM25 rather than failing when there are no vectors, because a
+    # search command that exits 1 is worse than a search command that answers
+    # less well and says so. It never downloads: `embed` is the only command
+    # that fetches a model, and a 146MB download in the middle of a query is not
+    # something to discover.
+    def cmd_query(argv)
+      opts = {limit: 10, help: false, json: false, hosted: false, auto_index: false}
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: gemchat query [lex:|vec:|hyde:] QUESTION [options]"
+        o.on("-n N", Integer, "Number of results") { |n| opts[:limit] = n }
+        o.on("--json", "JSON output") { opts[:json] = true }
+        o.on("--hosted", "Query gemchat.org instead of the local index (explicit; never a fallback)") { opts[:hosted] = true }
+        o.on("--auto-index", "With --hosted, ask the server to index gems it does not have") { opts[:auto_index] = true }
+        o.on("-h", "--help") { opts[:help] = true }
+      end
+      parser.parse!(argv)
+      if opts[:help]
+        @stdout.puts(parser)
+        return 0
+      end
+
+      raw = argv.join(" ").strip
+      raise Gemchat::Error, "a query is required" if raw.empty?
+
+      type, question = split_type(raw)
+      return hosted_query(question, opts, type: type) if opts[:hosted] || hosted_default?
+
+      store = Store.new
+
+      # The type maps straight onto which arms run. `lex:` is BM25 alone, for a
+      # caller naming an identifier. The fused default adds the vector arm, and
+      # the lexical arm keeps exact-phrase semantics on purpose: see
+      # `Store#hybrid_search` for why OR-ing the terms measures worse, not
+      # better, and why a bad arm is worse for fusion than no arm.
+      plan = {
+        lex: {lex: true, lex_mode: :phrase, vector: false},
+        vec: {lex: false, lex_mode: :phrase, vector: true},
+        hyde: {lex: true, lex_mode: :phrase, vector: true}
+      }.fetch(type)
+
+      has_vectors = !store.meta("embed_model").nil?
+      if plan[:vector] && !has_vectors
+        @stderr.puts("no vectors yet → run `gemchat embed`")
+        @stderr.puts("`gemchat search` still works; it uses BM25 and needs no model")
+        # `vec:` asked for semantics, so answering with keyword matches misleads.
+        # The fused default is a question, and a question is better served by a
+        # weaker answer than by none.
+        return 1 if type == :vec
+      end
+      use_vector = plan[:vector] && has_vectors
+
+      vector = nil
+      if use_vector
+        vector = embed_query(question)
+        return 1 if vector.nil?
+      elsif plan[:vector]
+        @stderr.puts("falling back to BM25 only; run `gemchat embed` for hybrid")
+      end
+
+      results = store.hybrid_search(
+        question, query_vector: vector,
+        lex: plan[:lex], lex_mode: plan[:lex_mode], limit: opts[:limit]
+      )
+      emit(results, opts)
+    end
+
+    # The hosted path. Explicit only: `--hosted` on the invocation, or a
+    # project default set by `gemchat init --hosted`. There is no code path that
+    # reaches this without one of those, and a failure here stops rather than
+    # quietly answering from the local index -- a user who asked for hosted
+    # results and silently got local ones cannot tell the difference.
+    #
+    # The lockfile's exact versions go with the query. That is the hosted tier's
+    # biggest advantage over what §12.3 originally claimed: pins mean the answer
+    # is about the version actually installed, and the server discloses any pin
+    # it could not apply.
+    def hosted_query(question, opts, type: :hyde)
+      hosted = Hosted.new
+      unless hosted.configured?
+        @stderr.puts("hosted backend not configured")
+        @stderr.puts("  set GEMCHAT_API_KEY, or write GEMCHAT_API_KEY=... to #{Hosted.credentials_path}")
+        @stderr.puts("  keys: gemchat.org/settings")
+        @stderr.puts("`gemchat query` without --hosted still searches the local index")
+        return 1
+      end
+
+      # Only `hyde`/`vec` have a hosted equivalent. `lex:` is BM25, which §12.2
+      # records as local-only, so saying so beats silently returning something else.
+      if type == :lex
+        @stderr.puts("`lex:` is BM25 and has no hosted equivalent; `gemchat search` covers it locally")
+        return 1
+      end
+
+      names, versions = lockfile_pins
+      result = hosted.query(question, limit: opts[:limit], gem_names: names, gem_versions: versions,
+        auto_index: opts[:auto_index])
+      report_hosted(result, opts)
+    rescue Hosted::Unauthorized => e
+      @stderr.puts("error: #{e.message}")
+      1
+    rescue Hosted::Error => e
+      @stderr.puts("error: #{e.message}")
+      1
+    end
+
+    # The gem names and exact versions to pin the hosted query to, taken from this
+    # project's Gemfile.lock.
+    #
+    # Direct dependencies only, matching the scope `gemchat index` uses, so the
+    # pinned set is the same set the local index holds. Sending all 200
+    # transitive specs would be a much larger request to say the same thing.
+    #
+    # A missing or unparseable lockfile yields empty lists, which the server reads
+    # as "search everything" -- degraded, but not wrong, and better than refusing
+    # to search because the project is not a Bundler project.
+    def lockfile_pins
+      path = File.join(Dir.pwd, "Gemfile.lock")
+      return [[], []] unless File.file?(path)
+
+      parsed = ::Bundler::LockfileParser.new(File.read(path))
+      specs = parsed.specs.reject { |s| s.name == "ruby-core-stdlib" }
+      direct = parsed.dependencies.keys - ["ruby-core-stdlib"]
+      specs = specs.select { |s| direct.include?(s.name) }
+      [specs.map(&:name), specs.map { |s| s.version.to_s }]
+    rescue
+      [[], []]
+    end
+
+    def report_hosted(result, opts)
+      report_hosted_scope(result.scope) if result.rows.empty?
+      @stderr.puts("note: #{result.version_note}") if result.version_note
+      @stderr.puts(result.notice) if result.notice
+      if result.missing.any? && result.rows.empty?
+        @stderr.puts("not indexed on gemchat.org: #{result.missing.join(", ")}")
+        @stderr.puts("  re-run with --auto-index to ask the server to index them")
+      end
+
+      rows = result.rows.map { |row| hosted_row(row) }
+      emit(rows, opts)
+    end
+
+    # Why there are no results, when the server can say. The two cases look
+    # identical on the wire otherwise, and they call for opposite reactions:
+    # "nothing matched" means widen the query, "nothing was searchable" means the
+    # index is not built and the query was never really asked.
+    def report_hosted_scope(scope)
+      return if scope.nil?
+
+      unless scope["searchable"]
+        @stderr.puts("nothing in scope is searchable: #{scope["vectorized"]}/#{scope["chunks"]} chunks have vectors")
+        @stderr.puts("  this is not an empty result -- the hosted index has no searchable content for this query")
+        return
+      end
+
+      @stderr.puts("scope: #{scope["vectorized"]}/#{scope["chunks"]} chunks searchable across #{scope["gems"]} gem(s)")
+    end
+
+    # Hosted rows carry a url or file_path; local rows carry Prism's path:line.
+    # Normalised to the local shape so the same renderer and the same `--json`
+    # keys work on either backend, with `hosted` marking which one answered.
+    def hosted_row(row)
+      location = row["url"].to_s.empty? ? row["file_path"].to_s : row["url"].to_s
+      {
+        "gem_name" => row["gem_name"], "gem_version" => row["gem_version"],
+        "source_type" => row["source_type"], "title" => row["title"],
+        "signature" => "", "body" => row["body"], "score" => row["score"],
+        "source_path" => row["file_path"], "source_line" => nil,
+        "url" => row["url"], "matched" => ["hosted"], "hosted" => true
+      }.tap { |out| out["url"] = location if location.empty? }
+    end
+
+    QUERY_TYPES = %w[lex vec hyde].freeze
+
+    # Only a leading `lex:`/`vec:`/`hyde:` is a type. Anything else -- including
+    # a query that happens to start `foo: bar` -- is left alone, because
+    # misreading a question as a directive is worse than ignoring one.
+    def split_type(raw)
+      head, rest = raw.split(/\s+/, 2)
+      return [:hyde, raw] if head.nil? || rest.nil? || !head.end_with?(":")
+
+      name = head[0..-2]
+      QUERY_TYPES.include?(name) ? [name.to_sym, rest] : [:hyde, raw]
+    end
+
+    # A query is embedded with the model's *query* prefix, not the document one.
+    # Returns nil when no model is usable, which the callers treat as "no vectors".
+    def embed_query(query)
+      return nil if Embedder.build.null?
+
+      querier = Embedder::Supervised.new(
+        model_path: Models.path, identity: Models.identity, prefix: Models.prefix(:query)
+      )
+      # embed returns [index, vector] pairs, so a single query is .last.
+      querier.embed([query]).first&.last
+    end
+
+    def emit(results, opts)
+      if opts[:json]
+        @stdout.puts(JSON.pretty_generate(results.map { |row| project(row) }))
+      else
+        results.each_with_index { |row, i| @stdout.puts(format_result(i + 1, row)) }
+        @stdout.puts("no results") if results.empty?
+      end
+      0
+    end
+
+    def cmd_status(argv)
+      opts = {help: false}
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: gemchat status"
+        o.on("-h", "--help") { opts[:help] = true }
+      end
+      parser.parse!(argv)
+      if opts[:help]
+        @stdout.puts(parser)
+        return 0
+      end
+
+      store = Store.new
+      stats = store.stats
+      digest = Lockfile.digest
+      manifest = Manifest.new
+
+      @stdout.puts("gemchat:   #{Gemchat::VERSION}")
+      @stdout.puts("store:     #{store.path}")
+      @stdout.puts("index:     #{stats[:gems]} gems · #{stats[:chunks]} chunks")
+      @stdout.puts("project:   #{Dir.pwd}")
+
+      # The three facts that decide whether the plugin will do anything, so
+      # "why is auto-index not running" is answerable without a debugger.
+      @stdout.puts("lockfile:  #{digest ? digest[0, 12] : "none (run `bundle install`)"}")
+      @stdout.puts("manifest:  #{manifest_state(manifest, digest)}")
+      @stdout.puts("trust:     #{Trust.trusted? ? "granted" : "not granted → `gemchat init` or `gemchat index`"}")
+      @stdout.puts("plugin:    #{plugin_state}")
+      @stdout.puts("vectors:   #{vector_summary(store)}")
+      @stdout.puts("hosted:    #{hosted_state}")
+
+      if (drift = store.drift).any?
+        @stdout.puts("note:      this index was written by a different gemchat " \
+          "(#{drift.join(", ")}); reindex if searches look wrong")
+      end
+      0
+    end
+
+    def vector_summary(store)
+      return "not downloaded (#{Models.megabytes}MB) → gemchat embed" unless Models.installed?
+
+      # No vectors written yet is a distinct state from "vectors written", and
+      # from "downloaded but the index is empty" -- the first asks the user to run
+      # embed, the second has nothing to embed.
+      return "model downloaded, nothing embedded yet → gemchat embed" unless store.meta("embed_model")
+
+      stats = store.embedded_stats
+      summary = "#{store.meta("embed_model")} · #{stats[:embedded]}/#{stats[:total]} chunks"
+      stats[:pending].positive? ? "#{summary} · #{stats[:pending]} pending" : summary
+    end
+
+    # The tier ladder, in one line, naming the action rather than the variable
+    # that gates it (§12.4).
+    def hosted_state
+      host = ENV["GEMCHAT_HOST"].to_s.strip
+      return "#{host} (GEMCHAT_HOST)" unless host.empty?
+      return "configured via GEMCHAT_API_KEY" unless ENV["GEMCHAT_API_KEY"].to_s.strip.empty?
+      return "configured via #{Hosted.credentials_path}" if Hosted.credentials_file
+      return "project default: hosted" if hosted_default?
+
+      "not configured → gemchat.org/settings"
+    end
+
+    # `gemchat init --hosted` records the project's default in the manifest, so a
+    # project that wants the hosted tier does not need a flag on every call.
+    def hosted_default?
+      manifest = Manifest.new
+      manifest.exist? && manifest.hosted?
+    rescue
+      false
+    end
+
+    def manifest_state(manifest, digest)
+      return "none → `gemchat index`" unless manifest.exist?
+      return "stale → `gemchat index`" unless manifest.up_to_date?(digest)
+
+      "up to date"
+    end
+
+    # Answers "is the hook armed?", which the Gemfile cannot. A declared plugin
+    # only becomes active on the next `bundle install`, and the difference is
+    # invisible until you look at Bundler's own index.
+    def plugin_state
+      return "active" if PluginIndex.armed?
+      return "no Gemfile here (run `gemchat init` inside a project)" unless File.file?(Init.new.gemfile_path)
+      return "declared in Gemfile → run `bundle install` to arm" if Init.new.declared?(Init::PLUGIN_LINE)
+
+      "not declared → `gemchat init`"
+    end
+
+    def cmd_version
+      @stdout.puts(Gemchat::VERSION)
+      0
+    end
+
+    def usage
+      @stdout.puts(<<~TEXT)
+        gemchat #{Gemchat::VERSION} — local, offline documentation index for your bundle
+
+        Usage: gemchat <command> [options]
+
+        Commands:
+          init       Set up this project: add gemchat to the Gemfile and trust it
+          index      Index gems from Gemfile.lock (ri is generated locally)
+          reindex    Discard the index and generated ri, then index again
+          search     BM25 full-text search (instant, no models required)
+          embed      Download the model and embed every chunk (the explicit step)
+          vsearch    Vector search over the embedded index
+          query      Hybrid BM25 + vector, fused by reciprocal rank
+          status     Show index state and what is missing
+          version    Print the version
+
+        `query` reads a leading type and routes on it:
+
+          gemchat query "how do I list every task"     both engines, fused (default)
+          gemchat query "lex: Rake::Task#enhance"      BM25 only
+          gemchat query "vec: stop a process on a signal"  vectors only
+
+        `search` works with no model on disk. Everything else needs `gemchat embed`
+        to have run first, and only `embed` ever downloads a model.
+
+        Run `gemchat <command> --help` for command options.
+      TEXT
+      0
+    end
+  end
+end