devex 0.3.5

data/lib/devex/tool.rb

@@ -0,0 +1,374 @@
+# frozen_string_literal: true
+
+module Devex
+  # Represents a CLI tool/command with its metadata, flags, args, and subtools
+  class Tool
+    attr_accessor :builtin, :desc, :long_desc, :run_block, :source_code, :source_file, :source_proc
+    attr_reader :name, :parent, :subtools, :flags, :args, :mixins
+
+    # Global flag specs that tools cannot override
+    # These are handled by CLI before tool flag parsing
+    RESERVED_FLAG_SPECS = %w[
+      -f --format
+      -v --verbose --no-verbose
+      -q --quiet --no-quiet
+      --color --no-color
+      --dx-version --dx-from-dir
+    ].freeze
+
+    def initialize(name, parent: nil)
+      @name        = name
+      @parent      = parent
+      @desc        = nil
+      @long_desc   = nil
+      @flags       = []
+      @args        = []
+      @subtools    = {}
+      @run_block   = nil
+      @mixins      = []
+      @builtin     = nil # reference to builtin tool if this is an override
+      @source_code = nil
+      @source_file = nil
+      @source_proc = nil
+    end
+
+    # Full command path (e.g., ["version", "bump"])
+    def full_path
+      if parent
+        parent.full_path + [name]
+      else
+        (name ? [name] : [])
+      end
+    end
+
+    # Full command string (e.g., "version bump")
+    def full_name = full_path.join(" ")
+
+    # Define a flag
+    # Examples:
+    #   flag :verbose, "-v", "--verbose", desc: "Enable verbose output"
+    #   flag :file, "-f FILE", "--file=FILE", desc: "Input file"
+    def flag(name, *specs, desc: nil, default: nil) = @flags << Flag.new(name, specs, desc: desc, default: default)
+
+    # Check that flag specs don't conflict with global flags (called at execute time)
+    def validate_flags!
+      @flags.each do |flag|
+        flag.specs.each do |spec|
+          # Extract the flag part (before space or =)
+          flag_part = spec.split(/[\s=]/).first
+          if RESERVED_FLAG_SPECS.include?(flag_part)
+            raise Error, <<~ERR.chomp
+              Tool '#{full_name}': flag '#{flag_part}' conflicts with global flag
+
+              Global flags like #{flag_part} are handled before tool execution.
+              Your tool can access the global value via:
+                verbose?                 # for -v/--verbose
+                global_options[:format]  # for -f/--format
+                global_options[:quiet]   # for -q/--quiet
+
+              To fix: remove this flag definition or use a different flag name.
+            ERR
+          end
+        end
+      end
+    end
+
+    # Define a required positional argument
+    def required_arg(name, desc: nil) = @args << Arg.new(name, required: true, desc: desc)
+
+    # Define an optional positional argument
+    def optional_arg(name, desc: nil, default: nil) = @args << Arg.new(name, required: false, desc: desc, default: default)
+
+    # Define remaining args (variadic)
+    def remaining_args(name, desc: nil) = @args << Arg.new(name, required: false, desc: desc, remaining: true)
+
+    # Add a subtool
+    def add_subtool(tool) = @subtools[tool.name] = tool
+
+    # Find a subtool by name
+    def subtool(name) = @subtools[name]
+
+    # Include a mixin by name
+    def include_mixin(name) = @mixins << name
+
+    # Set builtin reference for override support
+
+    # Parse arguments and execute the tool
+    def execute(argv, cli)
+      # Check for subcommand first
+      if argv.any? && (sub = subtool(argv.first))
+        return sub.execute(argv[1..], cli)
+      end
+
+      # Validate flags don't conflict with global flags
+      validate_flags!
+
+      # Parse flags and args
+      context = ExecutionContext.new(self, cli)
+      context.parse(argv)
+
+      # Check for required args
+      @args.select(&:required).each do |arg|
+        raise Error, "Missing required argument: #{arg.name}" unless context.options.key?(arg.name)
+      end
+
+      # Execute - re-evaluate source in context so `def run` has access to cli, options, etc.
+      if @source_code
+        # Re-evaluate the source code in the execution context
+        # This makes all def methods available with proper context
+        context.instance_eval(@source_code, @source_file || "(tool)")
+        if context.respond_to?(:run)
+          context.run
+        elsif @subtools.any?
+          cli.show_help(self)
+        else
+          raise Error, "Tool '#{full_name}' has no run method"
+        end
+      elsif @source_proc
+        # For nested tools defined with blocks.
+        # First eval the source file (if any) to define helper methods,
+        # then eval the block to define this subtool's run method.
+        if @source_file && File.exist?(@source_file)
+          context.instance_eval(File.read(@source_file), @source_file)
+        end
+        context.instance_eval(&@source_proc)
+        if context.respond_to?(:run)
+          context.run
+        elsif @subtools.any?
+          cli.show_help(self)
+        else
+          raise Error, "Tool '#{full_name}' has no run method"
+        end
+      elsif @run_block
+        context.instance_exec(&@run_block)
+      elsif @subtools.any?
+        cli.show_help(self)
+      else
+        raise Error, "Tool '#{full_name}' has no implementation"
+      end
+    end
+
+    # Generate help text
+    def help_text(executable_name = "dx")
+      lines = []
+
+      # Usage line
+      cmd         = [executable_name, *full_path].join(" ")
+      usage_parts = [cmd]
+      usage_parts << "[OPTIONS]" if @flags.any?
+      @args.each do |arg|
+        usage_parts << if arg.remaining
+                         "[#{arg.name.to_s.upcase}...]"
+                       elsif arg.required
+                         arg.name.to_s.upcase
+                       else
+                         "[#{arg.name.to_s.upcase}]"
+                       end
+      end
+      usage_parts << "COMMAND" if @subtools.any?
+
+      lines << "Usage: #{usage_parts.join(' ')}"
+      lines << ""
+
+      # Description
+      if @desc
+        lines << @desc
+        lines << ""
+      end
+
+      if @long_desc
+        lines << @long_desc
+        lines << ""
+      end
+
+      # Subcommands
+      if @subtools.any?
+        lines << "Commands:"
+        max_name = @subtools.keys.map(&:length).max
+        @subtools.sort.each do |name, tool|
+          desc_text = tool.desc || ""
+          lines << "  #{name.ljust(max_name)}  #{desc_text}"
+        end
+        lines << ""
+      end
+
+      # Flags
+      if @flags.any?
+        lines << "Options:"
+        @flags.each do |flag|
+          flag_str = flag.specs.join(", ")
+          desc_text = flag.desc || ""
+          lines << "  #{flag_str}"
+          lines << "      #{desc_text}" if desc_text != ""
+        end
+        lines << ""
+      end
+
+      # Args
+      if @args.any?
+        lines << "Arguments:"
+        @args.each do |arg|
+          name_str = arg.name.to_s.upcase
+          name_str += "..." if arg.remaining
+          req_str = arg.required ? "(required)" : "(optional)"
+          desc_text = arg.desc ? " - #{arg.desc}" : ""
+          lines << "  #{name_str} #{req_str}#{desc_text}"
+        end
+        lines << ""
+      end
+
+      lines.join("\n")
+    end
+  end
+
+  # Represents a flag definition
+  class Flag
+    attr_reader :name, :specs, :desc, :default
+
+    def initialize(name, specs, desc: nil, default: nil)
+      @name    = name
+      @specs   = specs
+      @desc    = desc
+      @default = default
+    end
+
+    # Does this flag take an argument?
+    def takes_argument? = @specs.any? { |s| s.include?(" ") || s.include?("=") }
+  end
+
+  # Represents a positional argument definition
+  class Arg
+    attr_reader :name, :required, :desc, :default, :remaining
+
+    def initialize(name, required:, desc: nil, default: nil, remaining: false)
+      @name      = name
+      @required  = required
+      @desc      = desc
+      @default   = default
+      @remaining = remaining
+    end
+  end
+
+  # Execution context - the 'self' when a tool runs
+  class ExecutionContext
+    include Exec  # All tools have access to cmd, capture, spawn, etc.
+
+    attr_reader :options, :cli
+
+    def initialize(tool, cli)
+      @tool    = tool
+      @cli     = cli
+      @options = {}
+
+      # Set defaults for flags
+      tool.flags.each do |flag|
+        @options[flag.name] = if !flag.default.nil?
+                                flag.default
+                              elsif !flag.takes_argument?
+                                false  # Boolean flags default to false
+                              end
+      end
+      tool.args.each do |arg|
+        @options[arg.name] = arg.default unless arg.default.nil?
+      end
+    end
+
+    # Parse argv into options, return unparsed remainder
+    def parse(argv)
+      require "optparse"
+
+      parser = OptionParser.new do |opts|
+        tool.flags.each do |flag|
+          if flag.takes_argument?
+            opts.on(*flag.specs) { |v| @options[flag.name] = v }
+          else
+            opts.on(*flag.specs) { @options[flag.name] = true }
+          end
+        end
+      end
+
+      # Parse, collecting non-flag args
+      remaining = parser.parse(argv)
+
+      # Assign positional args
+      tool.args.each do |arg|
+        if arg.remaining
+          @options[arg.name] = remaining
+          remaining = []
+        elsif remaining.any?
+          @options[arg.name] = remaining.shift
+        end
+      end
+
+      remaining
+    end
+
+    # DSL methods - no-ops during execution (already captured during load)
+    def desc(_text)                      = nil
+    def long_desc(_text)                 = nil
+    def flag(_name, *_specs, **_kwargs)  = nil
+    def required_arg(_name, **_kwargs)   = nil
+    def optional_arg(_name, **_kwargs)   = nil
+    def remaining_args(_name, **_kwargs) = nil
+    def include(_name)                   = nil
+    def to_run(&)                  = nil
+
+    # We need special handling because `tool` is both an attr_reader
+    # and a DSL method. Override the reader to handle both cases.
+    def tool(name = nil, &block)
+      if name.nil? && block.nil?
+        # Called as attr_reader - return the Tool object
+        @tool
+      else
+        # Called as DSL method - no-op during execution (already captured)
+        nil
+      end
+    end
+
+    # Access options as methods
+    def method_missing(name, *args, &)
+      if @options.key?(name)
+        @options[name]
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false) = @options.key?(name) || super
+
+    # Access to builtin if this is an override
+    def builtin = tool.builtin ? ExecutionContext.new(tool.builtin, cli) : nil
+
+    # Run another tool by path
+    def run_tool(*path) = cli.run([*path.map(&:to_s)])
+
+    # Exit with code
+    def exit(code = 0) = Kernel.exit(code)
+
+    # --- Global options access ---
+
+    # Access CLI's global options
+    def global_options = cli.global_options
+
+    # Is verbose mode enabled? Returns verbosity level (0 = off, 1+ = on)
+    def verbose = global_options[:verbose]
+
+    def verbose? = verbose > 0
+
+    # Is quiet mode enabled?
+    def quiet? = global_options[:quiet]
+
+    # Get the effective output format
+    # Tool's --format flag takes precedence, then global --format, then context-based default
+    def output_format
+      # Tool-specific format (from options[:format]) takes precedence
+      return options[:format].to_sym if options[:format]
+
+      # Global format
+      return global_options[:format].to_sym if global_options[:format]
+
+      # Context-based default
+      Devex::Context.agent_mode? ? :json : :text
+    end
+  end
+end

data/lib/devex/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Devex
+  VERSION = "0.3.5"
+end

data/lib/devex/working_dir.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "support/path"
+require_relative "dirs"
+
+module Devex
+  # Immutable working directory context for tool execution.
+  #
+  # The working directory is passed through the call tree but cannot be
+  # mutated. Child contexts see a new directory but parent is unaffected.
+  #
+  # Usage:
+  #   working_dir  # => current working directory (Path)
+  #
+  #   within "packages/core" do
+  #     working_dir  # => /project/packages/core
+  #     run "npm", "test"  # Runs from packages/core
+  #   end
+  #
+  #   working_dir  # => /project (unchanged)
+  #
+  # See ADR-003 for full specification.
+  #
+  module WorkingDir
+    Path = Support::Path
+
+    # Thread-local working directory stack
+    # Each entry is an immutable Path
+    @stack       = []
+    @stack_mutex = Mutex.new
+
+    class << self
+      # Get current working directory
+      # Defaults to project_dir if no context has been pushed
+      def current = @stack_mutex.synchronize { @stack.last || Dirs.project_dir }
+
+      # Execute a block with a different working directory
+      # The working directory is restored after the block completes.
+      #
+      # @param subdir [String, Path] Directory to change to
+      # @yield Block to execute in the new context
+      # @return Result of the block
+      #
+      # @example Relative path
+      #   within "packages/web" do
+      #     run "npm", "test"
+      #   end
+      #
+      # @example Absolute path
+      #   within Path["/tmp/build"] do
+      #     run "make"
+      #   end
+      #
+      # @example Using project paths
+      #   within prj.test do
+      #     run "rake"
+      #   end
+      #
+      def within(subdir)
+        new_wd = case subdir
+                 when Path     then subdir.absolute? ? subdir : current / subdir
+                 when Pathname then subdir.absolute? ? Path.new(subdir) : current / subdir.to_s
+                 when String   then subdir.start_with?("/") ? Path[subdir] : current / subdir
+                 else
+                   raise ArgumentError, "Expected String or Path, got #{subdir.class}"
+                 end
+
+        push(new_wd)
+        yield
+      ensure
+        pop
+      end
+
+      # Reset the working directory stack (for testing)
+      def reset! = @stack_mutex.synchronize { @stack.clear }
+
+      # Get the full stack (for debugging)
+      def stack = @stack_mutex.synchronize { @stack.dup }
+
+      # Get the depth of the current context
+      def depth = @stack_mutex.synchronize { @stack.size }
+
+      private
+
+      def push(path) = @stack_mutex.synchronize { @stack.push(path.freeze) }
+
+      def pop = @stack_mutex.synchronize { @stack.pop }
+    end
+  end
+
+  # Mixin module for tools that need working directory support
+  module WorkingDirMixin
+    # Get current working directory
+    def working_dir = WorkingDir.current
+
+    # Execute block in a different working directory
+    def within(subdir, &) = WorkingDir.within(subdir, &)
+  end
+end

data/lib/devex.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# Devex - The dx CLI tool with all builtins and dx-specific configuration.
+#
+# This is the full dx application. For just the CLI framework (to build
+# your own CLI tool), use: require "devex/core"
+
+require_relative "devex/core"
+
+module Devex
+  class Error < StandardError; end
+
+  # ─────────────────────────────────────────────────────────────
+  # dx-specific Configuration
+  # ─────────────────────────────────────────────────────────────
+
+  # dx-specific project root markers, checked in order
+  ROOT_MARKERS = %w[.dx.yml .dx .git tools].freeze
+
+  # Default tools directory name
+  DEFAULT_TOOLS_DIR = "tools"
+
+  # Templates directory name within the gem
+  TEMPLATES_DIR = "templates"
+
+  # dx-specific configuration for CLI
+  DX_CONFIG = Core::Configuration.new(
+    executable_name:  "dx",
+    flag_prefix:      "dx",
+    project_markers:  %w[.dx.yml .dx .git tools Gemfile Rakefile .devex.yml],
+    config_file:      ".dx.yml",
+    organized_dir:    ".dx",
+    tools_dir:        "tools",
+    env_prefix:       "DX",
+    delegation_file:  ".dx-use-local"
+  ).freeze
+
+  class << self
+    # Get the dx configuration
+    # @return [Core::Configuration]
+    def config
+      DX_CONFIG
+    end
+
+    # Root directory of the devex gem itself
+    # Used for locating built-in templates, builtins, etc.
+    def gem_root
+      @gem_root ||= File.expand_path('..', __dir__)
+    end
+
+    # Path to the templates directory within the gem
+    def templates_path
+      @templates_path ||= File.join(File.dirname(__FILE__), "devex", TEMPLATES_DIR)
+    end
+
+    # Load and render a template from the gem's templates directory
+    # Returns the rendered string
+    #
+    # If locals hash is provided, creates a binding with TemplateHelpers
+    # and all locals available. If a binding is provided directly, uses that.
+    def render_template(name, locals_or_binding = nil)
+      path = template_path(name)
+      raise Error, "Template not found: #{name}" unless File.exist?(path)
+
+      bind = if locals_or_binding.is_a?(Hash)
+               TemplateHelpers.template_binding(locals_or_binding)
+             elsif locals_or_binding.is_a?(Binding)
+               locals_or_binding
+             else
+               TemplateHelpers.template_binding
+             end
+
+      Output.render_template_file(path, bind)
+    end
+
+    # Get full path to a template file
+    # Adds .erb extension if not present
+    def template_path(name)
+      name = "#{name}.erb" unless name.end_with?(".erb")
+      File.join(templates_path, name)
+    end
+
+    # Find the project root by walking up from the given directory
+    # looking for root markers (.dx.yml, .git, tools/)
+    #
+    # Returns [root_path, marker_found] or [nil, nil] if not found
+    def find_project_root(from = Dir.pwd)
+      dir = File.expand_path(from)
+
+      loop do
+        ROOT_MARKERS.each do |marker|
+          marker_path = File.join(dir, marker)
+          return [dir, marker] if File.exist?(marker_path)
+        end
+
+        parent = File.dirname(dir)
+        break if parent == dir # reached filesystem root
+
+        dir = parent
+      end
+
+      [nil, nil]
+    end
+
+    # Get the tools directory for a project root
+    # Reads from .dx.yml or .dx/config.yml if present, otherwise uses default
+    def tools_dir(project_root)
+      return nil unless project_root
+
+      config         = load_config(project_root)
+      tools_dir_name = config["tools_dir"] || DEFAULT_TOOLS_DIR
+
+      dir = File.join(project_root, tools_dir_name)
+      File.directory?(dir) ? dir : nil
+    end
+
+    # Load project configuration from .dx.yml or .dx/config.yml
+    # Returns empty hash if no config file exists
+    # Raises Error if both .dx.yml and .dx/ directory exist (conflict)
+    def load_config(project_root)
+      return {} unless project_root
+
+      dx_dir = File.join(project_root, ".dx")
+      dx_yml = File.join(project_root, ".dx.yml")
+
+      dx_dir_exists = File.directory?(dx_dir)
+      dx_yml_exists = File.exist?(dx_yml)
+
+      # Conflict check: both simple and organized mode markers present
+      if dx_dir_exists && dx_yml_exists
+        raise Error, <<~ERR.chomp
+          Conflicting dx configuration
+
+            Found both:
+              .dx.yml   (simple mode config)
+              .dx/      (organized mode directory)
+
+            Choose one:
+              • Remove .dx.yml to use organized mode (.dx/config.yml)
+              • Remove .dx/ directory to use simple mode (.dx.yml)
+        ERR
+      end
+
+      config_file = if dx_dir_exists
+                      File.join(dx_dir, "config.yml")
+                    else
+                      dx_yml
+                    end
+
+      if File.exist?(config_file)
+        require "yaml"
+        YAML.safe_load_file(config_file) || {}
+      else
+        {}
+      end
+    end
+  end
+end

data/sig/devex.rbs

@@ -0,0 +1,4 @@
+module Devex
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end