devex 0.3.5

data/lib/devex/support/path.rb

@@ -0,0 +1,357 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "fileutils"
+require "tmpdir"
+
+module Devex
+  module Support
+    # Enhanced Pathname with ergonomic shortcuts for CLI development.
+    #
+    # Usage:
+    #   path = Path["~/src/project"]
+    #   path = "~/src/project".to_p  # With String refinement
+    #   path = Path.pwd
+    #
+    #   # Joining with / operator
+    #   path / "lib" / "foo.rb"
+    #
+    #   # Permission checks
+    #   path.r?   # readable?
+    #   path.w?   # writable?
+    #   path.rw?  # readable and writable?
+    #
+    #   # Existence
+    #   path.exist?
+    #   path.missing?
+    #   path.existence  # Returns self or nil
+    #
+    #   # Relative paths
+    #   path.rel                      # Relative to pwd with ~/
+    #   path.rel(from: project_root)  # Relative to specific dir
+    #   path.short                    # Shortest representation
+    #
+    #   # Globbing
+    #   path["**/*.rb"]
+    #
+    #   # Safe directory creation
+    #   path.dir!   # Creates parent dirs, returns self
+    #
+    #   # File I/O
+    #   path.read
+    #   path.write(content)
+    #   path.append(content)
+    #   path.atomic_write(content)
+    #
+    class Path < Pathname
+      class << self
+        # Construct from string: Path["~/src/project"]
+        def [](path) = new(expand_user(path.to_s))
+
+        # Current working directory
+        def pwd = new(Dir.pwd)
+        alias cwd pwd
+        alias getwd pwd
+
+        # Home directory
+        def home = new(Dir.home)
+
+        # Temporary directory
+        def tmp = new(Dir.tmpdir)
+        alias tmpdir tmp
+
+        private
+
+        # Expand ~ and ~user in path strings
+        def expand_user(path)
+          return path unless path.start_with?("~")
+
+          File.expand_path(path)
+        end
+      end
+
+      # ─────────────────────────────────────────────────────────────
+      # Path Joining
+      # ─────────────────────────────────────────────────────────────
+
+      # Division operator for path joining: path / "subdir" / "file.rb"
+      def /(other) = self.class.new(join(other.to_s))
+
+      # Override join to return Path
+      def join(*args)
+        return self if args.empty?
+
+        self.class.new(super(*args.map(&:to_s)))
+      end
+
+      # ─────────────────────────────────────────────────────────────
+      # Permission Checks
+      # ─────────────────────────────────────────────────────────────
+
+      def r?   = readable_real?
+      def w?   = writable_real?
+      def x?   = executable_real?
+      def rw?  = r? && w?
+      def rx?  = r? && x?
+      def wx?  = w? && x?
+      def rwx? = r? && w? && x?
+
+      # ─────────────────────────────────────────────────────────────
+      # Type Checks
+      # ─────────────────────────────────────────────────────────────
+
+      def dir?     = directory?
+      def missing? = !exist?
+      alias exists? exist?
+
+      # ActiveSupport-style: returns self if exists, nil otherwise
+      def existence = exist? ? self : nil
+
+      # ─────────────────────────────────────────────────────────────
+      # Memoized Expansions
+      # ─────────────────────────────────────────────────────────────
+
+      # Expanded path (memoized)
+      def exp = @exp ||= self.class.new(expand_path)
+
+      # Real path with fallback to expanded (memoized, safe)
+      def real
+        @real ||= begin
+          self.class.new(realpath)
+        rescue Errno::ENOENT
+          exp
+        end
+      end
+
+      # Clear memoization (if path might have changed)
+      def reload!
+        @exp = @real = @rc = nil
+        self
+      end
+
+      # ─────────────────────────────────────────────────────────────
+      # Relative Paths
+      # ─────────────────────────────────────────────────────────────
+
+      # Relative path with ~ substitution for home directory
+      # @param from [Path, String] Base directory (default: pwd)
+      # @param home [Boolean] Substitute ~ for home directory
+      def rel(from: nil, home: true)
+        from   = self.class.new(from&.to_s || Dir.pwd)
+        result = exp.relative_path_from(from.exp)
+        result = self.class.new(result)
+
+        result = self.class.new(result.to_s.sub(Dir.home, "~")) if home && Dir.home && result.to_s.start_with?(Dir.home)
+        result
+      rescue ArgumentError
+        # Can't compute relative path (different drives on Windows, etc.)
+        if home && Dir.home
+          self.class.new(to_s.sub(Dir.home, "~"))
+        else
+          self
+        end
+      end
+
+      # Shortest representation of path
+      def short(from: nil)
+        from       = self.class.new(from&.to_s || Dir.pwd)
+        candidates = []
+
+        # Try relative from base
+        begin
+          candidates << exp.relative_path_from(from.exp)
+        rescue ArgumentError
+          # Ignore - can't compute relative
+        end
+
+        # Try with ~ substitution
+        if Dir.home
+          home_sub = to_s.sub(Dir.home, "~")
+          candidates << self.class.new(home_sub) if home_sub != to_s
+        end
+
+        # Original as fallback
+        candidates << self
+
+        candidates.compact.min_by { |c| c.to_s.length }
+      end
+
+      # Cache for relative path calculations (expensive operation)
+      def relative_path_from(base)
+        @rc            ||= {}
+        @rc[base.to_s] ||= self.class.new(super)
+      end
+
+      # ─────────────────────────────────────────────────────────────
+      # Globbing
+      # ─────────────────────────────────────────────────────────────
+
+      # Glob from this directory: path["**/*.rb"]
+      def [](pattern, include_dotfiles: true)
+        base  = directory? ? self : dirname
+        flags = include_dotfiles ? File::FNM_DOTMATCH : 0
+        Pathname.glob((base / pattern).to_s, flags).map { |p| self.class.new(p) }
+      end
+
+      # Alias for more explicit calls
+      def glob(pattern, **) = self[pattern, **]
+
+      # ─────────────────────────────────────────────────────────────
+      # Directory Operations
+      # ─────────────────────────────────────────────────────────────
+
+      # Get directory (dirname, but returns self if already a directory)
+      def dir = directory? ? exp : self.class.new(dirname)
+
+      # Create directory (and parents) if missing, return self
+      # Safe - returns nil on error instead of raising
+      def dir!
+        target = directory? ? self : dir
+        target.mkpath unless target.exist?
+        self
+      rescue SystemCallError
+        nil
+      end
+
+      # Create this directory (and parents) if missing
+      def mkdir!
+        mkpath unless exist?
+        self
+      rescue SystemCallError
+        nil
+      end
+
+      # ─────────────────────────────────────────────────────────────
+      # File I/O
+      # ─────────────────────────────────────────────────────────────
+
+      # Read entire file contents
+      def read(encoding: nil)
+        opts = encoding ? { encoding: encoding } : {}
+        File.read(to_s, **opts)
+      end
+      alias contents read
+
+      # Read as lines
+      def lines(chomp: true) = File.readlines(to_s, chomp: chomp)
+
+      # Write contents (creates parent directories)
+      def write(content, encoding: nil)
+        dir!
+        opts = encoding ? { encoding: encoding } : {}
+        File.write(to_s, content, **opts)
+        self
+      end
+
+      # Append to file
+      def append(content)
+        dir!
+        File.write(to_s, content, mode: "a")
+        self
+      end
+
+      # Atomic write (write to temp, then rename)
+      def atomic_write(content)
+        dir!
+        require "tempfile"
+        Tempfile.create([basename.to_s, extname], dirname.to_s) do |temp|
+          temp.binmode
+          temp.write(content)
+          temp.close
+          FileUtils.mv(temp.path, to_s)
+        end
+        self
+      end
+
+      # Delete file (no-op if doesn't exist)
+      def rm
+        File.delete(to_s) if file?
+        self
+      end
+      alias delete rm
+      alias unlink rm
+
+      # Delete directory recursively (no-op if doesn't exist)
+      def rm_rf
+        FileUtils.rm_rf(to_s) if exist?
+        self
+      end
+
+      # ─────────────────────────────────────────────────────────────
+      # Modification Time Comparisons
+      # ─────────────────────────────────────────────────────────────
+
+      def newer_than?(other)
+        other = self.class[other] unless other.is_a?(Pathname)
+        return true unless other.exist?
+        return false unless exist?
+
+        mtime > other.mtime
+      end
+
+      def older_than?(other)
+        other = self.class[other] unless other.is_a?(Pathname)
+        return false unless other.exist?
+        return true unless exist?
+
+        mtime < other.mtime
+      end
+
+      # ─────────────────────────────────────────────────────────────
+      # Extension Manipulation
+      # ─────────────────────────────────────────────────────────────
+
+      # Replace extension: path.with_ext(".md")
+      def with_ext(new_ext)
+        new_ext = ".#{new_ext}" unless new_ext.to_s.start_with?(".")
+        self.class.new(sub_ext(new_ext.to_s))
+      end
+
+      # Remove extension
+      def without_ext = self.class.new(to_s.sub(/#{Regexp.escape(extname)}$/, ""))
+
+      # ─────────────────────────────────────────────────────────────
+      # Siblings and Relatives
+      # ─────────────────────────────────────────────────────────────
+
+      # Sibling with same directory but different name
+      def sibling(name) = dir / name.to_s
+
+      # Override parent to return Path
+      def parent = self.class.new(super)
+
+      # Override dirname to return Path
+      def dirname = self.class.new(super)
+
+      # Override basename to return Path
+      def basename(*args) = self.class.new(super)
+
+      # ─────────────────────────────────────────────────────────────
+      # Inspection
+      # ─────────────────────────────────────────────────────────────
+
+      def inspect = "#<Path:#{self}>"
+
+      # ─────────────────────────────────────────────────────────────
+      # String-like Behavior
+      # ─────────────────────────────────────────────────────────────
+
+      # Delegate string methods to to_s
+      def method_missing(method, *, &)
+        if to_s.respond_to?(method)
+          result = to_s.send(method, *, &)
+          # Return Path if result looks like a path
+          if result.is_a?(String) && result.include?("/")
+            self.class.new(result)
+          else
+            result
+          end
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method, include_private = false) = to_s.respond_to?(method, include_private) || super
+    end
+  end
+end

data/lib/devex/support.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Devex Support Library
+#
+# A zero-dependency collection of Ruby utilities optimized for CLI development.
+# Provides Path manipulation, ANSI colors, and core extensions as refinements.
+#
+# ## Quick Start
+#
+#   require "devex/support"
+#
+#   # Use refinements (scoped to current file)
+#   using Devex::Support::CoreExt
+#   using Devex::Support::ANSI::StringMethods
+#
+#   # Or for CLI tools, load globally:
+#   require "devex/support/global"
+#
+# ## Components
+#
+# ### Path - Enhanced Pathname for CLI tools
+#
+#   path = Path["~/src/project"]
+#   path = Path.pwd / "lib" / "foo.rb"
+#
+#   path.r?          # readable?
+#   path.w?          # writable?
+#   path.exist?      # exists?
+#   path.dir!        # ensure parent dirs exist
+#   path.rel         # relative path with ~ for home
+#   path.short       # shortest representation
+#
+# ### ANSI - Terminal colors (truecolor, zero deps)
+#
+#   ANSI["text", :bold, :success]
+#   ANSI["text", "#5AF78E"]
+#   ANSI % ["Outer %{inner}", :yellow, inner: ["nested", :blue]]
+#
+# ### CoreExt - Refinements for common operations
+#
+#   "".blank?                    # => true
+#   nil.present?                 # => false
+#   [1,2,3].average              # => 2.0
+#   {a: 1}.deep_merge(b: 2)      # => {a: 1, b: 2}
+#   "hello world".truncate(8)    # => "hello..."
+#
+
+module Devex
+  module Support
+    # Autoload support modules
+    autoload :Path,    "devex/support/path"
+    autoload :ANSI,    "devex/support/ansi"
+    autoload :CoreExt, "devex/support/core_ext"
+
+    # Convenience: expose Path at module level
+    # Allows: Devex::Support::Path["~/foo"]
+    # Or after `include Devex::Support`: Path["~/foo"]
+
+    class << self
+      # Version of the support library
+      def version = "0.1.0"
+    end
+  end
+end
+
+# Also expose Path at Devex level for convenience
+# Allows: Devex::Path["~/foo"]
+module Devex
+  Path = Support::Path
+  ANSI = Support::ANSI
+end

data/lib/devex/template_helpers.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative "support/ansi"
+
+module Devex
+  # Helper methods available in ERB templates.
+  # Automatically respects Context.color? for all styling.
+  #
+  # Usage in templates:
+  #   <%= c :green, "success" %>
+  #   <%= c :bold, :white, "header" %>
+  #   <%= sym :success %> All tests passed
+  #   <%= hr %>
+  #   <%= heading "Section" %>
+  #
+  module TemplateHelpers
+    # Color definitions (truecolor RGB) - matches Output::COLORS
+    COLORS = {
+      success:  [0x5A, 0xF7, 0x8E],
+      error:    [0xFF, 0x6B, 0x6B],
+      warning:  [0xFF, 0xE6, 0x6D],
+      info:     [0x6B, 0xC5, 0xFF],
+      header:   [0xC4, 0xB5, 0xFD],
+      muted:    [0x88, 0x88, 0x88],
+      emphasis: [0xFF, 0xFF, 0xFF]
+    }.freeze
+
+    # Symbols - basic unicode that works everywhere
+    # (Not nerdfont glyphs or emoji that render as images)
+    SYMBOLS = {
+      success: "✓",
+      error:   "✗",
+      warning: "⚠",
+      info:    "ℹ",
+      arrow:   "→",
+      bullet:  "•",
+      check:   "✓",
+      cross:   "✗",
+      dot:     "·"
+    }.freeze
+
+    module_function
+
+    # Colorize text - the main helper
+    # Last argument is the text, preceding arguments are colors/styles
+    #
+    # Examples:
+    #   c(:green, "text")
+    #   c(:bold, :white, "text")
+    #   c(:success, "text")      # uses named color
+    #   c([0x5A, 0xF7, 0x8E], "text")  # RGB array
+    #
+    def c(*args)
+      text = args.pop.to_s
+      return text unless Context.color?
+      return text if args.empty?
+
+      # Expand named colors to RGB
+      colors = args.map do |color|
+        if color.is_a?(Symbol) && COLORS.key?(color)
+          COLORS[color]
+        else
+          color
+        end
+      end
+
+      Support::ANSI[text, *colors]
+    end
+
+    # Get symbol - always unicode (basic unicode works everywhere)
+    def sym(name) = SYMBOLS.fetch(name, name.to_s)
+
+    # Colored symbol - combines sym() and c()
+    def csym(name, color = nil)
+      color ||= name # Default: use symbol name as color name
+      s     = sym(name)
+      c(color, s)
+    end
+
+    # Horizontal rule
+    def hr(char: "─", width: 40)
+      line = char * width
+      Context.color? ? c(:muted, line) : line
+    end
+
+    # Styled heading
+    def heading(text, char: "=", width: nil)
+      width ||= text.length
+      line  = char * width
+      if Context.color?
+        "#{c(:header, text)}\n#{c(:muted, line)}"
+      else
+        "#{text}\n#{line}"
+      end
+    end
+
+    # Muted/secondary text
+    def muted(text) = c(:muted, text)
+
+    # Bold text
+    def bold(text) = c(:bold, text)
+
+    # Create a binding with all helpers and locals available
+    def template_binding(locals = {}) = TemplateContext.new(locals).get_binding
+  end
+
+  # Context object for template rendering
+  # Includes all helper methods directly so templates can use clean syntax:
+  #   <%= c :green, "text" %>
+  #   <%= heading "Title" %>
+  #
+  class TemplateContext
+    include TemplateHelpers
+
+    def initialize(locals = {})
+      @locals = locals
+      # Define accessor methods for each local variable
+      locals.each do |name, value|
+        define_singleton_method(name) { value }
+      end
+    end
+
+    def get_binding = binding
+
+    # Allow accessing locals as methods or via method_missing
+    def method_missing(name, *args, &)
+      if @locals.key?(name)
+        @locals[name]
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false) = @locals.key?(name) || super
+  end
+end

data/lib/devex/templates/debug.erb

@@ -0,0 +1,24 @@
+<%= heading "Context Detection" %>
+
+<%= c :header, "TTY Detection:" %>
+  stdout.tty?     = <%= c(tty[:stdout] ? :success : :muted, tty[:stdout]) %>
+  stderr.tty?     = <%= c(tty[:stderr] ? :success : :muted, tty[:stderr]) %>
+  stdin.tty?      = <%= c(tty[:stdin] ? :success : :muted, tty[:stdin]) %>
+  terminal?       = <%= c(tty[:terminal] ? :success : :muted, tty[:terminal]) %>
+
+<%= c :header, "Streams:" %>
+  streams_merged? = <%= c(streams[:merged] ? :warning : :muted, streams[:merged]) %>
+  piped?          = <%= c(streams[:piped] ? :info : :muted, streams[:piped]) %>
+
+<%= c :header, "Environment:" %>
+  ci?             = <%= c(environment[:ci] ? :info : :muted, environment[:ci]) %>
+  env             = <%= c :emphasis, environment[:env] %>
+  agent_mode_env? = <%= c(environment[:agent_mode_env] ? :warning : :muted, environment[:agent_mode_env]) %>
+
+<%= c :header, "Detection:" %>
+  agent_mode?     = <%= c(detection[:agent_mode] ? :warning : :success, detection[:agent_mode]) %>
+  interactive?    = <%= c(detection[:interactive] ? :success : :muted, detection[:interactive]) %>
+  color?          = <%= c(detection[:color] ? :success : :muted, detection[:color]) %>
+
+<%= muted "Call Tree: #{call_tree.inspect}" %>
+<%= muted "Overrides: #{overrides.inspect}" %>