envspec 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28f13d06ae0882152222605d7b631f76f181c63fd91544ace2e53c33cc718ffa
-  data.tar.gz: 616d302174e177c0cce5864a4a12533710ea4823c528496a0e88a9f1466462be
+  metadata.gz: 876d54d300e49212e28fe8ff57ed3b05fc96ef168a2b668ac71ba6f2c9421945
+  data.tar.gz: d7d25d84e2fc60d898070bd13ce0cfebe891612035975695e16c31b10eedd319
 SHA512:
-  metadata.gz: 9b57dba76d1e5862c97548c1c0b040e1147ce3abac04e3034d9ae313f46c27fbbdb9a3105d776a7da2d5d066412a05373dfc19c769698222c25406f9d9b651d0
-  data.tar.gz: a19532006f8fc6822fa3a8b4ed7a17f4ba6485547233819e76c762df9a22b79b09a6ab52adf36401d760bc0ae0265939ad9e848d967ccb0f349b0572ca0db65d
+  metadata.gz: 7a4582455ef7d02a5d190d8bb16173ddda9e67aacbe701fe29b16879df6e404dad3d6106ff792913527677253511c1c0428e3cfb20dccc41b348f36125a06234
+  data.tar.gz: af136637aa5cd6f4e35129dbfe787ce59ec245901b5980b0a6b4df06a8790885ce1e59426ace7ececb9f095bca1d94aafc00cf85b7386a07ccae2054830bfea3

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.2 — 2026-05-04
+
+- Split CLI into one file per subcommand under `lib/envspec/cli/`:
+  `command.rb` (base class), `lint.rb`, `check.rb`, `init.rb`. Adding a new
+  subcommand is now: write a class inheriting from `EnvSpec::CLI::Command`,
+  register it in `EnvSpec::CLI::COMMANDS`.
+- Aligned formatting in global help.
+
+## 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/check.rb

@@ -0,0 +1,33 @@
+require_relative "command"
+
+class EnvSpec
+  class CLI
+    class Check < Command
+      name "check"
+      summary "Check current ENV against an env.spec"
+      banner "Usage: envspec check <file> [options]"
+      description <<~DESC
+        Validates the current process ENV against an env.spec file.
+        Checks presence of required keys and that values match declared types.
+      DESC
+
+      def default_opts
+        { env: "*", strict: false }
+      end
+
+      def configure(o, opts)
+        o.on("--env=NAME", "Env scope to validate against (default: shared/*)") { |v| opts[:env] = v }
+        o.on("--strict", "Treat unknown env vars as problems")                  { opts[:strict] = true }
+      end
+
+      def call(rest, opts)
+        file = require_file(rest.shift)
+        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
+    end
+  end
+end

data/lib/envspec/cli/command.rb

@@ -0,0 +1,97 @@
+require "optparse"
+
+class EnvSpec
+  class CLI
+    # Base class for a single CLI subcommand.
+    #
+    # Subclasses declare:
+    #   - name     (string, e.g. "lint")
+    #   - summary  (one-line description for global help)
+    #   - configure(parser, opts) — define options on the OptionParser
+    #   - call(argv, opts) — execute; return exit code
+    class Command
+      class << self
+        def name(value = nil)
+          @name = value if value
+          @name
+        end
+
+        def summary(value = nil)
+          @summary = value if value
+          @summary
+        end
+
+        def banner(value = nil)
+          @banner = value if value
+          @banner
+        end
+
+        def description(value = nil)
+          @description = value if value
+          @description
+        end
+      end
+
+      def initialize
+        @opts = default_opts
+      end
+
+      def default_opts
+        {}
+      end
+
+      def parser
+        @parser ||= build_parser
+      end
+
+      def build_parser
+        OptionParser.new do |o|
+          o.banner = self.class.banner || "Usage: envspec #{self.class.name}"
+          if self.class.description
+            o.separator ""
+            self.class.description.each_line { |ln| o.separator ln.chomp }
+          end
+          o.separator ""
+          o.separator "Options:"
+          configure(o, @opts)
+          o.on("-h", "--help", "Show help for this command") { puts o; exit 0 }
+        end
+      end
+
+      def configure(_parser, _opts)
+        # subclass override
+      end
+
+      def help
+        parser.help
+      end
+
+      # Subclasses override `call(argv, opts)`. The dispatcher invokes `run(argv)`.
+      def run(argv)
+        rest = parser.parse(argv)
+        call(rest, @opts)
+      end
+
+      def call(_rest, _opts)
+        raise NotImplementedError
+      end
+
+      protected
+
+      def die(msg, code = 1)
+        warn "envspec: #{msg}"
+        code
+      end
+
+      def require_file(file)
+        return file if file && File.exist?(file)
+        if file.nil?
+          warn parser.help
+          exit 2
+        end
+        warn "envspec: file not found: #{file}"
+        exit 1
+      end
+    end
+  end
+end

data/lib/envspec/cli/init.rb

@@ -0,0 +1,46 @@
+require_relative "command"
+
+class EnvSpec
+  class CLI
+    class Init < Command
+      name "init"
+      summary "Scan repo for env vars and generate env.spec"
+      banner "Usage: envspec init [options]"
+      description <<~DESC
+        Scans the current directory tree for env var usages across
+        Ruby/Python/JS/Go/Shell sources and writes a starter env.spec.
+      DESC
+
+      def default_opts
+        { force: false, output: "env.spec", root: Dir.pwd }
+      end
+
+      def configure(o, opts)
+        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 }
+      end
+
+      def call(_rest, opts)
+        result = EnvSpec::Init.run(root: opts[:root], force: opts[:force], output: opts[:output])
+
+        unless result[:ok]
+          if result[:reason] == :exists
+            return die("#{opts[:output]} already exists (use --force to overwrite)", 1)
+          end
+          return die("init failed: #{result[:reason]}", 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
+    end
+  end
+end

data/lib/envspec/cli/lint.rb

@@ -0,0 +1,19 @@
+require_relative "command"
+
+class EnvSpec
+  class CLI
+    class Lint < Command
+      name "lint"
+      summary "Parse and validate syntax of an env.spec file"
+      banner "Usage: envspec lint <file>"
+      description "Parses an env.spec file and reports any syntax errors."
+
+      def call(rest, _opts)
+        file = require_file(rest.shift)
+        EnvSpec.parse_file(file)
+        puts "✓ #{file} is valid"
+        0
+      end
+    end
+  end
+end

data/lib/envspec/cli.rb

@@ -0,0 +1,80 @@
+require_relative "cli/command"
+require_relative "cli/lint"
+require_relative "cli/check"
+require_relative "cli/init"
+
+class EnvSpec
+  # Dispatcher for `envspec` subcommands.
+  #
+  # Each subcommand is a class under EnvSpec::CLI inheriting from
+  # EnvSpec::CLI::Command. Register new commands by adding them to COMMANDS
+  # below and creating a file under lib/envspec/cli/.
+  class CLI
+    COMMANDS = {
+      "lint"  => Lint,
+      "check" => Check,
+      "init"  => Init,
+    }.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)
+        return 0
+      when "version", "-v", "--version"
+        puts EnvSpec::VERSION
+        return 0
+      end
+
+      klass = COMMANDS[cmd]
+      unless klass
+        warn "envspec: unknown command '#{cmd}'"
+        warn ""
+        print_help
+        return 2
+      end
+
+      klass.new.run(argv)
+    rescue OptionParser::ParseError => e
+      warn "envspec: #{e.message}"
+      2
+    rescue EnvSpec::ParseError, EnvSpec::ValidationError => e
+      warn "envspec: #{e.message}"
+      1
+    end
+
+    private
+
+    def print_help(topic = nil)
+      if topic && (klass = COMMANDS[topic])
+        puts klass.new.help
+        return
+      end
+      puts global_help
+    end
+
+    def global_help
+      rows = COMMANDS.map { |n, k| [n, k.summary] }
+      rows << ["help",    "Show help for a command"]
+      rows << ["version", "Show version"]
+      width = rows.map { |r| r[0].length }.max
+
+      lines = []
+      lines << "Usage: envspec <command> [options]"
+      lines << ""
+      lines << "Commands:"
+      rows.each { |name, summary| lines << format("  %-#{width}s   %s", name, summary) }
+      lines << ""
+      lines << "Run `envspec help <command>` (or `envspec <command> -h`) for command-specific options."
+      lines << "Docs: https://github.com/repleadfy/envspec"
+      lines.join("\n")
+    end
+  end
+end

data/lib/envspec/version.rb

@@ -1,3 +1,3 @@
 class EnvSpec
-  VERSION = "0.1.0".freeze
+  VERSION = "0.1.2".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.2
 platform: ruby
 authors:
 - Leadfy
@@ -67,6 +67,11 @@ files:
 - README.md
 - exe/envspec
 - lib/envspec.rb
+- lib/envspec/cli.rb
+- lib/envspec/cli/check.rb
+- lib/envspec/cli/command.rb
+- lib/envspec/cli/init.rb
+- lib/envspec/cli/lint.rb
 - lib/envspec/entry.rb
 - lib/envspec/errors.rb
 - lib/envspec/heuristics.rb