devex 0.3.5

data/lib/devex/dirs.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require_relative "support/path"
+
+module Devex
+  # Directory context for a CLI application.
+  #
+  # Holds the directory state for a CLI invocation:
+  #   - invoked_dir: Where user actually ran the command
+  #   - dest_dir: Effective start directory (invoked_dir or overridden)
+  #   - project_dir: Discovered project root
+  #   - src_dir: Framework gem installation directory
+  #
+  # Instance-based for Core usage, with module methods for backward compatibility.
+  #
+  # @example Core usage (recommended)
+  #   config = Devex::Core::Configuration.new(project_markers: %w[.mycli.yml .git])
+  #   dirs = Devex::Dirs.new(config: config)
+  #   dirs.project_dir  # => discovered project root
+  #
+  # @example Backward-compatible module usage
+  #   Devex::Dirs.project_dir  # uses default dx configuration
+  #
+  class Dirs
+    Path = Support::Path
+
+    # Default project markers
+    # Includes dx-specific markers since this is the devex gem.
+    # Core users can override via Configuration.project_markers.
+    DEFAULT_PROJECT_MARKERS = %w[.dx.yml .dx .git Gemfile Rakefile .devex.yml].freeze
+
+    # @param config [Core::Configuration, nil] configuration (uses defaults if nil)
+    # @param invoked_from [String] directory where command was invoked (default: pwd)
+    # @param dest_dir [String, nil] override for dest_dir (e.g., from --flag-from-dir)
+    # @param src_dir [String, nil] framework source directory (defaults to devex gem)
+    def initialize(config: nil, invoked_from: Dir.pwd, dest_dir: nil, src_dir: nil)
+      @config      = config
+      @invoked_dir = Path[invoked_from].exp
+      @dest_dir    = dest_dir ? Path[dest_dir].exp : @invoked_dir
+      @src_dir     = src_dir ? Path[src_dir] : Path[File.expand_path("../..", __dir__)]
+      @project_dir = nil  # lazy
+    end
+
+    # Where the user actually ran the command (captured at startup)
+    # @return [Path]
+    attr_reader :invoked_dir
+
+    # Effective start directory (invoked_dir unless overridden)
+    # @return [Path]
+    attr_reader :dest_dir
+
+    # Framework source directory (for templates, builtins, etc.)
+    # @return [Path]
+    attr_reader :src_dir
+
+    # Project markers to search for
+    # @return [Array<String>]
+    def project_markers
+      @config&.project_markers || DEFAULT_PROJECT_MARKERS
+    end
+
+    # Discovered project root directory
+    # Searched upward from dest_dir using project_markers
+    # @param raise_on_missing [Boolean] raise error if not found (default: true)
+    # @return [Path, nil]
+    def project_dir(raise_on_missing: true)
+      @project_dir ||= discover_project_root(raise_on_missing: raise_on_missing)
+    end
+
+    # Check if we're inside a project (without raising)
+    # @return [Boolean]
+    def in_project?
+      !!@project_dir || !!discover_project_root(raise_on_missing: false)
+    end
+
+    # Reset cached state (for testing)
+    def reset!
+      @project_dir = nil
+    end
+
+    private
+
+    def discover_project_root(raise_on_missing: true)
+      current = @dest_dir
+
+      loop do
+        project_markers.each do |marker|
+          marker_path = current / marker
+          return current if marker_path.exist?
+        end
+
+        parent = current.parent
+        break if parent.to_s == current.to_s  # Reached filesystem root
+
+        current = parent
+      end
+
+      return nil unless raise_on_missing
+
+      fail_no_project!
+    end
+
+    def fail_no_project!
+      exe_name = @config&.executable_name || "cli"
+      from_flag = @config ? @config.flag("from_dir") : "--from-dir"
+
+      message = <<~ERR
+        ERROR: Not inside a project
+
+          Searched from: #{@dest_dir}
+          Looked for: #{project_markers.join(', ')}
+
+          To create a new project:
+            #{exe_name} init
+
+          To operate on a different directory:
+            #{exe_name} #{from_flag}=/path/to/project command
+
+        Exit code: 78 (EX_CONFIG)
+      ERR
+
+      raise message
+    end
+
+    # ─────────────────────────────────────────────────────────────
+    # Module-Level API (Backward Compatibility)
+    # ─────────────────────────────────────────────────────────────
+    #
+    # These class methods provide backward compatibility with the
+    # original module-based API. They delegate to a thread-local
+    # default instance.
+    #
+    class << self
+      # Get or create the default Dirs instance for this thread
+      # @return [Dirs]
+      def default
+        Thread.current[:devex_dirs] ||= new_default
+      end
+
+      # Set the default Dirs instance (used by devex.rb to configure for dx)
+      # @param dirs [Dirs]
+      def default=(dirs)
+        Thread.current[:devex_dirs] = dirs
+      end
+
+      # Reset the default instance (for testing)
+      def reset!
+        Thread.current[:devex_dirs] = nil
+        # Also clear any instance state if there was one
+        Thread.current[:devex_dirs_dest_override] = nil
+      end
+
+      # Backward-compatible: set dest_dir before project discovery
+      # Must be called early, before project_dir is accessed
+      def dest_dir=(path)
+        if Thread.current[:devex_dirs]&.instance_variable_get(:@project_dir)
+          raise "Cannot change dest_dir after project_dir is computed"
+        end
+
+        Thread.current[:devex_dirs_dest_override] = path
+        # Clear default so it gets recreated with new dest_dir
+        Thread.current[:devex_dirs] = nil
+      end
+
+      # Delegate instance methods to default
+      def invoked_dir = default.invoked_dir
+      def dest_dir = default.dest_dir
+      def project_dir = default.project_dir
+      def src_dir = default.src_dir
+      def dx_src_dir = default.src_dir  # Backward-compatible alias
+      def in_project? = default.in_project?
+
+      private
+
+      def new_default
+        dest_override = Thread.current[:devex_dirs_dest_override]
+        new(dest_dir: dest_override)
+      end
+    end
+
+    # ─────────────────────────────────────────────────────────────
+    # Delegation Support
+    # ─────────────────────────────────────────────────────────────
+
+    # Check if we should delegate to a bundled/local version of the CLI
+    # Call early in startup, before any real work.
+    #
+    # @param config [Core::Configuration] configuration with delegation settings
+    # @param argv [Array<String>] command line arguments to pass through
+    # @return [void] (exits process if delegating)
+    def self.maybe_delegate_to_local!(config: nil, argv: ARGV)
+      delegation_file = config&.delegation_file
+      return unless delegation_file
+
+      delegation_env = config.env_var(:delegated)
+      return if ENV[delegation_env]
+
+      dirs = config ? new(config: config) : default
+      return unless dirs.in_project?
+
+      use_local = dirs.project_dir / delegation_file
+      return unless use_local.exist?
+
+      # Delegate: set flag, change to project dir, exec bundled version
+      ENV[delegation_env] = "1"
+      Dir.chdir(dirs.project_dir.to_s)
+      exec "bundle", "exec", config.executable_name, *argv
+    end
+  end
+end

data/lib/devex/dsl.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Devex
+  # DSL context for defining tools in task files
+  class DSL
+    attr_reader :tool
+
+    def initialize(tool) = @tool = tool
+
+    def desc(text) = @tool.desc = text
+
+    def long_desc(text) = @tool.long_desc = text
+
+    def flag(name, *specs, desc: nil, default: nil) = @tool.flag(name, *specs, desc: desc, default: default)
+
+    def required_arg(name, desc: nil) = @tool.required_arg(name, desc: desc)
+
+    def optional_arg(name, desc: nil, default: nil) = @tool.optional_arg(name, desc: desc, default: default)
+
+    def remaining_args(name, desc: nil) = @tool.remaining_args(name, desc: desc)
+
+    def include(name) = @tool.include_mixin(name)
+
+    def tool(name, &block)
+      subtool = Tool.new(name, parent: @tool)
+      if block
+        # Capture the block source location for later re-evaluation
+        subtool.source_file = block.source_location[0]
+        subtool.source_proc = block
+      end
+      @tool.add_subtool(subtool)
+      subtool
+    end
+
+    def to_run(&block) = @tool.run_block = block
+  end
+
+  # Evaluates task files and captures tool definitions
+  module TaskFileDSL
+    def self.evaluate(tool, code, filename)
+      # Store the source for later execution
+      tool.source_code = code
+      tool.source_file = filename
+
+      # Parse the DSL parts (desc, flags, etc.) but don't execute run yet
+      context = DSLContext.new(tool)
+      context.instance_eval(code, filename)
+
+      tool
+    end
+  end
+
+  # Context for parsing DSL declarations (not execution)
+  class DSLContext
+    def initialize(tool) = @tool = tool
+
+    def desc(text) = @tool.desc = text
+
+    def long_desc(text) = @tool.long_desc = text
+
+    def flag(name, *specs, desc: nil, default: nil) = @tool.flag(name, *specs, desc: desc, default: default)
+
+    def required_arg(name, desc: nil) = @tool.required_arg(name, desc: desc)
+
+    def optional_arg(name, desc: nil, default: nil) = @tool.optional_arg(name, desc: desc, default: default)
+
+    def remaining_args(name, desc: nil) = @tool.remaining_args(name, desc: desc)
+
+    def include(name) = @tool.include_mixin(name)
+
+    def tool(name, &block)
+      subtool = Tool.new(name, parent: @tool)
+      if block
+        # For nested tools, we need to capture the block's source
+        # Since we can't easily get block source, we'll use a different strategy:
+        # Evaluate the block in a new DSLContext to get the DSL parts,
+        # and mark that it has a run method defined
+        nested_context = DSLContext.new(subtool)
+        nested_context.instance_eval(&block)
+        # Store source_file so the whole file is eval'd at runtime,
+        # making helper methods from the parent file available
+        subtool.source_file = block.source_location[0]
+        subtool.source_proc = block
+      end
+      @tool.add_subtool(subtool)
+      subtool
+    end
+
+    def to_run(&block) = @tool.run_block = block
+
+    # Capture def statements - they become the tool's methods
+    # We use method_missing to collect method names, but can't capture the bodies
+    # Instead, we mark that the tool has a run method and will re-eval at runtime
+    def method_missing(name, *args, &)
+      # Silently ignore - methods will be available at runtime via re-eval
+    end
+
+    def respond_to_missing?(_name, _include_private = false) = true
+  end
+end

data/lib/devex/exec/controller.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require_relative "result"
+
+module Devex
+  module Exec
+    # Controller for managing background (spawned) processes.
+    #
+    # Returned by `spawn` to provide control over the child process.
+    # Use this to monitor, signal, or wait for completion.
+    #
+    # @example Basic usage
+    #   ctrl = spawn "rails", "server"
+    #   sleep 5
+    #   ctrl.kill(:TERM)
+    #   result = ctrl.result
+    #
+    # @example With IO access
+    #   ctrl = spawn "cat", stdin: :pipe, stdout: :pipe
+    #   ctrl.stdin.puts "hello"
+    #   ctrl.stdin.close
+    #   output = ctrl.stdout.read
+    #   ctrl.result
+    #
+    class Controller
+      # @return [Integer] Process ID
+      attr_reader :pid
+
+      # @return [String, nil] Optional name/identifier
+      attr_reader :name
+
+      # @return [Array<String>] The command being executed
+      attr_reader :command
+
+      # @return [Time] When the process was started
+      attr_reader :started_at
+
+      # @return [IO, nil] Stdin pipe (if configured)
+      attr_reader :stdin
+
+      # @return [IO, nil] Stdout pipe (if configured)
+      attr_reader :stdout
+
+      # @return [IO, nil] Stderr pipe (if configured)
+      attr_reader :stderr
+
+      # @return [Hash] Options passed when spawning
+      attr_reader :options
+
+      def initialize(
+        pid:,
+        command:,
+        name: nil,
+        stdin: nil,
+        stdout: nil,
+        stderr: nil,
+        options: {}
+      )
+        @pid        = pid
+        @command    = Array(command)
+        @name       = name
+        @stdin      = stdin
+        @stdout     = stdout
+        @stderr     = stderr
+        @options    = options
+        @started_at = Time.now
+        @result     = nil
+        @mutex      = Mutex.new
+      end
+
+      # ─────────────────────────────────────────────────────────────
+      # Status
+      # ─────────────────────────────────────────────────────────────
+
+      # @return [Boolean] true if process is still running
+      def executing?
+        return false if @result
+
+        # Non-blocking check
+        pid_result, _status = Process.wait2(pid, Process::WNOHANG)
+        pid_result.nil?
+      rescue Errno::ECHILD
+        false
+      end
+
+      alias running? executing?
+
+      # @return [Boolean] true if process has finished
+      def finished? = !executing?
+
+      # @return [Float] Seconds since process started
+      def elapsed = Time.now - @started_at
+
+      # ─────────────────────────────────────────────────────────────
+      # Signals
+      # ─────────────────────────────────────────────────────────────
+
+      # Send a signal to the process.
+      #
+      # @param signal [Symbol, String, Integer] Signal to send
+      # @return [Boolean] true if signal was sent successfully
+      #
+      # @example
+      #   ctrl.kill(:TERM)
+      #   ctrl.kill(:INT)
+      #   ctrl.kill(:KILL)
+      #   ctrl.kill(9)
+      #   ctrl.kill("SIGTERM")
+      #
+      def kill(signal = :TERM)
+        Process.kill(signal, pid)
+        true
+      rescue Errno::ESRCH, Errno::EPERM
+        # Process already gone or we don't have permission
+        false
+      end
+
+      alias signal kill
+
+      # Send SIGTERM and wait for graceful shutdown.
+      #
+      # @param timeout [Float] Seconds to wait before SIGKILL
+      # @return [Result] Final result
+      def terminate(timeout: 5)
+        kill(:TERM)
+        result(timeout: timeout)
+      rescue Timeout::Error
+        kill(:KILL)
+        result(timeout: 1)
+      end
+
+      # ─────────────────────────────────────────────────────────────
+      # Wait for Completion
+      # ─────────────────────────────────────────────────────────────
+
+      # Wait for process to complete and return Result.
+      #
+      # @param timeout [Float, nil] Maximum seconds to wait (nil = forever)
+      # @return [Result] Final result with exit status
+      # @raise [Timeout::Error] if timeout exceeded
+      #
+      # @example
+      #   result = ctrl.result
+      #   result = ctrl.result(timeout: 30)
+      #
+      def result(timeout: nil)
+        @mutex.synchronize do
+          return @result if @result
+        end
+
+        status = if timeout
+                   wait_with_timeout(timeout)
+                 else
+                   Process.wait2(pid)[1]
+                 end
+
+        duration = Time.now - @started_at
+        close_pipes
+
+        @mutex.synchronize do
+          @result = Result.from_status(
+            status,
+            command:  @command,
+            duration: duration,
+            options:  @options
+          )
+        end
+      end
+
+      alias wait result
+
+      # ─────────────────────────────────────────────────────────────
+      # IO Helpers
+      # ─────────────────────────────────────────────────────────────
+
+      # Write to stdin and optionally close.
+      #
+      # @param data [String] Data to write
+      # @param close_after [Boolean] Close stdin after writing
+      # @return [Integer] Bytes written
+      def write(data, close_after: false)
+        raise "No stdin pipe available" unless @stdin
+
+        bytes = @stdin.write(data)
+        @stdin.close if close_after
+        bytes
+      end
+
+      # Read all available stdout.
+      #
+      # @return [String, nil] Stdout content or nil if no pipe
+      def read_stdout = @stdout&.read
+
+      # Read all available stderr.
+      #
+      # @return [String, nil] Stderr content or nil if no pipe
+      def read_stderr = @stderr&.read
+
+      # ─────────────────────────────────────────────────────────────
+      # Inspection
+      # ─────────────────────────────────────────────────────────────
+
+      def to_s
+        status = if @result
+                   @result.success? ? "exited" : "failed"
+                 else
+                   "running"
+                 end
+        "#<Controller #{command.first} pid=#{pid} #{status}>"
+      end
+
+      def inspect
+        parts = ["#<Controller"]
+        parts << "name=#{name.inspect}" if name
+        parts << "command=#{command.inspect}"
+        parts << "pid=#{pid}"
+        parts << "elapsed=#{'%.2f' % elapsed}s"
+        parts << "status=#{@result ? 'finished' : 'running'}"
+        parts << ">"
+        parts.join(" ")
+      end
+
+      private
+
+      def wait_with_timeout(timeout)
+        deadline = Time.now + timeout
+        loop do
+          pid_result, status = Process.wait2(pid, Process::WNOHANG)
+          return status if pid_result
+
+          remaining = deadline - Time.now
+          raise Timeout::Error, "Process #{pid} did not exit within #{timeout}s" if remaining <= 0
+
+          sleep([0.1, remaining].min)
+        end
+      end
+
+      def close_pipes
+        @stdin&.close unless @stdin&.closed?
+        @stdout&.close unless @stdout&.closed?
+        @stderr&.close unless @stderr&.closed?
+      end
+    end
+  end
+end