vaultez-cli 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f51a620534fdfedc6d42e56c4bfadf38f0705298f984a96326de81967d6b893
-  data.tar.gz: 5cd7deade6d544287ebe947bc9ad18031ab014dcdd3bd7b74b0de7b489f9f183
+  metadata.gz: 7ec4178a4e79116eef6ff1b13b8db47f134cb9c57ed0fa85e727871886acb2fa
+  data.tar.gz: 23ee0ad5bf641a03a7a8cc3763ab1b2c140c50a07927dac808eded42d2e7a421
 SHA512:
-  metadata.gz: afe76438bda1a5bbffe795105685b7ef952e96012c9bb8841827d6d25fb75b00aeb83d7c3e88aaa16a5617d1ec73bf868eb43de2be0e1441f28cf522938df5c2
-  data.tar.gz: 8f5617fbe1654c3ffb4b38e40cb623d656c610c36a0f0cb0019bf90b3c12e121bb4fc733f3524af5bc89dbe2a1242d437f2cd06d79fd9969210db27e88b86fb2
+  metadata.gz: b4e00d6f19821fffe29bfac9430b125a9dbab05f8e3a2d53f73bdae8e4c6adb820999ef32d563d3825601978df128d31ef827b33a07aa267d21f1e4c182f7e00
+  data.tar.gz: e53532d610033a006a3f04e8153d35e081b1605fd55ed7f5de4b813a0cf67f4f3191b0206844cd068a0e14c0912eed9d4e241aa1e942e21149d77342767a4873

data/lib/vaultez/cli.rb

@@ -1,5 +1,6 @@
 require "thor"
 require_relative "version"
+require_relative "output"
 require_relative "commands/auth"
 require_relative "commands/fetch"
 require_relative "commands/config_command"
@@ -12,6 +13,12 @@ module Vaultez
 
     map %w[--version -v] => :__version
 
+    # Usage errors (unknown flag, bad --format) must exit non-zero, or
+    # `vaultez fetch ... > .env && ./start.sh` carries on as if it worked.
+    def self.exit_on_failure?
+      true
+    end
+
     desc "login", "Authenticate with email, password, and 2FA code"
     long_desc <<~DESC, wrap: false
       Authenticate with your Vaultez account. You will be prompted for your
@@ -54,6 +61,26 @@ module Vaultez
         VAULTEZ_TOKEN=vz_... vaultez fetch
         VAULTEZ_TOKEN=vz_... vaultez fetch --secret="DATABASE_URL"
 
+      OUTPUT FORMATS (--format, for a project's secrets):
+        env      KEY='value' lines, quoted so they are safe to eval or source (default)
+                   eval "$(vaultez fetch --project="Backend")"
+                   set -a; source <(vaultez fetch --project="Backend"); set +a
+        shell    export KEY='value' lines
+        dotenv   a .env file for dotenv, Next.js, Vite or Docker Compose
+                   vaultez fetch --project="Backend" --format=dotenv > .env.local
+        github   entries for $GITHUB_ENV, multi-line values included
+                   vaultez fetch --format=github >> "$GITHUB_ENV"
+        json     a JSON array of {id, name, value} (same as --json)
+
+      Secrets whose names aren't valid variable names (letters, numbers and _,
+      not starting with a number) are skipped, with a warning on stderr. They
+      are still included in json output.
+
+      --secret prints just the value, unquoted, or a JSON object with --format=json.
+
+      Stdout only ever carries data. Errors and notices such as "No secrets
+      found" go to stderr, and errors exit with status 1.
+
       Project tokens can be created in the Tokens tab of your project settings.
       Always pass the token via the VAULTEZ_TOKEN environment variable, never
       as a command-line flag — CLI arguments are visible to other local users
@@ -64,7 +91,8 @@ module Vaultez
     option :projects,  type: :boolean, desc: "List projects in a company"
     option :project,   type: :string,  desc: "Project name"
     option :secret,    type: :string,  desc: "Secret name (returns value only)"
-    option :json,      type: :boolean, desc: "Output as JSON (errors go to stderr)"
+    option :format,    type: :string,  enum: Vaultez::Output::FORMATS, desc: "Output format (default: env)"
+    option :json,      type: :boolean, desc: "Output as JSON (same as --format=json)"
     def fetch; super; end
 
     desc "config", "Set default company or token"

data/lib/vaultez/commands/auth.rb

@@ -20,11 +20,11 @@ module Vaultez
         Vaultez::Config.set("token", response["token"])
         puts "Logged in successfully."
       rescue Vaultez::TwoFactorRequiredError => error
-        puts "Error: #{error.message}"
-        puts "Set up two-factor authentication at https://vaultez.app/two_factor/new"
+        warn "Error: #{error.message}"
+        warn "Set up two-factor authentication at https://vaultez.app/two_factor/new"
         exit 1
       rescue Vaultez::AuthenticationError => error
-        puts "Error: #{error.message}"
+        warn "Error: #{error.message}"
         exit 1
       end
 
@@ -34,7 +34,7 @@ module Vaultez
         Vaultez::Config.clear
         puts "Logged out successfully."
       rescue Vaultez::NotAuthenticatedError => error
-        puts "Error: #{error.message}"
+        warn "Error: #{error.message}"
         exit 1
       end
     end

data/lib/vaultez/commands/config_command.rb

@@ -8,21 +8,21 @@ module Vaultez
           company   = companies.find { |company| company["name"] == options[:"default-company"] }
 
           unless company
-            puts "Error: company \"#{options[:"default-company"]}\" not found."
+            warn "Error: company \"#{options[:"default-company"]}\" not found."
             exit 1
           end
 
           Vaultez::Config.set("default_company", company["name"])
           puts "Default company set to \"#{company["name"]}\"."
         else
-          puts "No config option provided. See `vaultez help config`."
+          warn "No config option provided. See `vaultez help config`."
           exit 1
         end
       rescue Vaultez::NotAuthenticatedError => error
-        puts "Error: #{error.message}"
+        warn "Error: #{error.message}"
         exit 1
       rescue Vaultez::ApiError => error
-        puts "Error: #{error.message}"
+        warn "Error: #{error.message}"
         exit 1
       end
     end

data/lib/vaultez/commands/fetch.rb

@@ -1,4 +1,5 @@
 require "json"
+require_relative "../output"
 
 module Vaultez
   module Commands
@@ -29,13 +30,40 @@ module Vaultez
 
       private
 
+      # Stdout carries only data, so `vaultez fetch > .env` never writes an
+      # error or a notice into the file. Everything else goes to stderr.
       def fail!(message)
-        if options[:json]
-          warn "Error: #{message}"
+        warn "Error: #{message}"
+        exit 1
+      end
+
+      def output_format
+        @output_format ||= begin
+          format = options[:format]
+          if options[:json] && format && format != "json"
+            fail!("--json can't be combined with --format=#{format}.")
+          end
+          format || (options[:json] ? "json" : Vaultez::Output::DEFAULT_FORMAT)
+        end
+      end
+
+      def json?
+        output_format == "json"
+      end
+
+      def print_secret_value(secret)
+        if json?
+          puts secret.to_json
         else
-          puts "Error: #{message}"
+          print secret["value"]
         end
-        exit 1
+      end
+
+      def print_secrets(secrets, empty_message)
+        warn empty_message if secrets.empty?
+        text, warnings = Vaultez::Output.render(secrets, output_format)
+        print text
+        warnings.each { |message| warn "Warning: #{message}" }
       end
 
       def fetch_with_project_token(client)
@@ -45,22 +73,9 @@ module Vaultez
           unless secret
             fail!("secret \"#{options[:secret]}\" not found.")
           end
-          if options[:json]
-            puts secret.to_json
-          else
-            print secret["value"]
-          end
+          print_secret_value(secret)
         else
-          secrets = fetch_all_secrets_for_token(client)
-          if options[:json]
-            puts secrets.to_json
-            return
-          end
-          if secrets.empty?
-            puts "No secrets found."
-            return
-          end
-          secrets.each { |s| puts "#{s["name"]}=#{s["value"]}" }
+          print_secrets(fetch_all_secrets_for_token(client), "No secrets found.")
         end
       end
 
@@ -80,12 +95,12 @@ module Vaultez
 
       def fetch_companies(client)
         companies = client.companies
-        if options[:json]
+        if json?
           puts companies.to_json
           return
         end
         if companies.empty?
-          puts "No companies found."
+          warn "No companies found."
           return
         end
         puts "Companies:"
@@ -97,12 +112,12 @@ module Vaultez
       def fetch_projects(client)
         company  = resolve_company(client)
         projects = client.projects(company["id"])
-        if options[:json]
+        if json?
           puts projects.to_json
           return
         end
         if projects.empty?
-          puts "No projects found in #{company["name"]}."
+          warn "No projects found in #{company["name"]}."
           return
         end
         puts "Projects in #{company["name"]}:"
@@ -115,17 +130,7 @@ module Vaultez
         company = resolve_company(client)
         project = resolve_project(client, company)
         secrets = client.secrets(project["id"])
-        if options[:json]
-          puts secrets.to_json
-          return
-        end
-        if secrets.empty?
-          puts "No secrets found in #{project["name"]}."
-          return
-        end
-        secrets.each do |secret|
-          puts "#{secret["name"]}=#{secret["value"]}"
-        end
+        print_secrets(secrets, "No secrets found in #{project["name"]}.")
       end
 
       def fetch_secret(client)
@@ -138,11 +143,7 @@ module Vaultez
           fail!("secret \"#{options[:secret]}\" not found in #{project["name"]}.")
         end
 
-        if options[:json]
-          puts secret.to_json
-        else
-          print secret["value"]
-        end
+        print_secret_value(secret)
       end
 
       def resolve_company(client)

data/lib/vaultez/output.rb

@@ -0,0 +1,88 @@
+require "json"
+require "securerandom"
+
+module Vaultez
+  # Renders a project's secrets for the formats `vaultez fetch --format=...`
+  # accepts. Every format except json must be safe to hand to its consumer
+  # as-is: a secret value is data written by any project editor, so it must
+  # never be able to run a command, end its own line early, or set a second
+  # variable on the machine of whoever sources the output.
+  module Output
+    FORMATS        = %w[env shell dotenv github json].freeze
+    DEFAULT_FORMAT = "env".freeze
+
+    VARIABLE_NAME = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+
+    module_function
+
+    def valid_name?(name)
+      name.is_a?(String) && VARIABLE_NAME.match?(name)
+    end
+
+    # Returns [text, warnings]; the caller prints the warnings on stderr.
+    # Secrets whose names can't be variable names are left out of the
+    # non-json formats, since no shell or dotenv parser would accept the line.
+    def render(secrets, format)
+      return [JSON.generate(secrets) + "\n", []] if format == "json"
+
+      warnings = []
+      lines = secrets.filter_map do |secret|
+        name, value = secret["name"], secret["value"].to_s
+        unless valid_name?(name)
+          warnings << "skipped secret #{name.inspect}: not a valid variable name. " \
+                      "Rename it to use only letters, numbers and _ (not starting with a number), or use --format=json."
+          next
+        end
+        if format == "dotenv" && !portable_in_dotenv?(value)
+          warnings << "secret #{name.inspect} contains ' together with \", \\ or $. Ruby dotenv and " \
+                      "Docker Compose read it correctly; Node's dotenv keeps the backslash escapes."
+        end
+        line(name, value, format)
+      end
+      [lines.join, warnings]
+    end
+
+    def line(name, value, format)
+      case format
+      when "env"    then "#{name}=#{shell_quote(value)}\n"
+      when "shell"  then "export #{name}=#{shell_quote(value)}\n"
+      when "dotenv" then "#{name}=#{dotenv_quote(value)}\n"
+      when "github" then github_entry(name, value)
+      else raise ArgumentError, "unknown format: #{format}"
+      end
+    end
+
+    # POSIX single quotes: nothing inside is special except the closing
+    # quote itself, which is written as '\'' (close, escaped quote, reopen).
+    def shell_quote(value)
+      "'#{value.gsub("'", %q('\\\\''))}'"
+    end
+
+    # Single-quoted values, line breaks included, are literal in every
+    # common dotenv parser (Ruby dotenv, Node dotenv, Docker Compose), so use
+    # them whenever the value has no ' of its own. Double quotes are next:
+    # also literal as long as there's no ", \ or $ to interpret. Only a value
+    # with both needs escapes, and parsers disagree on those: Ruby dotenv and
+    # Compose unescape \" \\ \$ (and Ruby runs $(...) if $ isn't escaped),
+    # while Node's dotenv leaves the backslashes in.
+    def dotenv_quote(value)
+      return "'#{value}'" unless value.include?("'")
+      return "\"#{value}\"" unless value.match?(/["\\$]/)
+
+      "\"#{value.gsub(/["\\$]/) { |char| "\\#{char}" }}\""
+    end
+
+    def portable_in_dotenv?(value)
+      !(value.include?("'") && value.match?(/["\\$]/))
+    end
+
+    # GitHub's multiline syntax for $GITHUB_ENV. A random delimiter means a
+    # value can't close the block early and smuggle in another variable
+    # (e.g. NODE_OPTIONS) for later workflow steps.
+    def github_entry(name, value)
+      delimiter = "VAULTEZ_EOF_#{SecureRandom.hex(16)}"
+      delimiter = "VAULTEZ_EOF_#{SecureRandom.hex(16)}" while value.include?(delimiter)
+      "#{name}<<#{delimiter}\n#{value}\n#{delimiter}\n"
+    end
+  end
+end

data/lib/vaultez/version.rb

@@ -1,3 +1,3 @@
 module Vaultez
-  VERSION = "0.3.2"
+  VERSION = "0.4.0"
 end

data/lib/vaultez.rb

@@ -1,5 +1,6 @@
 require_relative "vaultez/version"
 require_relative "vaultez/errors"
+require_relative "vaultez/output"
 require_relative "vaultez/config"
 require_relative "vaultez/client"
 require_relative "vaultez/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vaultez-cli
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Nur Ketene
@@ -39,6 +39,7 @@ files:
 - lib/vaultez/commands/fetch.rb
 - lib/vaultez/config.rb
 - lib/vaultez/errors.rb
+- lib/vaultez/output.rb
 - lib/vaultez/version.rb
 homepage: https://vaultez.app
 licenses:
@@ -58,7 +59,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: CLI tool for Vaultez — manage your secrets from the terminal
 test_files: []