localvault 1.6.2 → 1.8.0

data/lib/localvault/cli.rb

@@ -2,10 +2,96 @@ require "thor"
 require "io/console"
 require "base64"
 require "lipgloss"
+require_relative "env_projection"
+require_relative "key_lookup"
 require_relative "session_cache"
+require_relative "vault_resolver"
+require_relative "group_catalog"
 
 module LocalVault
   class CLI < Thor
+    USAGE_EXIT_STATUS = 1
+    GROUP_ALL_SENTINEL = "\0localvault-all-groups"
+    GROUP_OFF_SENTINEL = "\0localvault-groups-off"
+    CommandStatus = Data.define(:code) do
+      def self.ok
+        new(0)
+      end
+
+      def self.error
+        new(1)
+      end
+    end
+    class GroupSaveError < Thor::Error
+      attr_reader :kind, :candidates
+
+      def initialize(kind, candidates: [])
+        @kind = kind
+        @candidates = candidates
+        super("group save failed")
+      end
+
+      def exit_status
+        1
+      end
+    end
+    class GroupSelectionError < Thor::Error
+      attr_reader :kind, :query, :candidates
+
+      def initialize(kind, query:, candidates: [])
+        @kind = kind
+        @query = query
+        @candidates = candidates
+        super("group selection failed")
+      end
+
+      def exit_status
+        1
+      end
+    end
+
+    def self.start(given_args = ARGV, config = {})
+      require_relative "cli/error_presenter"
+      config[:shell] ||= Thor::Base.shell.new
+      result = dispatch(nil, normalize_legacy_group_option(given_args.dup), nil, config)
+      result.is_a?(CommandStatus) ? result.code : 0
+    rescue Thor::Error => error
+      ErrorPresenter.new(self, given_args).render(error)
+      error.respond_to?(:exit_status) ? error.exit_status : USAGE_EXIT_STATUS
+    rescue Errno::EPIPE
+      0
+    end
+
+    def self.normalize_legacy_group_option(arguments)
+      command = arguments.first
+      matches = all_commands.keys.select { |name| name.start_with?(command.to_s) }
+      return arguments unless command == "show" || matches == ["show"]
+
+      normalized = []
+      index = 0
+      while index < arguments.length
+        argument = arguments[index]
+        if argument == "--"
+          normalized.concat(arguments[index..])
+          break
+        end
+        if argument == "--group" && arguments[index + 1]&.match?(/\A(?:true|false|t|f)\z/i)
+          enabled = arguments[index + 1].match?(/\A(?:true|t)\z/i)
+          normalized << "--group=#{enabled ? GROUP_ALL_SENTINEL : GROUP_OFF_SENTINEL}"
+          index += 2
+          next
+        end
+
+        case argument
+        when /\A--group=(?:true|t)\z/i then normalized << "--group=#{GROUP_ALL_SENTINEL}"
+        when /\A--group=(?:false|f)\z/i, "--no-group", "--skip-group" then normalized << "--group=#{GROUP_OFF_SENTINEL}"
+        else normalized << argument
+        end
+        index += 1
+      end
+      normalized
+    end
+
     class_option :vault, aliases: "-v", type: :string, desc: "Vault name"
 
     def self.help(shell, subcommand = false)
@@ -20,8 +106,10 @@ module LocalVault
       shell.say ""
       shell.say "SECRETS"
       shell.say "  localvault set KEY VALUE      Store a secret"
+      shell.say "  localvault set --group G K V  Store a secret inside group G"
       shell.say "  localvault get KEY            Retrieve a secret"
       shell.say "  localvault show               Display all secrets (masked by default)"
+      shell.say "  localvault groups [QUERY]     List or search stored groups (names only)"
       shell.say "  localvault list               List secret key names"
       shell.say "  localvault delete KEY         Remove a secret"
       shell.say "  localvault import FILE        Bulk-import from .env / .json / .yml"
@@ -68,6 +156,8 @@ module LocalVault
       shell.say "AI / MCP"
       shell.say "  localvault install-mcp        Configure MCP server in your AI tool"
       shell.say "  localvault mcp                Start MCP server (stdio)"
+      shell.say "  localvault mcp --check        Check setup and active-vault readiness"
+      shell.say "  Agents: list names, then use localvault_build_exec for safe injection"
       shell.say ""
       shell.say "LEGACY SHARING  (pre-v1.2 direct share, still works as fallback)"
       shell.say "  localvault keygen             Generate X25519 keypair (same as `keys generate`)"
@@ -120,14 +210,38 @@ module LocalVault
 \x05    localvault set platepose.SECRET_KEY_BASE abc123          -v intellectaco
 \x05    localvault set inventlist.STRIPE_KEY sk_live_abc123      -v intellectaco
 
+      GUIDED GROUP SAVE (same storage, easier to discover):
+\x05    localvault set --group GROUP KEY VALUE
+\x05    localvault set GROUP.KEY VALUE
+\x05    localvault groups [QUERY]
+
       The dot separates project from key name. One vault can hold many projects.
       Use `localvault show -p platepose -v vault` to view a single project.
       Use `localvault import` to bulk-load from a .env, .json, or .yml file.
     DESC
+    method_option :group, type: :string, desc: "Store KEY and VALUE inside this named group"
     def set(key, value)
       vault = open_vault!
-      vault.set(key, value)
-      $stdout.puts "Set #{key} in vault '#{vault.name}'"
+      if options[:group]
+        group = canonical_group_name(vault, options[:group])
+        validate_group_segment!(group)
+        validate_group_segment!(key)
+        raise GroupSaveError, :collision if vault.all.key?(group) && !vault.all[group].is_a?(Hash)
+        vault.set("#{group}.#{key}", value)
+        $stdout.puts "Set #{key} in group `#{group}` in vault `#{vault.name}`."
+        $stdout.puts
+        $stdout.puts "Stored as:"
+        $stdout.puts "  #{group}.#{key}"
+      else
+        vault.set(key, value)
+        $stdout.puts "Set #{key} in vault '#{vault.name}'"
+      end
+    rescue Vault::InvalidKeyName => e
+      raise GroupSaveError, :invalid if options[:group]
+      abort_with e.message
+    rescue RuntimeError => e
+      raise GroupSaveError, :collision if options[:group]
+      abort_with e.message
     end
 
     desc "get KEY", "Retrieve a secret value by key"
@@ -146,28 +260,18 @@ module LocalVault
     DESC
     def get(key)
       vault = open_vault!
-      value = vault.get(key)
-
-      if value.nil?
-        # Fall back to case-insensitive substring match
-        all_keys = vault.list
-        matches  = all_keys.select { |k| k.downcase.include?(key.downcase) }
-
-        if matches.size == 1
-          value = vault.get(matches.first)
-          $stdout.puts value
-          return
-        elsif matches.size > 1
-          $stderr.puts "Error: Multiple keys match '#{key}'. Be more specific:"
-          matches.sort.each { |k| $stderr.puts "  #{k}" }
-          return
-        else
-          abort_with "Key '#{key}' not found in vault '#{vault.name}'"
-          return
-        end
+      lookup = KeyLookup.lookup(vault, key)
+
+      if lookup.exact?
+        $stdout.puts lookup.value
+      elsif lookup.single_match?
+        $stdout.puts vault.get(lookup.matches.first)
+      elsif lookup.multiple_matches?
+        $stderr.puts "Error: Multiple keys match '#{key}'. Be more specific:"
+        lookup.matches.each { |k| $stderr.puts "  #{k}" }
+      else
+        abort_with "Key '#{key}' not found in vault '#{vault.name}'"
       end
-
-      $stdout.puts value
     end
 
     desc "list", "List all secret keys in the vault"
@@ -192,6 +296,30 @@ module LocalVault
       vault.list.each { |key| $stdout.puts key }
     end
 
+    desc "groups [QUERY]", "List or search stored secret groups without revealing values"
+    long_desc <<~DESC
+      Discover dot-notation namespaces and flat-key prefix groups.
+
+\x05    localvault groups
+\x05    localvault groups str
+\x05    localvault show --group STRIPE
+\x05    localvault set --group STRIPE API_KEY VALUE
+    DESC
+    def groups(query = nil)
+      vault = open_vault!
+      matches = GroupCatalog.new(vault.all).search(query)
+      if matches.empty?
+        $stdout.puts "No groups match #{query}"
+        return
+      end
+
+      heading = query ? "Groups matching `#{query}`" : "Groups"
+      $stdout.puts "#{heading} in vault `#{vault.name}`:"
+      $stdout.puts
+      $stdout.printf("  %-20s %-6s %s\n", "Group", "Keys", "Kind")
+      matches.each { |group| $stdout.printf("  %-20s %-6d %s\n", group.name, group.count, group.kind) }
+    end
+
     desc "delete KEY", "Remove a secret or entire project group"
     long_desc <<~DESC
       Delete a single key or an entire project group.
@@ -231,13 +359,25 @@ module LocalVault
 \x05    eval $(localvault env -v intellectaco)
 \x05    # → export PLATEPOSE__DATABASE_URL=...  export INVENTLIST__DATABASE_URL=...
 
+      SCOPED EXPORTS:
+\x05    localvault env --only AWS_IAM.*
+\x05    localvault env --only AWS_IAM.*,AWS_SES.* --except AWS_SES.smtp_password
+\x05    localvault env --map AWS_IAM.access_key_id=AWS_ACCESS_KEY_ID
+\x05    localvault env --profile aws
+
       Use `localvault exec` to inject directly into a subprocess without eval.
     DESC
     method_option :project, aliases: "-p", type: :string, desc: "Export only this project group (no prefix)"
+    method_option :only, type: :string, desc: "Export only exact keys or namespaces (KEY,GROUP.*)"
+    method_option :except, type: :string, desc: "Exclude exact keys or namespaces after --only"
+    method_option :map, type: :string, desc: "Map vault keys to env vars (KEY=ENV_NAME)"
+    method_option :profile, type: :string, desc: "Apply a built-in env mapping profile (aws)"
     def env
       vault = open_vault!
       skip_warn = ->(k) { $stderr.puts "Warning: skipping unsafe key '#{k}'" }
-      $stdout.puts vault.export_env(project: options[:project], on_skip: skip_warn)
+      $stdout.puts vault.export_env(**env_projection_options(on_skip: skip_warn))
+    rescue EnvProjection::InvalidMapping, EnvProjection::UnknownProfile => e
+      abort_with e.message
     end
 
     desc "exec -- CMD", "Run a command with secrets injected as environment variables"
@@ -256,13 +396,24 @@ module LocalVault
       TEAM VAULT — all projects (keys prefixed to avoid collisions):
 \x05    localvault exec -v intellectaco -- your-script
 \x05    # → PLATEPOSE__DATABASE_URL, INVENTLIST__DATABASE_URL, etc.
+
+      SCOPED INJECTION:
+\x05    localvault exec --only AWS_IAM.* -- aws sts get-caller-identity
+\x05    localvault exec --profile aws -- aws s3 ls
+\x05    localvault exec --map AWS_IAM.access_key_id=AWS_ACCESS_KEY_ID -- env
     DESC
     method_option :project, aliases: "-p", type: :string, desc: "Inject only this project group (no prefix)"
+    method_option :only, type: :string, desc: "Inject only exact keys or namespaces (KEY,GROUP.*)"
+    method_option :except, type: :string, desc: "Exclude exact keys or namespaces after --only"
+    method_option :map, type: :string, desc: "Map vault keys to env vars (KEY=ENV_NAME)"
+    method_option :profile, type: :string, desc: "Apply a built-in env mapping profile (aws)"
     def exec(*cmd)
       vault = open_vault!
       skip_warn = ->(k) { $stderr.puts "Warning: skipping unsafe key '#{k}'" }
-      env_vars = vault.env_hash(project: options[:project], on_skip: skip_warn)
+      env_vars = vault.env_hash(**env_projection_options(on_skip: skip_warn))
       Kernel.exec(env_vars, *cmd)
+    rescue EnvProjection::InvalidMapping, EnvProjection::UnknownProfile => e
+      abort_with e.message
     end
 
     desc "vaults", "List all vaults with secret counts"
@@ -334,14 +485,15 @@ module LocalVault
 \x05    localvault show -p platepose -v intellectaco  # one project only
 \x05    localvault show -p platepose -v intellectaco --reveal
     DESC
-    method_option :group,   type: :boolean, default: false, desc: "Group flat keys by common prefix"
+    method_option :group, type: :string, lazy_default: GROUP_ALL_SENTINEL, desc: "Show all groups or one group by name"
     method_option :reveal,  type: :boolean, default: false, desc: "Show full values instead of masking"
     method_option :project, aliases: "-p", type: :string,   desc: "Show only this project group"
     def show
       vault = open_vault!
       secrets = vault.all
 
-      if secrets.empty?
+      named_group_query = options[:group] && ![GROUP_ALL_SENTINEL, GROUP_OFF_SENTINEL].include?(options[:group])
+      if secrets.empty? && !named_group_query
         $stdout.puts "No secrets in vault '#{vault.name}'."
         return
       end
@@ -353,7 +505,17 @@ module LocalVault
           return
         end
         render_table(group.sort.to_h, "#{vault.name}/#{options[:project]}", reveal: options[:reveal])
-      elsif options[:group] || secrets.values.any? { |v| v.is_a?(Hash) }
+      elsif options[:group] && ![GROUP_ALL_SENTINEL, GROUP_OFF_SENTINEL].include?(options[:group])
+        match = GroupCatalog.new(secrets).resolve(options[:group])
+        if match.group
+          entries = match.group.entries.to_h { |entry| [entry.label, entry.value] }
+          render_table(entries, "#{vault.name}/#{match.group.name}", reveal: options[:reveal])
+        elsif match.kind == :ambiguous
+          raise GroupSelectionError.new(:ambiguous, query: options[:group], candidates: match.groups.map(&:name))
+        else
+          raise GroupSelectionError.new(:absent, query: options[:group])
+        end
+      elsif options[:group] != GROUP_OFF_SENTINEL && (options[:group] || secrets.values.any? { |v| v.is_a?(Hash) })
         render_grouped_table(secrets, vault.name, reveal: options[:reveal])
       else
         render_table(secrets.sort.to_h, vault.name, reveal: options[:reveal])
@@ -452,8 +614,44 @@ module LocalVault
     end
 
     desc "mcp", "Start MCP server (stdio)"
+    long_desc <<~DESC
+      Start LocalVault's stdio MCP server for an AI client.
+
+      Install and verify:
+\x05    localvault install-mcp [claude-code|cursor|windsurf]
+\x05    localvault mcp --check
+\x05    localvault show
+
+      Do not run `localvault mcp` directly to test it: stdio servers wait for
+      JSON-RPC input and therefore appear idle. Use `--check`, then restart the
+      configured AI client.
+
+      Agents should call `list_secrets`, then `localvault_build_exec` to inject
+      secrets into a subprocess. Plaintext `get_secret` requires the explicit
+      `allow_plaintext: true` acknowledgement.
+    DESC
+    method_option :check, type: :boolean, default: false, desc: "Check installation and active-vault readiness, then exit"
     def mcp
-      require "localvault/mcp/server"
+      if options[:check]
+        require_relative "mcp/tools"
+        status = VaultResolver.readiness_status(options[:vault])
+        ready = status["active_vault_unlocked"]
+        tool_names = MCP::Tools::DEFINITIONS.map { |definition| definition.fetch("name") }
+        $stdout.puts "LocalVault #{VERSION}"
+        $stdout.puts "Home: #{Config.root_path}"
+        $stdout.puts "MCP readiness: #{ready ? "ready" : "locked"}"
+        $stdout.puts "Active vault: #{status["active_vault"]} (#{status["active_vault_source"]})"
+        $stdout.puts "Vault session: #{ready ? "available" : "unlock with `localvault show`"}"
+        $stdout.puts "MCP tools: #{tool_names.join(", ")}"
+        $stdout.puts "Plaintext gate: enabled"
+        $stdout.puts "Server instructions: enabled"
+        $stdout.puts
+        $stdout.puts "Safe agent workflow: list_secrets → localvault_build_exec → run the generated command"
+        $stdout.puts "Plaintext retrieval is opt-in with allow_plaintext: true."
+        return ready ? CommandStatus.ok : CommandStatus.error
+      end
+
+      require_relative "mcp/server"
       MCP::Server.new.start
     end
 
@@ -466,8 +664,10 @@ module LocalVault
         cursor        Adds to ~/.cursor/mcp.json
         windsurf      Adds to ~/.codeium/windsurf/mcp_config.json
 
-      The MCP server uses whichever vault is your current default (localvault switch).
-      Unlock the vault once with `localvault show`, then the AI tool picks it up via Keychain.
+      The MCP server uses the same active vault rules as the CLI: explicit vault,
+      then LOCALVAULT_VAULT, then the configured default from `localvault switch`.
+      Unlock with `localvault show` or `localvault unlock`; `localvault lock`
+      revokes access without restarting the AI tool.
     DESC
     def install_mcp(client = "claude-code")
       case client.downcase
@@ -1264,7 +1464,7 @@ module LocalVault
     end
 
     def self.exit_on_failure?
-      true
+      false
     end
 
     no_commands do
@@ -1289,6 +1489,23 @@ module LocalVault
 
     private
 
+    def canonical_group_name(vault, supplied)
+      groups = GroupCatalog.new(vault.all).groups
+      return supplied if groups.any? { |group| group.name == supplied }
+
+      insensitive = groups.select { |group| group.name.casecmp?(supplied) }
+      return insensitive.first.name if insensitive.one?
+      raise GroupSaveError.new(:ambiguous, candidates: insensitive.map(&:name)) if insensitive.length > 1
+
+      supplied
+    end
+
+    def validate_group_segment!(segment)
+      unless segment.match?(Vault::KEY_SEGMENT_PATTERN) && segment.length <= 128
+        raise GroupSaveError, :invalid
+      end
+    end
+
     # ── Demo data ──────────────────────────────────────────────────
     DEMO_DATA = {
       "default" => {
@@ -1514,7 +1731,18 @@ module LocalVault
     end
 
     def resolve_vault_name
-      options[:vault] || Config.default_vault
+      VaultResolver.active_vault_name(options[:vault]).first
+    end
+
+    def env_projection_options(on_skip:)
+      {
+        project: options[:project],
+        only: options[:only],
+        except: options[:except],
+        map: options[:map],
+        profile: options[:profile],
+        on_skip: on_skip
+      }
     end
 
     def open_vault_by_name!(vault_name)
@@ -1665,9 +1893,11 @@ module LocalVault
     def print_next_steps(client_name)
       $stdout.puts ""
       $stdout.puts "Next steps:"
-      $stdout.puts "  1. Restart #{client_name}"
-      $stdout.puts "  2. Unlock your vault once:  localvault show"
-      $stdout.puts "  3. The AI can now access secrets from your default vault"
+      $stdout.puts "  1. Unlock your vault once:  localvault show"
+      $stdout.puts "  2. Verify readiness:         localvault mcp --check"
+      $stdout.puts "  3. Restart #{client_name}"
+      $stdout.puts "  4. Ask the agent to list names, then use localvault_build_exec"
+      $stdout.puts "     for process injection. Plaintext get_secret is explicit opt-in."
       $stdout.puts "     Switch vaults: localvault switch <vault>"
     end
 

data/lib/localvault/env_projection.rb

@@ -0,0 +1,138 @@
+require_relative "input_validation"
+
+module LocalVault
+  module EnvProjection
+    class InvalidMapping < StandardError; end
+    class UnknownProfile < StandardError; end
+
+    Entry = Struct.new(:key, :env_name, :value, keyword_init: true)
+
+    ENV_NAME_PATTERN = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+
+    PROFILES = {
+      "aws" => {
+        only: ["AWS_IAM.*"],
+        map: {
+          "AWS_IAM.access_key_id" => "AWS_ACCESS_KEY_ID",
+          "AWS_IAM.secret_access_key" => "AWS_SECRET_ACCESS_KEY",
+          "AWS_IAM.session_token" => "AWS_SESSION_TOKEN"
+        }
+      }
+    }.freeze
+
+    def self.entries(secrets, project: nil, only: nil, except: nil, map: nil, profile: nil, on_skip: nil)
+      profile_config = profile_config(profile)
+      selectors = parse_selectors(only) || profile_config[:only]
+      exclusions = parse_selectors(except) || []
+      mappings = profile_config[:map].merge(parse_map(map))
+
+      flatten(secrets, project: project, on_skip: on_skip)
+        .select { |entry| include_entry?(entry.key, selectors) }
+        .reject { |entry| selector_match?(entry.key, exclusions) }
+        .map { |entry| apply_mapping(entry, mappings, on_skip: on_skip) }
+        .compact
+    end
+
+    def self.parse_selectors(value)
+      values = Array(value).compact.flat_map { |v| v.to_s.split(",") }
+      selectors = values.map(&:strip).reject(&:empty?)
+      selectors.each { |selector| InputValidation.selector!(selector) }
+      selectors.empty? ? nil : selectors
+    rescue InputValidation::InvalidInput => e
+      raise InvalidMapping, e.message
+    end
+
+    def self.parse_map(value)
+      Array(value).compact.flat_map { |v| v.to_s.split(",") }.each_with_object({}) do |pair, hash|
+        next if pair.strip.empty?
+
+        key, env_name = pair.split("=", 2).map(&:strip)
+        raise InvalidMapping, "Invalid map '#{pair}'. Use KEY=ENV_NAME" if key.to_s.empty? || env_name.to_s.empty?
+        InputValidation.mapping!(key, env_name)
+
+        hash[key] = env_name
+      end
+    rescue InputValidation::InvalidInput => e
+      raise InvalidMapping, e.message
+    end
+
+    def self.profile_config(profile)
+      return { only: nil, map: {} } if profile.nil? || profile.to_s.empty?
+
+      PROFILES.fetch(profile.to_s) do
+        raise UnknownProfile, "Unknown env profile '#{profile}'"
+      end
+    end
+
+    def self.flatten(secrets, project:, on_skip:)
+      if project
+        group = secrets[project]
+        return [] unless group.is_a?(Hash)
+
+        group.filter_map do |key, value|
+          if safe_env_name?(key)
+            Entry.new(key: key, env_name: key, value: value.to_s)
+          else
+            on_skip&.call(key)
+            nil
+          end
+        end
+      else
+        secrets.flat_map do |key, value|
+          if value.is_a?(Hash)
+            flatten_group(key, value, on_skip: on_skip)
+          elsif safe_env_name?(key)
+            [Entry.new(key: key, env_name: key, value: value.to_s)]
+          else
+            on_skip&.call(key)
+            []
+          end
+        end
+      end
+    end
+
+    def self.flatten_group(group, pairs, on_skip:)
+      unless safe_env_name?(group)
+        on_skip&.call(group)
+        return []
+      end
+
+      pairs.filter_map do |key, value|
+        if safe_env_name?(key)
+          Entry.new(key: "#{group}.#{key}", env_name: "#{group.upcase}__#{key}", value: value.to_s)
+        else
+          on_skip&.call("#{group}.#{key}")
+          nil
+        end
+      end
+    end
+
+    def self.include_entry?(key, selectors)
+      selectors.nil? || selector_match?(key, selectors)
+    end
+
+    def self.selector_match?(key, selectors)
+      selectors.any? do |selector|
+        if selector.end_with?(".*")
+          key.start_with?("#{selector.delete_suffix(".*")}.")
+        else
+          key == selector
+        end
+      end
+    end
+
+    def self.apply_mapping(entry, mappings, on_skip:)
+      mapped_name = mappings.fetch(entry.key, entry.env_name)
+      unless safe_env_name?(mapped_name)
+        on_skip&.call(entry.key)
+        return nil
+      end
+
+      Entry.new(key: entry.key, env_name: mapped_name, value: entry.value)
+    end
+
+    def self.safe_env_name?(name)
+      name.is_a?(String) && name.match?(ENV_NAME_PATTERN)
+    end
+  end
+end

data/lib/localvault/group_catalog.rb

@@ -0,0 +1,67 @@
+module LocalVault
+  class GroupCatalog
+    Entry = Data.define(:label, :value, :source_kind)
+    Group = Data.define(:name, :kind, :entries) do
+      def count
+        entries.length
+      end
+    end
+    Match = Data.define(:kind, :query, :groups) do
+      def group
+        groups.one? ? groups.first : nil
+      end
+    end
+
+    attr_reader :groups
+
+    def initialize(secrets)
+      grouped = {}
+
+      secrets.each do |name, value|
+        if value.is_a?(Hash)
+          append_namespace(grouped, name, value)
+        elsif name.include?("_")
+          append_entry(grouped, name.split("_", 2).first, Entry.new(name, value, :prefix))
+        end
+      end
+
+      @groups = grouped.map do |name, entries|
+        kinds = entries.map(&:source_kind).uniq
+        kind = kinds.length > 1 ? :mixed : kinds.first
+        Group.new(name, kind, entries.sort_by(&:label).freeze)
+      end.sort_by { |group| [group.name.downcase, group.name] }.freeze
+    end
+
+    def search(query = nil)
+      return groups if query.nil? || query.empty?
+
+      needle = query.downcase
+      groups.select { |group| group.name.downcase.start_with?(needle) }
+    end
+
+    def resolve(query)
+      exact = groups.select { |group| group.name == query }
+      return Match.new(:exact, query, exact) if exact.one?
+
+      insensitive = groups.select { |group| group.name.casecmp?(query) }
+      return Match.new(:unique, query, insensitive) if insensitive.one?
+      return Match.new(:ambiguous, query, insensitive) if insensitive.length > 1
+
+      matches = search(query)
+      kind = matches.one? ? :unique : (matches.empty? ? :absent : :ambiguous)
+      Match.new(kind, query, matches)
+    end
+
+    private
+
+    def append_namespace(grouped, name, values)
+      values.each do |label, value|
+        append_entry(grouped, name, Entry.new(label, value, :namespace))
+      end
+    end
+
+    def append_entry(grouped, name, entry)
+      (grouped[name] ||= []) << entry
+    end
+  end
+end