localvault 1.6.2 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fe9cdf4fe4857588507532f6478318a7b02cdc47487bbecbe7ce54715e69e33
-  data.tar.gz: 1be1af8d9476e1171895a0ba0677e206832de1386416cd5fb7e7060e7b8b85f5
+  metadata.gz: 86be5d86ef86c74bcfc777561088264d1b908eaca92a2b501d5e23d937e5a906
+  data.tar.gz: d3d079c65ff54ca198907957ae3193a3a73520aa84169cf0067bc254967fea05
 SHA512:
-  metadata.gz: 500451ad18462b5380839eb06b031b83b3acb91872430855e07038896c392f9488934aaf1649bd311886890400aaef9c45a062d8503c6db0760a2927b56a1650
-  data.tar.gz: aa1aa1b764c2de50ab0c8fb425b14a77e05085f2224131c7f53dc1eaaccc9b80732f160716a1826ef479c0d9653e5451074ca585927a86630ef68a92f23b9b8c
+  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,28 +217,41 @@ localvault remove @alice -v production --rotate
 
 ## MCP Server (AI Agents)
 
-Give AI agents safe secret access. Keys never appear in agent context or config files.
+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
 localvault install-mcp claude-code
-# Also supports: cursor, windsurf, zed
+# Also supports: cursor, windsurf
 
 # 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:
-#   get_secret(key, vault?)      — read a secret
-#   list_secrets(vault?, prefix?) — list key names
+#   localvault_whoami             — diagnose active vault/session state
+#   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
+#   delete_secret(key, vault?)    — remove a secret
 ```
 
-**exec_action** — agent declares intent, LocalVault executes with secrets injected. The agent never sees the key:
+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_action -- curl -s https://api.openai.com/v1/models \
-  -H "Authorization: Bearer $OPENAI_API_KEY"
+localvault exec --profile aws -- aws sts get-caller-identity
+localvault exec --only AWS_IAM.*,AWS_SES.* --except AWS_SES.smtp_password -- your-script
+localvault env --map AWS_IAM.access_key_id=AWS_ACCESS_KEY_ID
 ```
 
 ## Multi-Project Vaults
@@ -247,15 +263,28 @@ 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
 
 # Export one project
 eval $(localvault env -p myapp -v work)
 
+# Export all projects with project.key transformed to PROJECT__key
+localvault env -v work
+# → MYAPP__DATABASE_URL, API__DATABASE_URL
+
 # Bulk import
 localvault import .env --prefix myapp -v work
 ```
@@ -272,7 +301,7 @@ localvault get API_KEY
 localvault exec -- rails server
 ```
 
-Session lives in `LOCALVAULT_SESSION` — disappears when the terminal closes.
+Unlocking writes a derived key to `LOCALVAULT_SESSION` and also caches it with an 8-hour TTL in Keychain or LocalVault's file fallback so MCP and new terminals can reuse it until `localvault lock`.
 
 ## Security
 
@@ -324,7 +353,7 @@ localvault login --server https://vaulthost.example
 git clone https://github.com/inventlist/localvault.git
 cd localvault
 bundle install
-bundle exec rake test  # 463 tests, 918 assertions
+bundle exec rake test
 ```
 
 ## Used by

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