envspec 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28f13d06ae0882152222605d7b631f76f181c63fd91544ace2e53c33cc718ffa
-  data.tar.gz: 616d302174e177c0cce5864a4a12533710ea4823c528496a0e88a9f1466462be
+  metadata.gz: a8d59afdbad3765ce2c0516b2cfd710b877f3da5b123ff52a8c2423259ea1825
+  data.tar.gz: ddece928a9d0b0d20d3a096f7d6a51d36422ebd9300d86c2b80d1102b45734b5
 SHA512:
-  metadata.gz: 9b57dba76d1e5862c97548c1c0b040e1147ce3abac04e3034d9ae313f46c27fbbdb9a3105d776a7da2d5d066412a05373dfc19c769698222c25406f9d9b651d0
-  data.tar.gz: a19532006f8fc6822fa3a8b4ed7a17f4ba6485547233819e76c762df9a22b79b09a6ab52adf36401d760bc0ae0265939ad9e848d967ccb0f349b0572ca0db65d
+  metadata.gz: d0ec195a2b9eb390aaad8fc547371b3ed8251f599c8916e535fbcac5448cec6dd85ca28a86e537b01484cbd52766315eff2235d003f21c73ec111ba6acf33750
+  data.tar.gz: 3e77c5274e45e61cde1f1e8792a934efe7b3aaf3914ea7da4e1715750e9c1737a93c26f8899a4ac54b88ffa2fd97cb4b3428b5f8d6e665d76c1413dee8a153c0

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.1 — 2026-05-04
+
+- Refactor CLI into `EnvSpec::CLI` with proper subcommand structure (per-subcommand `OptionParser` with banners, options, and `-h` help). Still pure stdlib.
+- `envspec help <command>` and `envspec <command> -h` now show subcommand-specific usage.
+- Better exit codes (2 for usage errors, 1 for parse/validation errors, 0 for success).
+
 ## 0.1.0 — 2026-05-04
 
 Initial release.

data/exe/envspec

@@ -1,106 +1,3 @@
 #!/usr/bin/env ruby
-require "optparse"
 require "envspec"
-
-def die(msg, code = 1)
-  warn "envspec: #{msg}"
-  exit code
-end
-
-def usage
-  <<~USAGE
-    Usage: envspec <command> [options]
-
-    Commands:
-      lint <file>                 Parse and validate syntax of an env.spec file
-      check <file> [--env=NAME]   Check current ENV against the spec
-                                  (presence + type validation)
-      init [--force] [--output=PATH]
-                                  Scan repo for env var usages and generate env.spec
-
-    Options:
-      -h, --help     Show this help
-      -v, --version  Show version
-
-  USAGE
-end
-
-cmd = ARGV.shift
-
-case cmd
-when nil, "-h", "--help", "help"
-  puts usage
-  exit 0
-
-when "-v", "--version", "version"
-  puts EnvSpec::VERSION
-  exit 0
-
-when "lint"
-  file = ARGV.shift or die "lint: missing file argument\n\n#{usage}"
-  die "file not found: #{file}" unless File.exist?(file)
-  begin
-    EnvSpec.parse_file(file)
-    puts "✓ #{file} is valid"
-  rescue EnvSpec::ParseError => e
-    die e.message
-  end
-
-when "check"
-  file = nil
-  env = "*"
-  strict = false
-
-  parser = OptionParser.new do |o|
-    o.on("--env=NAME") { |v| env = v }
-    o.on("--strict") { strict = true }
-  end
-  rest = parser.parse(ARGV)
-  file = rest.shift or die "check: missing file argument\n\n#{usage}"
-  die "file not found: #{file}" unless File.exist?(file)
-
-  spec = begin
-    EnvSpec.parse_file(file)
-  rescue EnvSpec::ParseError => e
-    die e.message
-  end
-
-  begin
-    spec.validate!(ENV.to_h, env: env, strict: strict)
-    scope_label = env == "*" ? "shared" : env
-    puts "✓ ENV satisfies #{file} (env: #{scope_label})"
-  rescue EnvSpec::ValidationError => e
-    die e.message
-  end
-
-when "init"
-  force = false
-  output = "env.spec"
-  root = Dir.pwd
-
-  parser = OptionParser.new do |o|
-    o.on("--force") { force = true }
-    o.on("--output=PATH") { |v| output = v }
-    o.on("--root=PATH") { |v| root = v }
-  end
-  parser.parse(ARGV)
-
-  result = EnvSpec::Init.run(root: root, force: force, output: output)
-
-  unless result[:ok]
-    die "#{output} already exists (use --force to overwrite)" if result[:reason] == :exists
-    die "init failed: #{result[:reason]}"
-  end
-
-  puts "✓ Scanned in #{format('%.2fs', result[:elapsed])}"
-  puts "✓ Found #{result[:keys]} env vars across #{result[:files]} files"
-  puts "✓ Wrote #{result[:path]}"
-  puts ""
-  puts "Next steps:"
-  puts "  1. Edit #{output} — review heuristic suggestions, classify secrets"
-  puts "  2. Run `envspec lint #{output}` to validate"
-  puts "  3. Run `envspec check #{output}` to test against your current ENV"
-
-else
-  die "unknown command: #{cmd}\n\n#{usage}"
-end
+exit EnvSpec::CLI.run(ARGV)

data/lib/envspec/cli.rb

@@ -0,0 +1,179 @@
+require "optparse"
+
+class EnvSpec
+  class CLI
+    SUBCOMMANDS = %w[lint check init help version].freeze
+
+    def self.run(argv)
+      new.run(argv)
+    end
+
+    def run(argv)
+      argv = argv.dup
+      cmd = argv.shift
+
+      case cmd
+      when nil, "help", "-h", "--help"
+        print_help(argv.first)
+        0
+      when "version", "-v", "--version"
+        puts EnvSpec::VERSION
+        0
+      when "lint"
+        cmd_lint(argv)
+      when "check"
+        cmd_check(argv)
+      when "init"
+        cmd_init(argv)
+      else
+        warn "envspec: unknown command '#{cmd}'"
+        warn ""
+        print_help
+        2
+      end
+    rescue OptionParser::ParseError => e
+      warn "envspec: #{e.message}"
+      2
+    rescue EnvSpec::ParseError, EnvSpec::ValidationError => e
+      warn "envspec: #{e.message}"
+      1
+    end
+
+    private
+
+    # ── help ──────────────────────────────────────────────────────────
+
+    def print_help(topic = nil)
+      case topic
+      when "lint"  then puts lint_parser.help
+      when "check" then puts check_parser({}).help
+      when "init"  then puts init_parser({}).help
+      else              puts global_help
+      end
+    end
+
+    def global_help
+      <<~HELP
+        Usage: envspec <command> [options]
+
+        Commands:
+          lint <file>            Parse and validate syntax of an env.spec file
+          check <file>           Check current ENV against the spec
+          init                   Scan repo for env vars and generate env.spec
+          help [command]         Show help for a command
+          version                Show version
+
+        Run `envspec help <command>` for command-specific options.
+        Docs: https://github.com/repleadfy/envspec
+      HELP
+    end
+
+    # ── lint ──────────────────────────────────────────────────────────
+
+    def lint_parser
+      OptionParser.new do |o|
+        o.banner = "Usage: envspec lint <file>"
+        o.separator ""
+        o.separator "Parses an env.spec file and reports any syntax errors."
+        o.separator ""
+        o.separator "Options:"
+        o.on("-h", "--help") { puts o; exit 0 }
+      end
+    end
+
+    def cmd_lint(argv)
+      rest = lint_parser.parse(argv)
+      file = rest.shift or (warn lint_parser.help; return 2)
+      die_unless_file(file)
+
+      EnvSpec.parse_file(file)
+      puts "✓ #{file} is valid"
+      0
+    end
+
+    # ── check ─────────────────────────────────────────────────────────
+
+    def check_parser(opts)
+      OptionParser.new do |o|
+        o.banner = "Usage: envspec check <file> [options]"
+        o.separator ""
+        o.separator "Validates the current process ENV against an env.spec file."
+        o.separator "Checks presence of required keys and that values match declared types."
+        o.separator ""
+        o.separator "Options:"
+        o.on("--env=NAME", "Env scope to validate against (default: shared/*)") do |v|
+          opts[:env] = v
+        end
+        o.on("--strict", "Treat unknown env vars as problems") do
+          opts[:strict] = true
+        end
+        o.on("-h", "--help") { puts o; exit 0 }
+      end
+    end
+
+    def cmd_check(argv)
+      opts = { env: "*", strict: false }
+      rest = check_parser(opts).parse(argv)
+      file = rest.shift or (warn check_parser(opts).help; return 2)
+      die_unless_file(file)
+
+      spec = EnvSpec.parse_file(file)
+      spec.validate!(ENV.to_h, env: opts[:env], strict: opts[:strict])
+
+      label = opts[:env] == "*" ? "shared" : opts[:env]
+      puts "✓ ENV satisfies #{file} (env: #{label})"
+      0
+    end
+
+    # ── init ──────────────────────────────────────────────────────────
+
+    def init_parser(opts)
+      OptionParser.new do |o|
+        o.banner = "Usage: envspec init [options]"
+        o.separator ""
+        o.separator "Scans the current directory tree for env var usages across"
+        o.separator "Ruby/Python/JS/Go/Shell sources and writes a starter env.spec."
+        o.separator ""
+        o.separator "Options:"
+        o.on("--force", "Overwrite an existing env.spec") { opts[:force] = true }
+        o.on("--output=PATH", "Output file (default: env.spec)") { |v| opts[:output] = v }
+        o.on("--root=PATH",   "Directory to scan (default: cwd)") { |v| opts[:root] = v }
+        o.on("-h", "--help") { puts o; exit 0 }
+      end
+    end
+
+    def cmd_init(argv)
+      opts = { force: false, output: "env.spec", root: Dir.pwd }
+      init_parser(opts).parse(argv)
+
+      result = EnvSpec::Init.run(root: opts[:root], force: opts[:force], output: opts[:output])
+
+      unless result[:ok]
+        if result[:reason] == :exists
+          warn "envspec: #{opts[:output]} already exists (use --force to overwrite)"
+          return 1
+        end
+        warn "envspec: init failed: #{result[:reason]}"
+        return 1
+      end
+
+      puts "✓ Scanned in #{format('%.2fs', result[:elapsed])}"
+      puts "✓ Found #{result[:keys]} env vars across #{result[:files]} files"
+      puts "✓ Wrote #{result[:path]}"
+      puts ""
+      puts "Next steps:"
+      puts "  1. Edit #{opts[:output]} — review heuristic suggestions, classify secrets"
+      puts "  2. Run `envspec lint #{opts[:output]}` to validate"
+      puts "  3. Run `envspec check #{opts[:output]}` to test against your current ENV"
+      0
+    end
+
+    # ── helpers ───────────────────────────────────────────────────────
+
+    def die_unless_file(file)
+      return if File.exist?(file)
+      warn "envspec: file not found: #{file}"
+      exit 1
+    end
+  end
+end

data/lib/envspec/version.rb

@@ -1,3 +1,3 @@
 class EnvSpec
-  VERSION = "0.1.0".freeze
+  VERSION = "0.1.1".freeze
 end

data/lib/envspec.rb

@@ -4,3 +4,4 @@ require_relative "envspec/entry"
 require_relative "envspec/parser"
 require_relative "envspec/validator"
 require_relative "envspec/init"
+require_relative "envspec/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: envspec
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Leadfy
@@ -67,6 +67,7 @@ files:
 - README.md
 - exe/envspec
 - lib/envspec.rb
+- lib/envspec/cli.rb
 - lib/envspec/entry.rb
 - lib/envspec/errors.rb
 - lib/envspec/heuristics.rb