localvault 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ff1cbda409eb9a922e301dfb73866fde96fa06dc7ace9e670df15ef587dd336
-  data.tar.gz: 8f1b78e9c49e3f6f99a37cd97bbca36054e75c15d99d126699beb61f00a07840
+  metadata.gz: 86be5d86ef86c74bcfc777561088264d1b908eaca92a2b501d5e23d937e5a906
+  data.tar.gz: d3d079c65ff54ca198907957ae3193a3a73520aa84169cf0067bc254967fea05
 SHA512:
-  metadata.gz: 35b625b3e4bd845ba5b5832016f4fd3f310b410e763c476a569c32920f8707317b007f00be9cbd441f704aeccf126d8c4d48646706cab7cc597d1e7fabc07d58
-  data.tar.gz: b509a7068ba88ea63e30ecb9c036c1b3b2d63d58da73cd0e2a812069f907ad8439d0ee1ae5d10d17ca7fb97595c0c420c02ab5f9fe151c96525f0c07b85c91d6
+  metadata.gz: f0d5b4b8d1575b8b91fbd742afd0aef2f71401e72882149cf0b83e68cd233636592c5e0af85512007b4cff604d466ff38d5ac085ea7eea60e9b9446a3d7247a5
+  data.tar.gz: 98a51ac12f4857e0f381fa4b4449a63687d402fe3bf3d97e693f75bfc526440efbc0fd9df14f397c99771c4c871c9a8f164b51e29cca56a232bfa78c099ca8c9

data/README.md

@@ -70,10 +70,13 @@ localvault exec -- rails server
 |---------|-------------|
 | `init [NAME]` | Create a vault (Argon2id key derivation) |
 | `set KEY VALUE` | Store a secret (supports dot-notation: `project.KEY`) |
+| `set --group GROUP KEY VALUE` | Store a secret in a named group |
 | `get KEY` | Retrieve a secret (raw, pipeable) |
 | `show` | Display all secrets in a table (masked by default) |
 | `show --reveal` | Display with values visible |
 | `show --group` | Group by dot-notation prefix (one table per project) |
+| `show --group QUERY` | Show one exact or uniquely matching group |
+| `groups [QUERY]` | List/search group names and key counts without values |
 | `list` | List key names only |
 | `delete KEY` | Remove a secret |
 | `rename OLD NEW` | Rename a secret key |
@@ -214,7 +217,9 @@ localvault remove @alice -v production --rotate
 
 ## MCP Server (AI Agents)
 
-Give AI agents controlled secret access without hardcoding credentials in MCP config. Exact `get_secret` calls can return secret values to the agent; fuzzy reads return candidate names only.
+Give AI agents controlled secret access without hardcoding credentials in MCP
+config. The default workflow keeps values out of model context: discover names,
+build a `localvault exec` command, then run it with process-scoped injection.
 
 ```bash
 # One-command install for Claude Code
@@ -224,15 +229,24 @@ localvault install-mcp claude-code
 # Unlock your vault for the session
 localvault unlock
 
+# Verify setup without starting the blocking stdio server
+localvault mcp --check
+
 # MCP tools available to the agent:
 #   localvault_whoami             — diagnose active vault/session state
-#   get_secret(key, vault?)       — read an exact secret key
 #   list_secrets(vault?, prefix?, query?) — list/search key names
+#   localvault_build_exec(command, ...) — build safe injection (does not execute)
+#   get_secret(key, allow_plaintext: true, vault?) — explicit plaintext reveal
 #   set_secret(key, value, vault?) — store a secret
 #   delete_secret(key, vault?)    — remove a secret
 ```
 
-Command injection stays in the CLI. Use selectors, mappings, and profiles to keep subprocess envs scoped:
+Agents should prefer `localvault_build_exec` for commands, evaluation, API calls,
+and configuration checks. It returns both argv and a shell-safe command without
+opening a vault or reading a value. `get_secret` rejects calls unless
+`allow_plaintext: true` is explicit.
+
+Use selectors, mappings, and profiles to keep subprocess envs scoped:
 
 ```bash
 localvault exec --profile aws -- aws sts get-caller-identity
@@ -249,9 +263,18 @@ One vault, many projects. Dot-notation keeps secrets organized:
 localvault set myapp.DATABASE_URL postgres://localhost/myapp -v work
 localvault set api.DATABASE_URL postgres://localhost/api -v work
 
+# Or use the guided group form
+localvault set --group myapp DATABASE_URL postgres://localhost/myapp -v work
+
+# Search groups without revealing values
+localvault groups app -v work
+
 # View grouped by project
 localvault show --group -v work
 
+# Show one group by exact or unique prefix
+localvault show --group my -v work
+
 # Filter to one project
 localvault show -p myapp -v work
 

data/bin/localvault

@@ -9,4 +9,5 @@ rescue LoadError
   require "localvault/cli"
 end
 
-LocalVault::CLI.start(ARGV)
+status = LocalVault::CLI.start(ARGV)
+exit(status) if status.is_a?(Integer) && !status.zero?

data/lib/localvault/cli/error_presenter.rb

@@ -0,0 +1,177 @@
+require "did_you_mean"
+
+module LocalVault
+  class CLI
+    class ErrorPresenter
+      Context = Data.define(:command_class, :namespace, :token, :command)
+
+      def initialize(root_class, argv)
+        @root_class = root_class
+        @argv = argv.map(&:to_s)
+      end
+
+      def render(error, io: $stderr)
+        @error = error
+        context = @context = resolve_context
+        io.puts error_heading(context)
+        io.puts "Usage: #{usage_for(context)}"
+        render_option_hint(context, io)
+        io.puts
+        io.puts "Try:"
+        suggestions_for(context).first(5).each { |suggestion| io.puts "  #{suggestion}" }
+      end
+
+      private
+
+      def resolve_context
+        command_class = @root_class
+        namespace = []
+        token = @argv.first
+        command = resolve_command(command_class, token)
+
+        if command && command_class.subcommand_classes.key?(command.name)
+          namespace << command.name
+          command_class = command_class.subcommand_classes.fetch(command.name)
+          token = @argv[1]
+          command = resolve_command(command_class, token)
+        end
+
+        Context.new(command_class, namespace, token, command)
+      end
+
+      def resolve_command(command_class, token)
+        return nil unless token && !token.start_with?("-")
+        return command_class.all_commands[token] if command_class.all_commands.key?(token)
+
+        matches = command_class.all_commands.keys.select { |name| name.start_with?(token) }
+        matches.one? ? command_class.all_commands[matches.first] : nil
+      end
+
+      def error_heading(context)
+        if @error.is_a?(CLI::GroupSelectionError)
+          if @error.kind == :ambiguous
+            "Error: Multiple groups match `#{@error.query}`."
+          else
+            "Error: No group matches `#{@error.query}`."
+          end
+        elsif @error.is_a?(CLI::GroupSaveError)
+          case @error.kind
+          when :collision then "Error: cannot create group: that name is already used by a secret key."
+          when :ambiguous then "Error: group name is ambiguous. Existing groups: #{@error.candidates.join(", ")}."
+          else "Error: group and key names may contain letters, digits, and underscores only."
+          end
+        elsif group_save_attempt?
+          "Error: saving in a group needs GROUP, KEY, and VALUE."
+        elsif unknown_option
+          "Error: unknown option `#{unknown_option}`."
+        elsif context.command.nil?
+          "Error: unknown or ambiguous command."
+        else
+          "Error: this command needs a different combination of arguments."
+        end
+      end
+
+      def usage_for(context)
+        if @error.is_a?(CLI::GroupSelectionError)
+          "localvault show --group GROUP"
+        elsif group_save_attempt?
+          "localvault set --group GROUP KEY VALUE"
+        elsif context.command
+          ["localvault", *context.namespace, context.command.usage].join(" ")
+        else
+          ["localvault", *context.namespace, "COMMAND"].join(" ")
+        end
+      end
+
+      def render_option_hint(context, io)
+        return unless unknown_option
+
+        correction = DidYouMean::SpellChecker.new(dictionary: option_names(context)).correct(unknown_option).first
+        io.puts "\nDid you mean `#{correction}`?" if correction
+      end
+
+      def suggestions_for(context)
+        if @error.is_a?(CLI::GroupSelectionError)
+          return @error.candidates.map { |name| "localvault show --group #{name}" } if @error.kind == :ambiguous
+          return ["localvault groups #{@error.query}", "localvault groups"]
+        end
+
+        return group_save_suggestions if group_save_attempt?
+        return ["localvault set KEY VALUE", *group_save_suggestions] if context.command&.name == "set"
+        return show_group_suggestions if context.command&.name == "show" || unknown_option == "--group-by"
+        return ["localvault add HANDLE", "localvault team add HANDLE"] if context.namespace == ["team"] && context.command&.name == "add"
+
+        if context.command
+          examples = curated_examples(context.command)
+          examples.empty? ? [usage_for(context)] : examples
+        else
+          command_suggestions(context)
+        end
+      end
+
+      def group_save_suggestions
+        [
+          "localvault set --group GROUP KEY VALUE",
+          "localvault set GROUP.KEY VALUE",
+          "localvault groups [QUERY]"
+        ]
+      end
+
+      def show_group_suggestions
+        [
+          "localvault show --group GROUP",
+          "localvault groups [QUERY]",
+          "localvault show --project PROJECT"
+        ]
+      end
+
+      def command_suggestions(context)
+        names = context.command_class.all_commands.keys.reject { |name| name == "help" }
+        matches = prefix_or_spelling_matches(names, context.token.to_s)
+        items = matches.map do |name|
+          command = context.command_class.all_commands.fetch(name)
+          ["localvault", *context.namespace, command.usage, "  # #{command.description}"].join(" ")
+        end
+        items.empty? ? ["localvault help"] : items
+      end
+
+      def prefix_or_spelling_matches(names, token)
+        prefix = names.select { |name| name.start_with?(token) }
+        return prefix.sort unless prefix.empty?
+
+        DidYouMean::SpellChecker.new(dictionary: names).correct(token).first(5)
+      end
+
+      def curated_examples(command)
+        command.long_description.to_s.lines.filter_map do |line|
+          example = line.delete("\u0005").strip
+          example if example.start_with?("localvault ")
+        end.uniq
+      end
+
+      def option_names(context)
+        options = context.command_class.class_options.values
+        options += context.command.options.values if context.command
+
+        options.flat_map do |option|
+          ["--#{option.name.to_s.tr("_", "-")}", *Array(option.aliases)]
+        end.uniq
+      end
+
+      def unknown_option
+        return @unknown_option if defined?(@unknown_option)
+
+        known = option_names(@context)
+        @unknown_option = @argv.find do |argument|
+          next false unless argument.start_with?("--") && argument != "--"
+
+          !known.include?(argument.split("=", 2).first)
+        end
+      end
+
+      def group_save_attempt?
+        @argv.first == "set" && @argv.include?("--group")
+      end
+    end
+  end
+end

data/lib/localvault/cli.rb

@@ -6,9 +6,92 @@ 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)
@@ -23,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"
@@ -71,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`)"
@@ -123,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"
@@ -185,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.
@@ -350,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
@@ -369,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])
@@ -468,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
 
@@ -1282,7 +1464,7 @@ module LocalVault
     end
 
     def self.exit_on_failure?
-      true
+      false
     end
 
     no_commands do
@@ -1307,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" => {
@@ -1694,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

@@ -1,3 +1,5 @@
+require_relative "input_validation"
+
 module LocalVault
   module EnvProjection
     class InvalidMapping < StandardError; end
@@ -34,7 +36,10 @@ module LocalVault
     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)
@@ -43,10 +48,12 @@ module LocalVault
 
         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?
-        raise InvalidMapping, "Invalid environment variable name '#{env_name}'" unless safe_env_name?(env_name)
+        InputValidation.mapping!(key, env_name)
 
         hash[key] = env_name
       end
+    rescue InputValidation::InvalidInput => e
+      raise InvalidMapping, e.message
     end
 
     def self.profile_config(profile)

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

data/lib/localvault/input_validation.rb

@@ -0,0 +1,80 @@
+module LocalVault
+  module InputValidation
+    class InvalidInput < StandardError; end
+
+    SEGMENT_PATTERN = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+    VAULT_PATTERN = /\A[A-Za-z0-9][A-Za-z0-9_-]{0,63}\z/
+    PROFILES = %w[aws].freeze
+
+    module_function
+
+    def selector!(value)
+      string!(value, "selector")
+      reject_delimiters!(value, "selector")
+      parts = value.split(".", -1)
+      valid = parts.length == 1 ? segment?(parts.first) :
+        parts.length == 2 && segment?(parts.first) && (segment?(parts.last) || parts.last == "*")
+      raise InvalidInput, "selector must be KEY, GROUP.KEY, or GROUP.*" unless valid
+
+      value
+    end
+
+    def mapping!(source, target)
+      selector!(source)
+      raise InvalidInput, "mapping source must be an exact key" if source.end_with?(".*")
+      string!(target, "mapping target")
+      reject_delimiters!(target, "mapping target")
+      raise InvalidInput, "mapping target must be an environment variable name" unless segment?(target)
+
+      [source, target]
+    end
+
+    def project!(value)
+      string!(value, "project")
+      reject_delimiters!(value, "project")
+      raise InvalidInput, "project must be one key segment" unless segment?(value)
+
+      value
+    end
+
+    def vault_name!(value)
+      string!(value, "vault")
+      raise InvalidInput, "vault must be a valid vault name" unless value.match?(VAULT_PATTERN)
+
+      value
+    end
+
+    def argv!(value)
+      unless value.is_a?(Array) && !value.empty? &&
+          value.all? { |token| token.is_a?(String) && !token.empty? && !token.include?("\0") }
+        raise InvalidInput, "command must be a non-empty array of non-empty NUL-free strings"
+      end
+
+      value
+    end
+
+    def profile!(value)
+      string!(value, "profile")
+      raise InvalidInput, "profile must be one of: #{PROFILES.join(", ")}" unless PROFILES.include?(value)
+
+      value
+    end
+
+    def segment?(value)
+      value.is_a?(String) && value.match?(SEGMENT_PATTERN)
+    end
+
+    def string!(value, label)
+      raise InvalidInput, "#{label} must be a non-empty string" unless value.is_a?(String) && !value.empty?
+      raise InvalidInput, "#{label} must not contain NUL bytes" if value.include?("\0")
+    end
+
+    def reject_delimiters!(value, label)
+      if value.include?(",") || value.include?("=")
+        raise InvalidInput, "#{label} must not contain commas or equals signs"
+      end
+    end
+
+    private_class_method :string!, :reject_delimiters!
+  end
+end

data/lib/localvault/mcp/exec_command_builder.rb

@@ -0,0 +1,77 @@
+require "shellwords"
+require_relative "../input_validation"
+
+module LocalVault
+  module MCP
+    class ExecCommandBuilder
+      def initialize(command:, vault: nil, project: nil, only: nil, except: nil, map: nil, profile: nil)
+        @command = command
+        @vault = vault
+        @project = project
+        @only = only
+        @except = except
+        @map = map
+        @profile = profile
+      end
+
+      def build
+        validate!
+        argv = ["localvault", "exec"]
+        append(argv, "-v", @vault)
+        append(argv, "--project", @project)
+        append(argv, "--only", serialize_selectors(@only))
+        append(argv, "--except", serialize_selectors(@except))
+        append(argv, "--map", serialize_map)
+        append(argv, "--profile", @profile)
+        argv.concat(["--", *@command])
+
+        {
+          "command" => Shellwords.join(argv),
+          "exposes_plaintext" => false,
+          "executes_command" => false,
+          "next_action" => "Run this command through your normal shell tool."
+        }.freeze
+      end
+
+      private
+
+      def validate!
+        InputValidation.argv!(@command)
+        InputValidation.vault_name!(@vault) if @vault
+        InputValidation.project!(@project) if @project
+        InputValidation.profile!(@profile) if @profile
+        validate_selectors!(@only, "only")
+        validate_selectors!(@except, "except")
+        validate_map!
+      end
+
+      def validate_selectors!(selectors, label)
+        return if selectors.nil?
+        unless selectors.is_a?(Array) && !selectors.empty?
+          raise InputValidation::InvalidInput, "#{label} must be a non-empty array of selectors"
+        end
+        selectors.each { |selector| InputValidation.selector!(selector) }
+      end
+
+      def validate_map!
+        return if @map.nil?
+        unless @map.is_a?(Hash) && !@map.empty?
+          raise InputValidation::InvalidInput, "map must be a non-empty object"
+        end
+        @map.each { |source, target| InputValidation.mapping!(source, target) }
+      end
+
+      def append(argv, flag, value)
+        argv.concat([flag, value]) if value
+      end
+
+      def serialize_selectors(selectors)
+        selectors&.join(",")
+      end
+
+      def serialize_map
+        @map&.sort_by { |source, _target| source }&.map { |source, target| "#{source}=#{target}" }&.join(",")
+      end
+    end
+  end
+end

data/lib/localvault/mcp/server.rb

@@ -72,7 +72,10 @@ module LocalVault
           success_response(id, {
             "protocolVersion" => "2025-11-25",
             "capabilities"    => { "tools" => {} },
-            "serverInfo"      => { "name" => "localvault", "version" => LocalVault::VERSION }
+            "serverInfo"      => { "name" => "localvault", "version" => LocalVault::VERSION },
+            "instructions"    => "Do not retrieve plaintext secrets for commands, API calls, evaluation, or configuration. " \
+                                 "Call list_secrets to discover names, then localvault_build_exec to construct process-scoped injection. " \
+                                 "Use get_secret with allow_plaintext: true only when the user task explicitly requires the value itself."
           })
         when "tools/list"
           success_response(id, { "tools" => Tools::DEFINITIONS })

data/lib/localvault/mcp/tools.rb

@@ -1,6 +1,7 @@
 require "json"
 require_relative "../key_lookup"
 require_relative "../version"
+require_relative "exec_command_builder"
 
 module LocalVault
   module MCP
@@ -17,19 +18,21 @@ module LocalVault
       DEFINITIONS = [
         {
           "name" => "get_secret",
-          "description" => "Retrieve a secret value by key from a localvault vault",
+          "description" => "Reveal plaintext only when the task truly requires the value in model context. Prefer localvault_build_exec for commands, evaluations, and API calls.",
           "inputSchema" => {
             "type" => "object",
             "properties" => {
-              "key"   => { "type" => "string", "description" => "The secret key to retrieve" },
+              "key"   => { "type" => "string", "description" => "The exact secret key to reveal" },
+              "allow_plaintext" => { "type" => "boolean", "description" => "Must be true to acknowledge that plaintext will enter model context" },
               **VAULT_PARAM
             },
-            "required" => ["key"]
-          }
+            "required" => ["key", "allow_plaintext"]
+          },
+          "annotations" => { "readOnlyHint" => true, "openWorldHint" => false }
         },
         {
           "name" => "list_secrets",
-          "description" => "List all secret keys in a localvault vault",
+          "description" => "Discover secret names without values. After selecting names, use localvault_build_exec to inject them into a process.",
           "inputSchema" => {
             "type" => "object",
             "properties" => {
@@ -38,7 +41,37 @@ module LocalVault
               **VAULT_PARAM
             },
             "required" => []
-          }
+          },
+          "annotations" => { "readOnlyHint" => true, "openWorldHint" => false }
+        },
+        {
+          "name" => "localvault_build_exec",
+          "description" => "Build, but never execute, a shell-safe localvault exec command that injects secrets directly into a subprocess without exposing values to the model.",
+          "inputSchema" => {
+            "type" => "object",
+            "properties" => {
+              "command" => { "type" => "array", "items" => { "type" => "string" }, "description" => "Command argv to run with injected secrets" },
+              "vault" => { "type" => "string", "description" => "Vault name" },
+              "project" => { "type" => "string", "description" => "Dot-notation project group to inject without a prefix" },
+              "only" => { "type" => "array", "items" => { "type" => "string" }, "description" => "Exact keys or GROUP.* selectors" },
+              "except" => { "type" => "array", "items" => { "type" => "string" }, "description" => "Selectors to exclude" },
+              "map" => { "type" => "object", "additionalProperties" => { "type" => "string" }, "description" => "Vault-key to environment-variable mappings" },
+              "profile" => { "type" => "string", "enum" => ["aws"], "description" => "Built-in mapping profile" }
+            },
+            "required" => ["command"]
+          },
+          "outputSchema" => {
+            "type" => "object",
+            "properties" => {
+              "command" => { "type" => "string" },
+              "exposes_plaintext" => { "type" => "boolean" },
+              "executes_command" => { "type" => "boolean" },
+              "next_action" => { "type" => "string" }
+            },
+            "required" => %w[command exposes_plaintext executes_command next_action],
+            "additionalProperties" => false
+          },
+          "annotations" => { "readOnlyHint" => true, "openWorldHint" => false }
         },
         {
           "name" => "localvault_whoami",
@@ -47,7 +80,8 @@ module LocalVault
             "type" => "object",
             "properties" => { **VAULT_PARAM },
             "required" => []
-          }
+          },
+          "annotations" => { "readOnlyHint" => true, "openWorldHint" => false }
         },
         {
           "name" => "set_secret",
@@ -60,6 +94,12 @@ module LocalVault
               **VAULT_PARAM
             },
             "required" => ["key", "value"]
+          },
+          "annotations" => {
+            "readOnlyHint" => false,
+            "destructiveHint" => true,
+            "idempotentHint" => false,
+            "openWorldHint" => false
           }
         },
         {
@@ -72,6 +112,12 @@ module LocalVault
               **VAULT_PARAM
             },
             "required" => ["key"]
+          },
+          "annotations" => {
+            "readOnlyHint" => false,
+            "destructiveHint" => true,
+            "idempotentHint" => true,
+            "openWorldHint" => false
           }
         }
       ].freeze
@@ -96,12 +142,21 @@ module LocalVault
 
         vault_name = arguments["vault"]
         return whoami(status_resolver.call(vault_name)) if name == "localvault_whoami"
+        return build_exec(arguments) if name == "localvault_build_exec"
+        return required_argument_error("key") if name == "get_secret" && !present_string?(arguments["key"])
+        if name == "get_secret" && arguments["allow_plaintext"] != true
+          return error_result(
+            "Plaintext retrieval is blocked by default. For authentication or an external command, call " \
+            "localvault_build_exec instead. Retry get_secret with allow_plaintext=true only when the user " \
+            "explicitly needs the secret text or injection cannot complete the task."
+          )
+        end
 
         vault = vault_resolver.call(vault_name)
 
         unless vault
           hint = vault_name ? "localvault show -v #{vault_name}" : "localvault show"
-          return error_result("No unlocked vault session. Run: #{hint}")
+          return error_result("No unlocked vault session. Run `localvault mcp --check`, then unlock with: #{hint}")
         end
 
         case name
@@ -138,7 +193,12 @@ module LocalVault
         keys = vault.list
         keys = keys.select { |key| key.start_with?(prefix) } if prefix && !prefix.empty?
         keys = keys.select { |key| key.downcase.include?(query.downcase) } if query && !query.empty?
-        keys.empty? ? text_result("No secrets stored") : text_result(keys.join("\n"))
+        result = keys.empty? ? text_result("No secrets stored") : text_result(keys.join("\n"))
+        result["content"] << {
+          "type" => "text",
+          "text" => "Next: call localvault_build_exec with command argv and optional only/project mappings. Do not copy secret values."
+        }
+        result
       end
 
       def self.set_secret(key, value, vault)
@@ -180,6 +240,23 @@ module LocalVault
         text_result(text).merge("structuredContent" => structured)
       end
 
+      def self.build_exec(arguments)
+        result = ExecCommandBuilder.new(
+          command: arguments["command"],
+          vault: arguments["vault"],
+          project: arguments["project"],
+          only: arguments["only"],
+          except: arguments["except"],
+          map: arguments["map"],
+          profile: arguments["profile"]
+        ).build
+        text_result(
+          "Built command (not executed):\n#{result["command"]}\n\n#{result["next_action"]}"
+        ).merge("structuredContent" => result)
+      rescue InputValidation::InvalidInput => e
+        error_result(e.message)
+      end
+
       def self.candidate_message(header, matches)
         ([header] + matches.map { |match| "  #{match}" }).join("\n")
       end
@@ -200,7 +277,7 @@ module LocalVault
         error_result("Argument '#{name}' must be a string")
       end
 
-      private_class_method :get_secret, :list_secrets, :set_secret, :delete_secret,
+      private_class_method :get_secret, :list_secrets, :set_secret, :delete_secret, :build_exec,
         :text_result, :error_result, :whoami, :candidate_message,
         :present_string?, :optional_string?, :required_argument_error, :string_argument_error
     end

data/lib/localvault/session_cache.rb

@@ -1,6 +1,6 @@
 require "base64"
 require "fileutils"
-require "shellwords"
+require "open3"
 
 module LocalVault
   # Caches derived master keys to avoid re-prompting passphrase on every command.
@@ -95,8 +95,11 @@ module LocalVault
 
     def self.keychain_get(vault_name)
       if macos?
-        out = `security find-generic-password -a #{Shellwords.escape(vault_name)} -s #{Shellwords.escape(KEYCHAIN_SERVICE)} -w 2>/dev/null`.chomp
-        return out if $?.success? && !out.empty?
+        out = run_command(
+          ["security", "find-generic-password", "-a", vault_name, "-s", KEYCHAIN_SERVICE, "-w"],
+          timeout: 2
+        )
+        return out unless out.nil? || out.empty?
       end
       # File fallback (Linux, or macOS when Keychain unavailable)
       file = session_file(vault_name)
@@ -143,5 +146,28 @@ module LocalVault
       FileUtils.rm_f(session_file(vault_name))
     end
 
+    def self.run_command(argv, timeout:)
+      output = nil
+      Open3.popen3(*argv) do |stdin, stdout, stderr, wait_thread|
+        stdin.close
+        unless wait_thread.join(timeout)
+          Process.kill("TERM", wait_thread.pid)
+          unless wait_thread.join(0.1)
+            Process.kill("KILL", wait_thread.pid)
+            wait_thread.join
+          end
+          return nil
+        end
+
+        output = stdout.read.chomp if wait_thread.value.success?
+        stderr.close
+      rescue Errno::ESRCH
+        return nil
+      end
+      output
+    rescue Errno::ENOENT
+      nil
+    end
+
   end
 end

data/lib/localvault/vault_resolver.rb

@@ -33,6 +33,17 @@ module LocalVault
       }
     end
 
+    def self.readiness_status(name = nil)
+      result = resolve(name)
+      {
+        "localvault_home" => Config.root_path,
+        "active_vault" => result.active_vault,
+        "active_vault_source" => result.active_vault_source,
+        "session_vault" => result.session_vault,
+        "active_vault_unlocked" => !result.vault.nil?
+      }
+    end
+
     def self.active_vault_name(name = nil)
       return [name, "argument"] if name && !name.empty?
       return [ENV["LOCALVAULT_VAULT"], "env"] if ENV["LOCALVAULT_VAULT"] && !ENV["LOCALVAULT_VAULT"].empty?

data/lib/localvault/version.rb

@@ -1,3 +1,3 @@
 module LocalVault
-  VERSION = "1.7.0"
+  VERSION = "1.8.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: localvault
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.0
 platform: ruby
 authors:
 - Nauman Tariq
@@ -108,6 +108,7 @@ files:
 - lib/localvault.rb
 - lib/localvault/api_client.rb
 - lib/localvault/cli.rb
+- lib/localvault/cli/error_presenter.rb
 - lib/localvault/cli/keys.rb
 - lib/localvault/cli/sync.rb
 - lib/localvault/cli/team.rb
@@ -115,9 +116,12 @@ files:
 - lib/localvault/config.rb
 - lib/localvault/crypto.rb
 - lib/localvault/env_projection.rb
+- lib/localvault/group_catalog.rb
 - lib/localvault/identity.rb
+- lib/localvault/input_validation.rb
 - lib/localvault/key_lookup.rb
 - lib/localvault/key_slot.rb
+- lib/localvault/mcp/exec_command_builder.rb
 - lib/localvault/mcp/server.rb
 - lib/localvault/mcp/tools.rb
 - lib/localvault/session_cache.rb