monq 0.1.0

data/docs/superpowers/plans/2026-10-24-monq.md

@@ -0,0 +1,1384 @@
+# Monq Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build a Pry workbench that loads user-authored Mongoid models from `~/.monq.d` and queries MongoDB the way Arql queries SQL.
+
+**Architecture:** `Cli` parses options, `App` merges YAML and owns environments, `Environment` owns one Mongoid client plus one namespace. Display (`t`/`v`/`vd`) and Pry commands sit on top and never open connections themselves.
+
+**Tech Stack:** Ruby >= 3.2, Mongoid ~> 9, mongo driver, Pry, net-ssh-gateway, terminal-table, rainbow, caxlsx, roo, RSpec.
+
+**Spec:** `docs/superpowers/specs/2026-10-24-monq-design.md`
+
+---
+
+## File map
+
+| File | Responsibility |
+|------|----------------|
+| `lib/monq/errors.rb` | `Monq::Error` exit messages |
+| `lib/monq/config.rb` | YAML load, env selection, CLI merge, client option build |
+| `lib/monq/cli.rb` | OptionParser → OpenStruct |
+| `lib/monq/app.rb` | Singleton, connect, load init.rb, `run!` |
+| `lib/monq/environment.rb` | Client, namespace, models, reconnect, sandbox session |
+| `lib/monq/ssh_proxy.rb` | Local port forward |
+| `lib/monq/presenter.rb` | BSON → printable |
+| `lib/monq/table.rb` `vd.rb` `multi_io.rb` | Tables, visidata, log fan-out |
+| `lib/monq/repl.rb` | Pry prompt |
+| `lib/monq/commands/*.rb` | Pry commands |
+| `lib/monq/ext/*.rb` | Kernel, const_missing, document/criteria/view/array |
+| `exe/monq` | Executable |
+| `spec/` | Unit tests; integration gated by env |
+
+Working directory for every command: `/Users/liuxiang/cascode/github.com/monq`.
+
+---
+
+### Task 1: Gem skeleton and error class
+
+**Files:**
+- Modify: `monq.gemspec`
+- Modify: `lib/monq.rb`
+- Create: `lib/monq/errors.rb`
+- Create: `exe/monq`
+- Modify: `spec/monq_spec.rb`
+
+- [ ] **Step 1: Write the failing test**
+
+Replace `spec/monq_spec.rb` with:
+
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe Monq do
+  it "has a version" do
+    expect(Monq::VERSION).to match(/\A\d+\.\d+\.\d+\z/)
+  end
+
+  it "defines Error" do
+    expect(Monq::Error.new("nope").message).to eq("nope")
+  end
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/monq_spec.rb`
+Expected: FAIL, `uninitialized constant Monq::Error`
+
+- [ ] **Step 3: Implement**
+
+`lib/monq/errors.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+module Monq
+  class Error < StandardError; end
+end
+```
+
+`lib/monq.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require_relative "monq/version"
+require_relative "monq/errors"
+
+module Monq
+end
+```
+
+`exe/monq`:
+
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "monq"
+
+Monq::Cli.start
+```
+
+`chmod +x exe/monq`.
+
+In `monq.gemspec`, replace the TODO summary/description:
+
+```ruby
+spec.summary = "Mongoid + Pry MongoDB query workbench"
+spec.description = "Load user-authored Mongoid models and query MongoDB from a Pry REPL."
+spec.metadata["allowed_push_host"] = "https://rubygems.org"
+```
+
+Add runtime deps:
+
+```ruby
+spec.add_dependency "mongoid", "~> 9.0"
+spec.add_dependency "pry", "~> 0.15"
+spec.add_dependency "pry-byebug", "~> 3.10"
+spec.add_dependency "net-ssh-gateway", "~> 2.0"
+spec.add_dependency "terminal-table", "~> 4.0"
+spec.add_dependency "rainbow", "~> 3.1"
+spec.add_dependency "caxlsx", "~> 4.1"
+spec.add_dependency "roo", "~> 2.10"
+```
+
+Run `bundle install`.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/monq_spec.rb`
+Expected: 2 examples, 0 failures
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add monq.gemspec Gemfile.lock lib/monq.rb lib/monq/errors.rb exe/monq spec/monq_spec.rb
+git commit -m "feat: add monq executable skeleton and Error"
+```
+
+---
+
+### Task 2: Config — select environments
+
+**Files:**
+- Create: `lib/monq/config.rb`
+- Create: `spec/config_spec.rb`
+
+- [ ] **Step 1: Write the failing test**
+
+```ruby
+# frozen_string_literal: true
+
+require "ostruct"
+
+RSpec.describe Monq::Config do
+  let(:yaml) do
+    {
+      "default" => { "auth_source" => "admin" },
+      "blog.dev" => { "uri" => "mongodb://h/db", "database" => "blog_dev", "namespace" => "Blog" },
+      "ops.prod" => { "host" => "ops.example.com", "database" => "ops" }
+    }
+  end
+
+  it "rejects reserved environment names" do
+    expect { described_class.select_environments(yaml, ["default"], OpenStruct.new) }
+      .to raise_error(Monq::Error, /reserved/i)
+  end
+
+  it "fails when an -e name is missing" do
+    expect { described_class.select_environments(yaml, ["nope"], OpenStruct.new) }
+      .to raise_error(Monq::Error, /nope/)
+  end
+
+  it "does not treat the YAML default anchor as an environment when -e is absent" do
+    expect { described_class.select_environments(yaml, nil, OpenStruct.new) }
+      .to raise_error(Monq::Error, /-e/)
+  end
+
+  it "slices only requested environments" do
+    envs = described_class.select_environments(yaml, ["blog.dev"], OpenStruct.new)
+    expect(envs.keys).to eq(["blog.dev"])
+  end
+
+  it "builds a synthetic default from CLI when -e is absent but uri is present" do
+    opts = OpenStruct.new(uri: "mongodb://h/x", database: "x")
+    envs = described_class.select_environments({}, nil, opts)
+    expect(envs.keys).to eq(["default"])
+    expect(envs["default"][:uri]).to eq("mongodb://h/x")
+  end
+
+  it "rejects two environments that share a namespace" do
+    yaml["ops.prod"]["namespace"] = "Blog"
+    expect { described_class.select_environments(yaml, ["blog.dev", "ops.prod"], OpenStruct.new) }
+      .to raise_error(Monq::Error, /namespace/i)
+  end
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/config_spec.rb`
+Expected: FAIL, `uninitialized constant Monq::Config`
+
+- [ ] **Step 3: Implement**
+
+`lib/monq/config.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require "yaml"
+require "ostruct"
+
+module Monq
+  module Config
+    RESERVED = %w[default arql].freeze
+
+    module_function
+
+    def load_file(path)
+      raw = YAML.safe_load(File.read(path), aliases: true)
+      (raw || {}).transform_keys(&:to_s)
+    rescue ArgumentError
+      raw = YAML.safe_load(File.read(path))
+      (raw || {}).transform_keys(&:to_s)
+    end
+
+    def select_environments(yaml, names, options)
+      yaml = stringify(yaml)
+      if names.nil? || names.empty?
+        return { "default" => cli_env(options) } if sufficient_cli?(options)
+
+        raise Error, "No -e given and CLI has no connection. Pass -e or --uri, or create ~/.monq.d/init.yml"
+      end
+
+      names.each do |name|
+        raise Error, "#{name} is a reserved environment name" if RESERVED.include?(name)
+        raise Error, "Environment #{name} not in config. Known: #{known(yaml).join(', ')}" unless yaml.key?(name)
+      end
+
+      selected = names.to_h { |n| [n, deep_sym(yaml[n])] }
+      apply_cli!(selected, options)
+      assign_namespaces!(selected)
+      assert_unique_namespaces!(selected)
+      selected
+    end
+
+    def known(yaml)
+      yaml.keys - RESERVED
+    end
+
+    def sufficient_cli?(options)
+      options.uri.to_s != "" || (options.host.to_s != "" && options.database.to_s != "")
+    end
+
+    def cli_env(options)
+      {
+        uri: options.uri,
+        host: options.host,
+        port: options.port,
+        database: options.database,
+        username: options.username,
+        password: options.password,
+        auth_source: options.auth_source
+      }.compact
+    end
+
+    def apply_cli!(selected, options)
+      overrides = connection_overrides(options)
+      if selected.size > 1 && overrides.any?
+        raise Error, "Connection CLI flags are not allowed with multiple -e environments"
+      end
+      return if selected.size != 1
+
+      env = selected.values.first
+      overrides.each { |k, v| env[k] = v }
+      merge_ssh!(env, options)
+    end
+
+    def connection_overrides(options)
+      {
+        uri: options.uri,
+        host: options.host,
+        port: options.port,
+        database: options.database,
+        username: options.username,
+        password: options.password,
+        auth_source: options.auth_source
+      }.compact.reject { |_, v| v.respond_to?(:empty?) && v.empty? }
+    end
+
+    def merge_ssh!(env, options)
+      return if options.ssh.nil? || options.ssh.empty?
+
+      env[:ssh] = (env[:ssh] || {}).merge(options.ssh.transform_keys(&:to_sym))
+    end
+
+    def assign_namespaces!(selected)
+      selected.each do |name, env|
+        env[:namespace] ||= camelize(name)
+      end
+    end
+
+    def assert_unique_namespaces!(selected)
+      groups = selected.group_by { |_, env| env[:namespace] }
+      dup = groups.find { |_, pairs| pairs.size > 1 }
+      return unless dup
+
+      raise Error, "Environments share namespace #{dup.first}: #{dup.last.map(&:first).join(', ')}"
+    end
+
+    def camelize(name)
+      name.split(/[^A-Za-z0-9]+/).reject(&:empty?).map { |p| p[0].upcase + p[1..] }.join
+    end
+
+    def stringify(hash)
+      hash.to_h.transform_keys(&:to_s).transform_values { |v| v.is_a?(Hash) ? stringify(v) : v }
+    end
+
+    def deep_sym(obj)
+      case obj
+      when Hash then obj.to_h { |k, v| [k.to_sym, deep_sym(v)] }
+      else obj
+      end
+    end
+
+    def prefix_for(env_name)
+      env_name.split(/[._-]/, 2).first
+    end
+
+    def client_name_for(env_name)
+      env_name.gsub(/[^A-Za-z0-9]/, "_").to_sym
+    end
+  end
+end
+```
+
+`require_relative "monq/config"` in `lib/monq.rb`.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/config_spec.rb`
+Expected: 6 examples, 0 failures
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/monq.rb lib/monq/config.rb spec/config_spec.rb
+git commit -m "feat: select monq environments from YAML and CLI"
+```
+
+---
+
+### Task 3: Config — client options, URI mask, SSH rewrite
+
+**Files:**
+- Modify: `lib/monq/config.rb`
+- Modify: `spec/config_spec.rb`
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `spec/config_spec.rb`:
+
+```ruby
+RSpec.describe Monq::Config do
+  describe ".client_options" do
+    it "prefers uri and lets database override the URI path" do
+      opts = described_class.client_options(uri: "mongodb://u:p@db.example.com:27017/other?authSource=admin", database: "blog_dev")
+      expect(opts[:database]).to eq("blog_dev")
+      expect(opts[:hosts]).to eq(["db.example.com:27017"])
+    end
+
+    it "requires database when the URI has no path" do
+      expect { described_class.client_options(uri: "mongodb://db.example.com:27017/?authSource=admin") }
+        .to raise_error(Monq::Error, /database/)
+    end
+
+    it "builds hosts from split fields when uri is absent" do
+      opts = described_class.client_options(host: "mongo.example.com", database: "x")
+      expect(opts[:hosts]).to eq(["mongo.example.com:27017"])
+      expect(opts[:database]).to eq("x")
+    end
+
+    it "rewrites ssh to one direct seed and drops replica_set" do
+      opts = described_class.client_options(
+        uri: "mongodb://u:p@db.example.com:27017,db2.example.com:27017/blog_dev?replicaSet=rs0",
+        ssh: { local_host: "127.0.0.1", local_port: 27018 }
+      )
+      expect(opts[:hosts]).to eq(["127.0.0.1:27018"])
+      expect(opts[:options][:direct_connection]).to eq(true)
+      expect(opts[:options]).not_to have_key(:replica_set)
+    end
+
+    it "rejects mongodb+srv together with ssh" do
+      expect {
+        described_class.client_options(uri: "mongodb+srv://u:p@cluster.example/?authSource=admin", database: "x", ssh: { local_port: 1 })
+      }.to raise_error(Monq::Error, /srv/i)
+    end
+  end
+
+  describe ".mask_uri" do
+    it "masks the password" do
+      expect(described_class.mask_uri("mongodb://admin:secret@db.example.com:27017/db"))
+        .to eq("mongodb://admin:***@db.example.com:27017/db")
+    end
+  end
+
+  it "maps env name to prefix and client name" do
+    expect(described_class.prefix_for("blog.dev")).to eq("blog")
+    expect(described_class.client_name_for("blog.dev")).to eq(:blog_dev)
+    expect(described_class.camelize("blog.dev")).to eq("BlogDev")
+  end
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/config_spec.rb`
+Expected: FAIL, `client_options` missing
+
+- [ ] **Step 3: Implement**
+
+Add to `Monq::Config` (still `module_function`):
+
+```ruby
+def client_options(env)
+  env = deep_sym(env)
+  ssh = env[:ssh]
+  if ssh && env[:uri].to_s.start_with?("mongodb+srv:")
+    raise Error, "mongodb+srv with ssh is not supported; use a direct host"
+  end
+
+  built = env[:uri].to_s != "" ? from_uri(env) : from_fields(env)
+  return built unless ssh && ssh[:local_port]
+
+  {
+    hosts: ["127.0.0.1:#{ssh[:local_port]}"],
+    database: built[:database],
+    options: built[:options].merge(direct_connection: true).except(:replica_set, :connect)
+  }
+end
+
+def from_uri(env)
+  require "mongo"
+  parsed = Mongo::URI.get(env[:uri])
+  database = env[:database].to_s
+  database = parsed.database if database.empty?
+  raise Error, "database is required (URI path is empty)" if database.nil? || database.empty?
+
+  options = parsed.uri_options.dup
+  options.delete(:replica_set) if env[:ssh] && env[:ssh][:local_port]
+  {
+    hosts: parsed.servers,
+    database: database,
+    options: options
+  }
+end
+
+def from_fields(env)
+  raise Error, "host and database are required" if env[:host].to_s.empty? || env[:database].to_s.empty?
+
+  port = env[:port] || 27017
+  options = {}
+  options[:user] = env[:username] if env[:username]
+  options[:password] = env[:password] if env[:password]
+  options[:auth_source] = env[:auth_source] if env[:auth_source]
+  options[:replica_set] = env[:replica_set] if env[:replica_set] && !(env[:ssh] && env[:ssh][:local_port])
+  options[:ssl] = env[:ssl] unless env[:ssl].nil?
+  { hosts: ["#{env[:host]}:#{port}"], database: env[:database], options: options }
+end
+
+def mask_uri(uri)
+  uri.to_s.sub(%r{://([^:/@]+):[^@]+@}, '://\1:***@')
+end
+
+def ssh_forward_target(env)
+  env = deep_sym(env)
+  if env[:uri].to_s != ""
+    require "mongo"
+    host, port = Mongo::URI.get(env[:uri]).servers.first.split(":")
+    { host: host, port: (port || 27017).to_i }
+  else
+    { host: env[:host], port: (env[:port] || 27017).to_i }
+  end
+end
+```
+
+If `Mongo::URI.get` does not exist in the installed driver, use `Mongo::URI.new(env[:uri])` and read `#servers` / `#database` / `#options` — adjust the three method names to whatever `bundle exec ruby -rmongo -e 'p Mongo::URI.instance_methods(false)'` prints, keeping the spec expectations above.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/config_spec.rb`
+Expected: all examples pass
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/monq/config.rb spec/config_spec.rb
+git commit -m "feat: build Mongo client options and mask URIs"
+```
+
+---
+
+### Task 4: Environment connects a named client without models
+
+**Files:**
+- Create: `lib/monq/environment.rb`
+- Create: `spec/environment_spec.rb`
+
+Use a fake client so unit tests do not dial the network.
+
+- [ ] **Step 1: Write the failing test**
+
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe Monq::Environment do
+  let(:hello_doc) { { "ok" => 1, "setName" => "rs0" } }
+  let(:fake_client) do
+    db = double("db", command: double(documents: [hello_doc]), collection_names: ["users"])
+    instance_double("Mongo::Client", database: db, close: nil)
+  end
+
+  before do
+    allow(Mongo::Client).to receive(:new).and_return(fake_client)
+    allow(Mongoid::Clients).to receive(:set)
+  end
+
+  it "registers the named client and maps the first env to :default" do
+    env = described_class.new("blog.dev", { uri: "mongodb://h/blog_dev", database: "blog_dev", namespace: "Blog" }, first: true, model_dir: "/tmp")
+    env.connect!
+    expect(Mongoid::Clients).to have_received(:set).with(:blog_dev, fake_client)
+    expect(Mongoid::Clients).to have_received(:set).with(:default, fake_client)
+    expect(env.namespace).to eq("Blog")
+    expect(env.ping?).to eq(true)
+  end
+
+  it "does not map later environments onto :default" do
+    env = described_class.new("ops.prod", { host: "h", database: "ops", namespace: "Ops" }, first: false, model_dir: "/tmp")
+    env.connect!
+    expect(Mongoid::Clients).to have_received(:set).with(:ops_prod, fake_client)
+    expect(Mongoid::Clients).not_to have_received(:set).with(:default, fake_client)
+  end
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/environment_spec.rb`
+Expected: FAIL, `uninitialized constant Monq::Environment`
+
+- [ ] **Step 3: Implement**
+
+`lib/monq/environment.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require "mongoid"
+
+module Monq
+  class Environment
+    attr_reader :name, :config, :client_name, :namespace, :client, :ssh_proxy
+
+    def initialize(name, config, first:, model_dir:)
+      @name = name
+      @config = config
+      @first = first
+      @model_dir = model_dir
+      @client_name = Config.client_name_for(name)
+      @namespace = config[:namespace]
+      @models = []
+      @sandbox_session = nil
+    end
+
+    def connect!
+      opts = Config.client_options(config)
+      @client = Mongo::Client.new(opts[:hosts], **opts[:options].merge(database: opts[:database]))
+      Mongoid::Clients.set(client_name, @client)
+      Mongoid::Clients.set(:default, @client) if @first
+      hello!
+    end
+
+    def hello!
+      @client.database.command(hello: 1).documents.first
+    end
+
+    def ping?
+      hello!
+      true
+    rescue StandardError
+      false
+    end
+
+    def reconnect!
+      raise Error, "sandbox is active; run sandbox-quit first" if sandbox?
+
+      @client&.close
+      connect!
+    end
+
+    def namespace_module
+      @namespace_module ||= Object.const_set(namespace, Module.new)
+    end
+
+    def sandbox?
+      !@sandbox_session.nil?
+    end
+  end
+end
+```
+
+`require_relative "monq/environment"` in `lib/monq.rb`.
+
+If `Mongoid::Clients.set` is not public in the installed version, check `Mongoid::Clients.methods` and use the method that stores a client under a symbol (often `set` or `clients[name] =`). Keep the spec's `have_received(:set)` by wrapping whatever the gem actually exposes in `Environment#register_client`.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/environment_spec.rb`
+Expected: 2 examples, 0 failures
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/monq.rb lib/monq/environment.rb spec/environment_spec.rb
+git commit -m "feat: connect a named Mongoid client per environment"
+```
+
+---
+
+### Task 5: Load models into the namespace and bind clients
+
+**Files:**
+- Modify: `lib/monq/environment.rb`
+- Modify: `spec/environment_spec.rb`
+
+- [ ] **Step 1: Write the failing test**
+
+```ruby
+RSpec.describe Monq::Environment do
+  it "loads prefix file into the namespace and rebinds :default client" do
+    dir = Dir.mktmpdir
+    File.write(File.join(dir, "blog.rb"), <<~RUBY)
+      class User
+        include Mongoid::Document
+        store_in collection: "users"
+        embeds_one :meta, class_name: "UserMeta"
+      end
+      class UserMeta
+        include Mongoid::Document
+        embedded_in :user
+        field :status, type: String
+      end
+    RUBY
+
+    env = described_class.new("blog.dev", { host: "h", database: "d", namespace: "Blog" }, first: true, model_dir: dir)
+    allow(env).to receive(:connect!)
+    env.load_models!
+    expect(Blog::User.storage_options[:client]).to eq(:blog_dev)
+    expect(Blog::User.storage_options[:collection]).to eq("users")
+    expect(Blog::UserMeta).to be_embedded
+    expect(Blog.const_defined?(:U)).to eq(true)
+  ensure
+    Object.send(:remove_const, :Blog) if Object.const_defined?(:Blog)
+    FileUtils.remove_entry(dir) if dir
+  end
+
+  it "warns and continues when the prefix file is missing" do
+    env = described_class.new("blog.dev", { host: "h", database: "d", namespace: "BlogX" }, first: true, model_dir: Dir.mktmpdir)
+    expect { env.load_models! }.to output(/blog\.rb/).to_stderr
+    expect(env.models).to eq([])
+  ensure
+    Object.send(:remove_const, :BlogX) if Object.const_defined?(:BlogX)
+  end
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/environment_spec.rb`
+Expected: FAIL, `load_models!` missing
+
+- [ ] **Step 3: Implement**
+
+Add to `Environment`:
+
+```ruby
+def load_models!
+  install_namespace_api!
+  path = File.join(@model_dir, "#{Config.prefix_for(name)}.rb")
+  unless File.file?(path)
+    warn "model file not found: #{path}"
+    return
+  end
+  namespace_module.module_eval(File.read(path), path)
+  bind_clients!
+  install_abbreviations!
+end
+
+def models
+  namespace_module.constants.filter_map do |const_name|
+    klass = namespace_module.const_get(const_name)
+    klass if klass.is_a?(Class) && klass < Mongoid::Document && !klass.embedded?
+  end
+end
+
+def redefine!
+  raise Error, "sandbox is active; run sandbox-quit first" if sandbox?
+
+  tracked_classes.each do |klass|
+    Mongoid.models.delete(klass) if Mongoid.models.respond_to?(:delete)
+  end
+  tracked_names.each { |n| namespace_module.send(:remove_const, n) if namespace_module.const_defined?(n, false) }
+  @tracked = []
+  load_models!
+end
+
+def tracked_names
+  @tracked ||= []
+end
+
+def tracked_classes
+  tracked_names.filter_map do |n|
+    namespace_module.const_get(n) if namespace_module.const_defined?(n, false)
+  end.select { |k| k.is_a?(Class) }
+end
+
+def bind_clients!
+  namespace_module.constants.each do |const_name|
+    klass = namespace_module.const_get(const_name)
+    next unless klass.is_a?(Class) && klass < Mongoid::Document
+    next if klass.embedded?
+
+    current = klass.storage_options[:client]
+    next if current && current.to_sym != :default
+
+    klass.store_in klass.storage_options.merge(client: client_name)
+    tracked_names << const_name
+  end
+end
+
+def install_abbreviations!
+  models.each do |klass|
+    abbr = klass.name.split("::").last.gsub(/[^A-Z]/, "")
+    abbr = "M" if abbr.empty?
+    candidate = abbr
+    n = 2
+    while namespace_module.const_defined?(candidate, false)
+      candidate = "#{abbr}#{n}"
+      n += 1
+    end
+    namespace_module.const_set(candidate, klass)
+    tracked_names << candidate.to_sym
+  end
+end
+
+def install_namespace_api!
+  env = self
+  mod = namespace_module
+  mod.define_singleton_method(:client) { env.client }
+  mod.define_singleton_method(:models) { env.models }
+  mod.define_singleton_method(:collections) { env.client.database.collection_names }
+  mod.define_singleton_method(:config) { env.config }
+  mod.define_singleton_method(:q) { |doc| env.client.database.command(doc) }
+end
+```
+
+`redefine!` must also record embedded classes created in the file so they are removed from `Mongoid.models`. After `module_eval`, walk `models` and each `embedded_relations` target class and push those class names into `tracked_names`.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/environment_spec.rb`
+Expected: pass, including `Blog::User.storage_options[:collection] == "users"`
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/monq/environment.rb spec/environment_spec.rb
+git commit -m "feat: load namespace models and bind Mongoid clients"
+```
+
+---
+
+### Task 6: CLI and App runner
+
+**Files:**
+- Create: `lib/monq/cli.rb`
+- Create: `lib/monq/app.rb`
+- Create: `spec/app_spec.rb`
+
+- [ ] **Step 1: Write the failing test**
+
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe Monq::Cli do
+  it "parses multiple environments" do
+    opts = described_class.parse!(%w[-e blog.dev,ops.prod])
+    expect(opts.environments).to eq(%w[blog.dev ops.prod])
+  end
+
+  it "rejects connection flags with multiple environments" do
+    expect { described_class.parse!(%w[-e a,b --uri mongodb://h/db]) }
+      .to raise_error(Monq::Error, /multiple/i)
+  end
+end
+
+RSpec.describe Monq::App do
+  it "evals -E and does not start pry" do
+    yaml = Tempfile.new(["monq", ".yml"])
+    yaml.write("blog.dev:\n  host: h\n  database: d\n  namespace: BlogApp\n")
+    yaml.close
+    app = described_class.new(OpenStruct.new(config_file: yaml.path, environments: ["blog.dev"], code: "MONQ_RAN = 1"))
+    allow_any_instance_of(Monq::Environment).to receive(:connect!)
+    expect(Pry).not_to receive(:start) if defined?(Pry)
+    app.run!
+    expect(MONQ_RAN).to eq(1)
+  ensure
+    yaml&.unlink
+  end
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/app_spec.rb`
+Expected: FAIL, `Monq::Cli` missing
+
+- [ ] **Step 3: Implement**
+
+`lib/monq/cli.rb` uses `OptionParser` for the flags in spec section 4.1. `parse!` returns an `OpenStruct`. `start` calls `App.new(parse!(ARGV)).run!`. Multiple `-e` plus any connection flag raises `Monq::Error`.
+
+`lib/monq/app.rb`:
+
+```ruby
+module Monq
+  class App
+    attr_reader :environments, :options
+
+    class << self
+      attr_accessor :instance
+    end
+
+    def initialize(options)
+      @options = options
+      self.class.instance = self
+      @environments = build_environments
+    end
+
+    def run!
+      @environments.each(&:connect!)
+      load_initializer!
+      @environments.each(&:load_models!)
+      if @options.code && !@options.code.empty?
+        eval(@options.code, TOPLEVEL_BINDING, "-e")
+      elsif @options.args&.first
+        load(@options.args.first)
+      elsif !$stdin.isatty
+        eval($stdin.read, TOPLEVEL_BINDING, "stdin")
+      else
+        require "monq/repl"
+        Repl.new.start
+      end
+    end
+  end
+end
+```
+
+`build_environments` resolves the config file (explicit `-c` missing → raise; no file and no CLI connection → raise), calls `Config.select_environments`, and maps each to `Environment.new(..., first: index.zero?, model_dir: File.expand_path("~/.monq.d"))`.
+
+`load_initializer!`: if `-i` set and missing, raise; if default path missing, return; else `load` once.
+
+`require_relative` both files from `lib/monq.rb`. `exe/monq` already calls `Monq::Cli.start`.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/app_spec.rb spec/config_spec.rb`
+Expected: pass
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/monq.rb lib/monq/cli.rb lib/monq/app.rb spec/app_spec.rb
+git commit -m "feat: add CLI and App runner"
+```
+
+---
+
+### Task 7: Presenter and Table
+
+**Files:**
+- Create: `lib/monq/presenter.rb`
+- Create: `lib/monq/table.rb`
+- Create: `spec/presenter_spec.rb`
+
+- [ ] **Step 1: Write the failing test**
+
+```ruby
+# frozen_string_literal: true
+
+require "bson"
+
+RSpec.describe Monq::Presenter do
+  it "stringifies ObjectId" do
+    id = BSON::ObjectId.new
+    expect(described_class.scalar(id)).to eq(id.to_s)
+  end
+
+  it "truncates long hashes" do
+    text = described_class.scalar({ "a" => "x" * 200 })
+    expect(text.length).to be <= 121
+    expect(text).to end_with("…")
+  end
+
+  it "builds rows from the first document's keys" do
+    rows = described_class.rows([{ "a" => 1, "b" => 2 }, { "a" => 3, "c" => 9 }])
+    expect(rows.first).to eq(%w[a b])
+    expect(rows.last).to eq([3, nil])
+  end
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/presenter_spec.rb`
+Expected: FAIL
+
+- [ ] **Step 3: Implement**
+
+`Presenter.scalar` follows spec 6.2 (ObjectId, Time, Binary, Decimal128, Hash/Array truncated at 120). `Presenter.rows(docs)` uses `docs.first.keys`, missing keys become `nil`.
+
+`Table` wraps `Terminal::Table` and supports `:terminal`, `:md`, `:org` the same way Arql's `lib/arql/table.rb` does (copy the style branches, do not require arql).
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/presenter_spec.rb`
+Expected: pass
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/monq/presenter.rb lib/monq/table.rb spec/presenter_spec.rb lib/monq.rb
+git commit -m "feat: present BSON values as tables"
+```
+
+---
+
+### Task 8: t/v/vd on documents, criteria, views, arrays
+
+**Files:**
+- Create: `lib/monq/ext/document.rb`
+- Create: `lib/monq/ext/criteria.rb`
+- Create: `lib/monq/ext/view.rb`
+- Create: `lib/monq/ext/array.rb`
+- Create: `spec/display_spec.rb`
+
+- [ ] **Step 1: Write the failing test**
+
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe "display" do
+  it "caps an unlimited criteria at 500 and reports it" do
+    criteria = double("criteria", options: {})
+    allow(criteria).to receive(:limit).with(500).and_return(criteria)
+    docs = [{ "_id" => "a", "name" => "n" }]
+    allow(criteria).to receive(:to_a).and_return(docs)
+    expect { Monq::Ext.display_criteria(criteria) }.to output(/capped at 500/).to_stdout
+  end
+
+  it "does not cap when the caller set limit" do
+    criteria = double("criteria", options: { limit: 2 })
+    expect(criteria).not_to receive(:limit)
+    allow(criteria).to receive(:to_a).and_return([{ "_id" => "a" }])
+    expect { Monq::Ext.display_criteria(criteria) }.not_to output(/capped/).to_stdout
+  end
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/display_spec.rb`
+Expected: FAIL
+
+- [ ] **Step 3: Implement**
+
+`Monq::Ext.display_criteria(criteria)`:
+
+- if `criteria.options[:limit].nil?`, `criteria = criteria.limit(500)` and set `capped = true`
+- print `Table` of `Presenter.rows(criteria.to_a)`
+- print `showing N rows (capped at 500)` only when capped
+
+`v` returns `[keys, nil, *rows]` and does not print the cap line. `t` and `vd` print it.
+
+Include the module into `Mongoid::Document`, `Mongoid::Criteria`, and `Mongo::Collection::View` (`view.rb` calls `to_a` then array `t`). Array `t` uses `Presenter.rows` when elements are Hash-like.
+
+Do **not** define `Fund.t` as a class method.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/display_spec.rb spec/presenter_spec.rb`
+Expected: pass
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/monq/ext spec/display_spec.rb lib/monq.rb
+git commit -m "feat: add t/v display with a 500-row cap"
+```
+
+---
+
+### Task 9: const_missing and Kernel helpers
+
+**Files:**
+- Create: `lib/monq/ext/object.rb`
+- Create: `lib/monq/ext/kernel.rb`
+- Create: `spec/const_missing_spec.rb`
+
+- [ ] **Step 1: Write the failing test**
+
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe "const_missing" do
+  it "resolves the first environment that defines the constant" do
+    a = Module.new
+    b = Module.new
+    stub_const("Alpha", Class.new)
+    a.const_set(:Alpha, Alpha)
+    app = instance_double(Monq::App, environments: [
+      instance_double(Monq::Environment, namespace_module: a),
+      instance_double(Monq::Environment, namespace_module: b)
+    ])
+    allow(Monq::App).to receive(:instance).and_return(app)
+    expect(Object.const_missing(:Alpha)).to eq(Alpha)
+  end
+end
+```
+
+Adjust if `Object.const_missing` cannot be called directly because the constant exists — remove it first or use a name that is not defined, e.g. `FundProbe`.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/const_missing_spec.rb`
+Expected: FAIL or `NameError` from `super`
+
+- [ ] **Step 3: Implement**
+
+`object.rb` prepends/overrides `Object.const_missing` exactly as Arql does, walking `Monq::App.instance.environments`. `kernel.rb` defines `models`, `model_names`, `within_namespace`, `within_env`, `env_config`, and `q` (single environment only; otherwise stderr + nil).
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/const_missing_spec.rb`
+Expected: pass
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/monq/ext/object.rb lib/monq/ext/kernel.rb spec/const_missing_spec.rb lib/monq.rb
+git commit -m "feat: alias top-level model constants across environments"
+```
+
+---
+
+### Task 10: Pry commands info, m, show-sql, reconnect, redefine
+
+**Files:**
+- Create: `lib/monq/repl.rb`
+- Create: `lib/monq/multi_io.rb`
+- Create: `lib/monq/commands/info.rb`
+- Create: `lib/monq/commands/models.rb`
+- Create: `lib/monq/commands/show_sql.rb`
+- Create: `lib/monq/commands/reconnect.rb`
+- Create: `lib/monq/commands/redefine.rb`
+- Create: `spec/commands_spec.rb`
+
+- [ ] **Step 1: Write the failing test**
+
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe Monq::Commands::Info do
+  it "masks passwords" do
+    env = instance_double(
+      Monq::Environment,
+      name: "blog.dev",
+      config: { uri: "mongodb://admin:secret@db.example.com:27017/blog_dev", database: "blog_dev" },
+      client_name: :blog_dev,
+      ping?: true,
+      ssh_proxy: nil
+    )
+    text = described_class.render([env], /blog/)
+    expect(text).to include("admin:***@")
+    expect(text).not_to include("secret")
+    expect(text).to include("blog_dev")
+  end
+end
+
+RSpec.describe Monq::Commands::Redefine do
+  it "refuses while sandbox is active" do
+    env = instance_double(Monq::Environment, sandbox?: true)
+    expect { described_class.run([env]) }.to raise_error(Monq::Error, /sandbox/)
+    expect(env).not_to receive(:redefine!)
+  end
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/commands_spec.rb`
+Expected: FAIL
+
+- [ ] **Step 3: Implement**
+
+Command modules expose pure methods (`render`, `run`) that Pry command blocks call. `Info.render` uses `Config.mask_uri`. `Models.render` lists `env.models` with collection, class name, abbreviation. `ShowSql` subscribes `Mongo::Monitoring::COMMAND` and writes JSON to `App.log_io` (`MultiIO`). `Reconnect.run` calls `ping?` then `reconnect!` unless `sandbox?`. `Redefine.run` raises `Monq::Error` when any env `sandbox?`, else `redefine!`.
+
+`Repl#start` sets the prompt `MONQ@<names>` and calls `Pry.start` unless `options.babel_compatable`.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/commands_spec.rb`
+Expected: pass
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/monq/repl.rb lib/monq/multi_io.rb lib/monq/commands spec/commands_spec.rb lib/monq.rb
+git commit -m "feat: add info, models, show-sql, reconnect, and redefine commands"
+```
+
+---
+
+### Task 11: SSH proxy
+
+**Files:**
+- Create: `lib/monq/ssh_proxy.rb`
+- Modify: `lib/monq/environment.rb`
+- Create: `spec/ssh_proxy_spec.rb`
+
+- [ ] **Step 1: Write the failing test**
+
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe Monq::SSHProxy do
+  it "returns the local host and port" do
+    gateway = instance_double(Net::SSH::Gateway, open: 27018, shutdown!: nil, active?: true)
+    allow(Net::SSH::Gateway).to receive(:new).and_return(gateway)
+    proxy = described_class.new(host: "jump", user: "deploy", port: 22, forward_host: "db.example.com", forward_port: 27017, local_port: 27018)
+    expect(proxy.database_host_port).to eq(host: "127.0.0.1", port: 27018)
+  end
+
+  it "reconnects only when inactive" do
+    gateway = instance_double(Net::SSH::Gateway, open: 27018, shutdown!: nil, active?: true)
+    allow(Net::SSH::Gateway).to receive(:new).and_return(gateway)
+    proxy = described_class.new(host: "jump", user: "deploy", forward_host: "db.example.com", forward_port: 27017)
+    expect(proxy).not_to receive(:reconnect!)
+    proxy.reconnect
+  end
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/ssh_proxy_spec.rb`
+Expected: FAIL
+
+- [ ] **Step 3: Implement**
+
+`SSHProxy#initialize` calls `Net::SSH::Gateway.new` and `open`. Password is optional. `reconnect` calls `reconnect!` only when `!active?`. `reconnect!` shuts down and opens the **same** local port.
+
+`Environment#connect!` if `config[:ssh]`: build proxy from `Config.ssh_forward_target`, put `{ local_host:, local_port: }` into the hash passed to `Config.client_options` so Task 3's rewrite runs. `reconnect!` calls `ssh_proxy.reconnect!` before rebuilding the client.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/ssh_proxy_spec.rb spec/config_spec.rb`
+Expected: pass
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/monq/ssh_proxy.rb lib/monq/environment.rb spec/ssh_proxy_spec.rb
+git commit -m "feat: tunnel Mongo connections over SSH"
+```
+
+---
+
+### Task 12: Sandbox
+
+**Files:**
+- Create: `lib/monq/commands/sandbox.rb`
+- Modify: `lib/monq/environment.rb`
+- Create: `spec/sandbox_spec.rb`
+
+- [ ] **Step 1: Write the failing test**
+
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe Monq::Commands::Sandbox do
+  def env(hello)
+    client = double("client")
+    db = double("db")
+    allow(client).to receive(:database).and_return(db)
+    allow(db).to receive(:command).with(hello: 1).and_return(double(documents: [hello]))
+    session = double("session", start_transaction: nil, abort_transaction: nil, end_session: nil)
+    allow(client).to receive(:start_session).and_return(session)
+    instance_double(Monq::Environment, client: client, name: "blog.dev", sandbox?: false).tap do |e|
+      allow(e).to receive(:bind_session)
+      allow(e).to receive(:clear_session)
+    end
+  end
+
+  it "does not start a session when any environment is standalone" do
+    good = env("ok" => 1, "setName" => "rs0")
+    bad = env("ok" => 1)
+    expect(good.client).not_to receive(:start_session)
+    expect { described_class.enter([good, bad]) }.to raise_error(Monq::Error, /replica set|mongos/i)
+  end
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/sandbox_spec.rb`
+Expected: FAIL
+
+- [ ] **Step 3: Implement**
+
+`Sandbox.enter(envs)`:
+
+1. Collect `hello` for every env. If any lacks `setName` and `msg != "isdbgrid"`, raise `Monq::Error` and return **before** `start_session`.
+2. For each env, `start_session` + `start_transaction` + `bind_session`. On failure, `abort_transaction` + `end_session` the earlier ones and raise.
+
+`Environment#bind_session(session)` stores the session on **that** client (client instance variable or a wrapper). Do not call `Mongoid::Threaded.set_session`.
+
+`Sandbox.quit` aborts every session. `enter` when already active prints and returns.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/sandbox_spec.rb spec/commands_spec.rb`
+Expected: pass
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/monq/commands/sandbox.rb lib/monq/environment.rb spec/sandbox_spec.rb
+git commit -m "feat: add all-or-nothing Mongo sandbox transactions"
+```
+
+---
+
+### Task 13: CSV and Excel export
+
+**Files:**
+- Modify: `lib/monq/ext/array.rb`
+- Modify: `lib/monq/ext/document.rb`
+- Modify: `lib/monq/ext/criteria.rb`
+- Create: `spec/export_spec.rb`
+
+- [ ] **Step 1: Write the failing test**
+
+```ruby
+# frozen_string_literal: true
+
+require "csv"
+
+RSpec.describe Array do
+  it "writes csv without the 500-row display cap" do
+    path = File.join(Dir.tmpdir, "monq-export.csv")
+    [{ "a" => 1 }, { "a" => 2 }].write_csv(path)
+    rows = CSV.read(path)
+    expect(rows.size).to eq(3)
+  ensure
+    File.delete(path) if path && File.exist?(path)
+  end
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/export_spec.rb`
+Expected: FAIL, `write_csv` missing
+
+- [ ] **Step 3: Implement**
+
+`Array#write_csv` writes UTF-8 CSV with a header from the first hash's keys. `Array#write_excel` uses `Axlsx::Package` one sheet. Document and Criteria delegate to `to_a` **without** the 500 cap. `vd` shells out to `vd` only when `which vd` succeeds; otherwise print the install hint.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/export_spec.rb spec/display_spec.rb`
+Expected: pass
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/monq/ext spec/export_spec.rb
+git commit -m "feat: export query results to CSV and Excel"
+```
+
+---
+
+### Task 14: Optional blog_dev integration spec and README
+
+**Files:**
+- Create: `spec/integration/blog_dev_spec.rb`
+- Modify: `README.md`
+
+- [ ] **Step 1: Write the spec (skips unless env is set)**
+
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe "blog_dev", :integration do
+  before do
+    skip "set MONQ_TEST_URI and MONQ_TEST_DB" unless ENV["MONQ_TEST_URI"] && ENV["MONQ_TEST_DB"]
+  end
+
+  it "counts users" do
+    klass = Class.new do
+      include Mongoid::Document
+      store_in collection: "users", client: :default, database: ENV.fetch("MONQ_TEST_DB")
+    end
+    Mongo::Client.new(ENV.fetch("MONQ_TEST_URI"), database: ENV.fetch("MONQ_TEST_DB")) do |client|
+      Mongoid::Clients.set(:default, client)
+      expect(klass.count).to be >= 1
+    end
+  end
+end
+```
+
+This spec does not fail CI when the variables are unset.
+
+- [ ] **Step 2: Run it skipped**
+
+Run: `bundle exec rspec spec/integration/blog_dev_spec.rb`
+Expected: 1 skipped (or 1 passed if the variables are already in the shell)
+
+- [ ] **Step 3: Replace README usage**
+
+Document:
+
+- `gem install` / `bundle exec exe/monq`
+- `~/.monq.d/init.yml` example using `uri` + `database: blog_dev` + `namespace: Blog` (placeholder password, not the real one)
+- `~/.monq.d/blog.rb` example: `class User` with `store_in collection: 'users'`, string date fields, `embeds_one` `_meta`, and a `posts` method using a natural key
+- Commands: `info`, `m`, `show-sql`, `reconnect`, `sandbox-enter`, `redefine`
+- SSH limitation: one seed, `direct_connection`, no `replicaSet`, no SRV+SSH
+- Sandbox needs a replica set; driver writes via the model are covered, raw `client[:c].insert_one` is not
+
+- [ ] **Step 4: Run the full suite**
+
+Run: `bundle exec rspec`
+Expected: 0 failures. Integration skipped unless env vars are set.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add spec/integration/blog_dev_spec.rb README.md
+git commit -m "docs: describe monq usage and add optional blog_dev spec"
+```
+
+---
+
+## Spec coverage check
+
+| Spec section | Task |
+|--------------|------|
+| CLI flags, multi-env ban | 6 |
+| YAML select, reserved `default`, no `-e` | 2 |
+| URI vs fields, database override, mask | 3 |
+| SSH rewrite, drop replicaSet, SRV reject | 3, 11 |
+| Named client + `:default` is the same instance | 4, 11 |
+| Prefix load, store_in merge, abbreviations | 5 |
+| redefine unregisters embedded + refuses in sandbox | 5, 10 |
+| const_missing, Kernel helpers | 9 |
+| t/v 500 cap, first-doc keys, no class `Model.t` | 7, 8 |
+| info/m/show-sql/reconnect | 10 |
+| sandbox all-or-nothing, per-client session | 12 |
+| CSV/Excel uncapped | 13 |
+| blog_dev optional integration, secrets not in git | 14 |
+
+Out of scope, matching the spec: auto models, DDL, Ransack, charts, mongodump, `model_names`, class-level `Model.t`.