localvault 1.7.0 → 1.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ff1cbda409eb9a922e301dfb73866fde96fa06dc7ace9e670df15ef587dd336
-  data.tar.gz: 8f1b78e9c49e3f6f99a37cd97bbca36054e75c15d99d126699beb61f00a07840
+  metadata.gz: a7cdca7447f0efeb125773a3385a6e3beee17cb03d4c05e04b91dc59254215dd
+  data.tar.gz: b3378c85ad59e00561d5eb5f590e203469d86f8c88925e7b547721717175f5a4
 SHA512:
-  metadata.gz: 35b625b3e4bd845ba5b5832016f4fd3f310b410e763c476a569c32920f8707317b007f00be9cbd441f704aeccf126d8c4d48646706cab7cc597d1e7fabc07d58
-  data.tar.gz: b509a7068ba88ea63e30ecb9c036c1b3b2d63d58da73cd0e2a812069f907ad8439d0ee1ae5d10d17ca7fb97595c0c420c02ab5f9fe151c96525f0c07b85c91d6
+  metadata.gz: 2e4409c50f9aa0350b86541e905703ed24520cd583498d49de11a320cda8b6c2ebf86bc14c377bed52cd83438ba2254b0e243d91ffcf5521f7f84d9445072e1c
+  data.tar.gz: 97ff4555610dc166e82d01b6f11200ce516d0d36acb701625519c73b6e2f31d9096ae53e19d863128246d240d54eb82ebbd6f60ed51309ef4a8ec45675b144fd

data/README.md

@@ -41,10 +41,10 @@ sudo dnf install libsodium-devel
 # Create a vault (prompts for passphrase)
 localvault init
 
-# Store secrets
-localvault set OPENAI_API_KEY "sk-proj-..."
-localvault set STRIPE_SECRET_KEY "sk_live_..."
-localvault set DATABASE_URL "postgres://localhost/myapp"
+# Store secrets without putting values in shell history / process args
+printf '%s' "$OPENAI_API_KEY" | localvault set OPENAI_API_KEY --stdin
+printf '%s' "$STRIPE_SECRET_KEY" | localvault set STRIPE_SECRET_KEY --stdin
+printf '%s' "$DATABASE_URL" | localvault set DATABASE_URL --stdin
 
 # Retrieve a secret (raw, pipeable)
 localvault get OPENAI_API_KEY
@@ -69,11 +69,15 @@ localvault exec -- rails server
 | Command | Description |
 |---------|-------------|
 | `init [NAME]` | Create a vault (Argon2id key derivation) |
-| `set KEY VALUE` | Store a secret (supports dot-notation: `project.KEY`) |
+| `set KEY --stdin` | Store a secret from stdin without argv/history exposure |
+| `set KEY [VALUE]` | Store a secret (positional value kept for compatibility) |
+| `set --group GROUP KEY --stdin` | Store a secret in a named group from stdin |
 | `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 |
@@ -140,6 +144,7 @@ backward compatibility but the top-level forms are preferred.
 |---------|-------------|
 | `install-mcp [CLIENT]` | Configure MCP server in claude-code, cursor, or windsurf |
 | `mcp` | Start MCP server (stdio transport) |
+| `doctor` | Check install and PATH readiness, including brew/asdf shadowing |
 
 All commands accept `--vault NAME` (or `-v NAME`) to target a specific vault. Default vault is `default`.
 
@@ -214,7 +219,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 +231,27 @@ localvault install-mcp claude-code
 # Unlock your vault for the session
 localvault unlock
 
+# Verify setup without starting the blocking stdio server
+localvault mcp --check
+
+# Diagnose brew/asdf PATH shadowing after upgrades
+localvault doctor
+
 # 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 +268,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,189 @@
+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 @error.is_a?(CLI::SetValueSourceError) && @error.kind == :multiple
+          "Error: #{@error.message}"
+        elsif group_save_attempt?
+          "Error: saving in a group needs GROUP, KEY, and VALUE."
+        elsif @error.is_a?(CLI::SetValueSourceError)
+          "Error: #{@error.message}"
+        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 set_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 set_suggestions
+        [
+          %(printf '%s' "$SECRET" | localvault set KEY --stdin),
+          "localvault set KEY VALUE",
+          *group_save_suggestions
+        ]
+      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