devex 0.3.5

data/lib/devex/loader.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Devex
+  # Loads tool definitions from task files
+  class Loader
+    INDEX_FILE = ".index.rb"
+
+    # Load all tools from a directory into a root tool
+    #
+    # Directory structure maps to tool hierarchy:
+    #   tools/test.rb           -> dx test
+    #   tools/version.rb        -> dx version (with nested tools defined inside)
+    #   tools/docs/             -> dx docs (if .index.rb exists) or namespace
+    #   tools/docs/generate.rb  -> dx docs generate
+    #
+    def self.load_directory(dir, root_tool, mixins = {})
+      return unless dir && File.directory?(dir)
+
+      loader = new(dir, root_tool, mixins)
+      loader.load
+    end
+
+    def initialize(dir, root_tool, mixins = {})
+      @dir       = dir
+      @root_tool = root_tool
+      @mixins    = mixins
+    end
+
+    def load
+      # First, load index file if present (defines mixins and root tool config)
+      index_file = File.join(@dir, INDEX_FILE)
+      load_index(index_file) if File.exist?(index_file)
+
+      # Then load all .rb files (excluding index)
+      Dir.glob(File.join(@dir, "*.rb")).sort.each do |file|
+        next if File.basename(file) == INDEX_FILE
+
+        load_tool_file(file, @root_tool)
+      end
+
+      # Load subdirectories
+      Dir.glob(File.join(@dir, "*")).sort.each do |path|
+        next unless File.directory?(path)
+        next if File.basename(path).start_with?(".")
+
+        load_subdirectory(path, @root_tool)
+      end
+    end
+
+    private
+
+    def load_index(file)
+      code    = File.read(file)
+      context = IndexDSL.new(@root_tool, @mixins)
+      context.instance_eval(code, file)
+    end
+
+    def load_tool_file(file, parent)
+      name = File.basename(file, ".rb")
+      tool = Tool.new(name, parent: parent)
+
+      code = File.read(file)
+      TaskFileDSL.evaluate(tool, code, file)
+
+      parent.add_subtool(tool)
+    end
+
+    def load_subdirectory(dir, parent)
+      name = File.basename(dir)
+      tool = Tool.new(name, parent: parent)
+
+      # Check for index file in subdirectory
+      index_file = File.join(dir, INDEX_FILE)
+      if File.exist?(index_file)
+        code = File.read(index_file)
+        TaskFileDSL.evaluate(tool, code, index_file)
+      end
+
+      # Load .rb files in subdirectory
+      Dir.glob(File.join(dir, "*.rb")).sort.each do |file|
+        next if File.basename(file) == INDEX_FILE
+
+        load_tool_file(file, tool)
+      end
+
+      # Recurse into nested subdirectories
+      Dir.glob(File.join(dir, "*")).sort.each do |path|
+        next unless File.directory?(path)
+        next if File.basename(path).start_with?(".")
+
+        load_subdirectory(path, tool)
+      end
+
+      parent.add_subtool(tool) if tool.desc || tool.subtools.any? || tool.run_block
+    end
+  end
+
+  # DSL for index files - can define mixins
+  class IndexDSL
+    def initialize(tool, mixins)
+      @tool   = tool
+      @mixins = mixins
+      @dsl    = DSL.new(tool)
+    end
+
+    # Define a mixin
+    def mixin(name, &block) = @mixins[name.to_s] = block
+
+    # Forward to regular DSL
+    def desc(text) = @dsl.desc(text)
+
+    def long_desc(text) = @dsl.long_desc(text)
+
+    def flag(name, *specs, **) = @dsl.flag(name, *specs, **)
+
+    def required_arg(name, **) = @dsl.required_arg(name, **)
+
+    def optional_arg(name, **) = @dsl.optional_arg(name, **)
+
+    def tool(name, &) = @dsl.tool(name, &)
+
+    def to_run(&) = @dsl.to_run(&)
+
+    # Capture run method
+    def run
+      # Will be captured by method definition
+    end
+
+    # Allow arbitrary methods (for mixin definitions)
+    def method_missing(name, *args, &)
+      # Ignore - these are likely mixin method definitions
+    end
+
+    def respond_to_missing?(_name, _include_private = false) = true
+  end
+end

data/lib/devex/output.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "erb"
+require_relative "support/ansi"
+
+module Devex
+  # Output helpers for tasks that respect runtime context.
+  #
+  # Provides styled output methods that automatically adapt to the environment:
+  # - Full color and unicode in interactive terminals
+  # - Plain text in agent mode, CI, or piped output
+  # - JSON-structured output when explicitly requested
+  #
+  # Usage in tasks:
+  #   include Devex::Output
+  #   header "Running tests"
+  #   success "All tests passed"
+  #   error "Build failed"
+  #   warn "Deprecated API used"
+  #
+  # See docs/ref/io-handling.md for design rationale.
+  #
+  module Output
+    # Unicode 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
+
+    # Color definitions (truecolor RGB values)
+    COLORS = {
+      success:  [0x5A, 0xF7, 0x8E],      # Green
+      error:    [0xFF, 0x6B, 0x6B],        # Red
+      warning:  [0xFF, 0xE6, 0x6D],      # Yellow
+      info:     [0x6B, 0xC5, 0xFF],         # Blue
+      header:   [0xC4, 0xB5, 0xFD],       # Purple
+      muted:    [0x88, 0x88, 0x88],        # Gray
+      emphasis: [0xFF, 0xFF, 0xFF]      # White
+    }.freeze
+
+    class << self
+      # Get symbol - always unicode (basic unicode works everywhere)
+      def symbol(name) = SYMBOLS.fetch(name, name.to_s)
+
+      # Apply color to text if colors are enabled
+      def colorize(text, color_name)
+        return text unless Context.color?
+
+        rgb = COLORS[color_name]
+        return text unless rgb
+
+        Support::ANSI[text, rgb]
+      end
+
+      # --- Primary output methods ---
+
+      # Print a section header
+      def header(text, io: $stderr)
+        if Context.agent_mode?
+          io.puts "=== #{text} ==="
+        else
+          styled = colorize(text, :header)
+          io.puts
+          io.puts styled
+          io.puts colorize("─" * text.length, :muted)
+        end
+      end
+
+      # Print a success message
+      def success(text, io: $stderr)
+        sym = symbol(:success)
+        if Context.color?
+          io.puts "#{colorize(sym, :success)} #{text}"
+        else
+          io.puts "#{sym} #{text}"
+        end
+      end
+
+      # Print an error message
+      def error(text, io: $stderr)
+        sym = symbol(:error)
+        if Context.color?
+          io.puts "#{colorize(sym, :error)} #{colorize(text, :error)}"
+        else
+          io.puts "#{sym} #{text}"
+        end
+      end
+
+      # Print a warning message
+      def warn(text, io: $stderr)
+        sym = symbol(:warning)
+        if Context.color?
+          io.puts "#{colorize(sym, :warning)} #{text}"
+        else
+          io.puts "#{sym} #{text}"
+        end
+      end
+
+      # Print an info message
+      def info(text, io: $stderr)
+        sym = symbol(:info)
+        if Context.color?
+          io.puts "#{colorize(sym, :info)} #{text}"
+        else
+          io.puts "#{sym} #{text}"
+        end
+      end
+
+      # Print muted/secondary text
+      def muted(text, io: $stderr) = io.puts colorize(text, :muted)
+
+      # Print a bullet point
+      def bullet(text, io: $stderr)
+        sym = symbol(:bullet)
+        io.puts "  #{sym} #{text}"
+      end
+
+      # Print an indented line
+      def indent(text, level: 1, io: $stdout) = io.puts "#{' ' * (level * 2)}#{text}"
+
+      # --- Structured output ---
+
+      # Output data in the requested format
+      # Respects --format flag if provided, defaults to text
+      #
+      # For composed tools outputting multiple documents:
+      # - JSON: outputs as JSONL (one JSON object per line)
+      # - YAML: uses --- between documents, ... at the end
+      def data(obj, format: nil, io: $stdout)
+        format ||= Context.agent_mode? ? :json : :text
+
+        case format.to_sym
+        when :json
+          require "json"
+          io.print JSON.generate(obj), "\n"
+        when :yaml
+          require "yaml"
+          # YAML.dump adds --- automatically, we just ensure clean output
+          io.print obj.to_yaml
+        else
+          io.print obj.to_s, "\n"
+        end
+      end
+
+      # Start a new YAML document (use between multiple outputs)
+      # The first document doesn't need this - YAML.dump adds --- automatically
+      def yaml_document_separator(io: $stdout) = io.print "---\n"
+
+      # End the YAML stream (use after all documents are written)
+      def yaml_end_stream(io: $stdout) = io.print "...\n"
+
+      # Output multiple objects as a YAML stream with proper separators
+      def yaml_stream(objects, io: $stdout)
+        require "yaml"
+        objects.each_with_index do |obj, i|
+          yaml_document_separator(io: io) if i > 0
+          io.print obj.to_yaml.sub(/\A---\n?/, "") # Remove auto-added ---
+        end
+        yaml_end_stream(io: io)
+      end
+
+      # Output multiple objects as JSONL (JSON Lines)
+      def jsonl_stream(objects, io: $stdout)
+        require "json"
+        objects.each do |obj|
+          io.print JSON.generate(obj), "\n"
+        end
+      end
+
+      # --- Template rendering ---
+
+      # Render an ERB template string with the given binding
+      def render_template(template_string, bind = nil)
+        erb = ERB.new(template_string, trim_mode: "-")
+        erb.result(bind || binding)
+      end
+
+      # Render an ERB template file
+      def render_template_file(path, bind = nil)
+        template = File.read(path)
+        render_template(template, bind)
+      end
+
+      # --- Progress indicators ---
+
+      # Print a progress indicator (only in interactive mode)
+      def progress(current, total, label: nil, io: $stderr)
+        return if Context.agent_mode?
+        return unless Context.interactive?
+
+        pct       = (current.to_f / total * 100).round
+        bar_width = 20
+        filled    = (bar_width * current / total).round
+        empty     = bar_width - filled
+
+        bar        = ("█" * filled) + ("░" * empty)
+        label_text = label ? "#{label}: " : ""
+
+        # Use carriage return to update in place
+        io.print "\r#{label_text}[#{bar}] #{pct}% (#{current}/#{total})"
+        io.puts if current >= total
+      end
+
+      # Clear the current line (for progress updates)
+      def clear_line(io: $stderr)
+        return unless Context.interactive?
+
+        io.print "\r\e[K"
+      end
+    end
+
+    # Instance methods that delegate to class methods
+    # These are included when a task does `include Devex::Output`
+
+    def header(text) = Output.header(text)
+
+    def success(text) = Output.success(text)
+
+    def error(text) = Output.error(text)
+
+    def warn(text) = Output.warn(text)
+
+    def info(text) = Output.info(text)
+
+    def muted(text) = Output.muted(text)
+
+    def bullet(text) = Output.bullet(text)
+
+    def indent(text, level: 1) = Output.indent(text, level: level)
+
+    def data(obj, format: nil) = Output.data(obj, format: format)
+
+    def yaml_stream(objects) = Output.yaml_stream(objects)
+
+    def jsonl_stream(objects) = Output.jsonl_stream(objects)
+
+    def yaml_document_separator = Output.yaml_document_separator
+
+    def yaml_end_stream = Output.yaml_end_stream
+
+    def render_template(template_string, bind = nil) = Output.render_template(template_string, bind)
+
+    def render_template_file(path, bind = nil) = Output.render_template_file(path, bind)
+
+    def progress(current, total, label: nil) = Output.progress(current, total, label: label)
+
+    def clear_line = Output.clear_line
+  end
+end

data/lib/devex/project_paths.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+require_relative "support/path"
+require_relative "dirs"
+
+module Devex
+  # Project path resolution with lazy discovery and fail-fast feedback.
+  #
+  # Access conventional project locations via the `prj` object:
+  #
+  #   prj.root        # Project root directory
+  #   prj.lib         # lib/
+  #   prj.test        # test/ or spec/ (discovered)
+  #   prj.config      # config file path
+  #   prj["**/*.rb"]  # Glob from project root
+  #
+  # Paths are resolved lazily on first access. If a conventional path
+  # doesn't exist, you get a clear error with remediation steps.
+  #
+  # @example Core usage with custom config
+  #   config = Devex::Core::Configuration.new(
+  #     organized_dir: ".mycli",
+  #     config_file: ".mycli.yml"
+  #   )
+  #   prj = Devex::ProjectPaths.new(root: project_root, config: config)
+  #
+  class ProjectPaths
+    Path = Support::Path
+
+    # Default conventional path mappings
+    # Values can be:
+    #   - String: exact path relative to root
+    #   - Array: list of alternatives (first existing wins)
+    #   - Symbol: special handler method
+    #   - String with *: glob pattern
+    #   - nil: returns root
+    DEFAULT_CONVENTIONS = {
+      root:           nil,                # Always project_dir
+      git:            ".git",
+      lib:            "lib",
+      src:            "src",
+      bin:            "bin",
+      exe:            "exe",
+      test:           %w[test spec tests],
+      features:       "features",
+      property_tests: "property_tests",
+      simulations:    "simulations",
+      spec_tests:     "specification_tests",
+      types:          "sig",
+      docs:           %w[docs doc documentation],
+      system_docs:    "system_docs",
+      version:        :detect_version,
+      gemfile:        "Gemfile",
+      gemspec:        "*.gemspec",
+      linter:         %w[.standard.yml .rubocop.yml],
+      mise:           %w[.mise.toml .tool-versions],
+      env:            ".env",
+      tmp:            "tmp",
+      log:            "log",
+      vendor:         "vendor",
+      db:             "db",
+      config_dir:     "config",
+      scripts:        "scripts"
+    }.freeze
+
+    # dx-specific conventions (added when no config provided)
+    DX_CONVENTIONS = {
+      dx:             ".dx",
+      config:         :detect_config,
+      tools:          :detect_tools,
+      templates:      :detect_templates,
+      hooks:          :detect_hooks
+    }.freeze
+
+    # @param root [String, Path, nil] project root (defaults to Dirs.project_dir)
+    # @param config [Core::Configuration, nil] configuration for customization
+    # @param overrides [Hash] explicit path overrides
+    def initialize(root: nil, config: nil, overrides: {})
+      @root      = root ? Path[root] : Dirs.project_dir
+      @config    = config
+      @overrides = overrides.transform_keys(&:to_sym)
+      @cache     = {}
+    end
+
+    # Project root directory
+    attr_reader :root
+
+    # Framework configuration (if any)
+    # Note: Named `configuration` to avoid shadowing the `config` path accessor
+    def configuration
+      @config
+    end
+
+    # Glob from project root
+    def [](pattern, **) = @root[pattern, **]
+
+    # Is this project in organized mode? (organized_dir exists)
+    def organized_mode?
+      @organized ||= begin
+        org_dir = organized_dir_name
+        org_dir && (@root / org_dir).directory?
+      end
+    end
+
+    # Dynamic path resolution
+    def method_missing(name, *args, &)
+      return super unless conventions.key?(name) || @overrides.key?(name)
+
+      @cache[name] ||= resolve(name)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      conventions.key?(name) || @overrides.key?(name) || super
+    end
+
+    private
+
+    # Merged conventions (config overrides + defaults)
+    def conventions
+      @conventions ||= begin
+        base = DEFAULT_CONVENTIONS.dup
+
+        # Add dx-specific conventions unless config specifies otherwise
+        if @config
+          # Add organized_dir convention if configured
+          base[:organized_dir] = @config.organized_dir if @config.organized_dir
+          # Add config/tools/templates/hooks with detection
+          base[:config] = :detect_config if @config.config_file || @config.organized_dir
+          base[:tools] = :detect_tools
+          base[:templates] = :detect_templates
+          base[:hooks] = :detect_hooks
+          # Merge custom conventions from config
+          base.merge!(@config.path_conventions) if @config.path_conventions
+        else
+          # No config = dx mode for backward compatibility
+          base.merge!(DX_CONVENTIONS)
+        end
+
+        base
+      end
+    end
+
+    # Name of organized mode directory (e.g., ".dx", ".mycli")
+    def organized_dir_name
+      @config&.organized_dir || ".dx"
+    end
+
+    # Name of simple mode config file (e.g., ".dx.yml", ".mycli.yml")
+    def config_file_name
+      @config&.config_file || ".dx.yml"
+    end
+
+    def resolve(name)
+      # Check overrides first
+      if @overrides.key?(name)
+        path = @root / @overrides[name]
+        return path if path.exist?
+
+        return fail_missing!(name, [@overrides[name]])
+      end
+
+      # Special handlers
+      convention = conventions[name]
+      case convention
+      when nil    then @root  # root returns the root
+      when Symbol then send(convention)
+      when Array
+        found = convention.map { |p| @root / p }.find(&:exist?)
+        found || fail_missing!(name, convention)
+      when String
+        if convention.include?("*")
+          # Glob pattern
+          matches = @root.glob(convention)
+          matches.first || fail_missing!(name, [convention])
+        else
+          path = @root / convention
+          path.exist? ? path : fail_missing!(name, [convention])
+        end
+      else
+        fail_missing!(name, [convention.to_s])
+      end
+    end
+
+    # ─────────────────────────────────────────────────────────────
+    # Special Detection Methods
+    # ─────────────────────────────────────────────────────────────
+
+    def detect_config
+      org_dir_name = organized_dir_name
+      cfg_file_name = config_file_name
+
+      org_dir = org_dir_name ? (@root / org_dir_name) : nil
+      cfg_file = cfg_file_name ? (@root / cfg_file_name) : nil
+
+      # Check for conflict (both exist)
+      if org_dir&.exist? && cfg_file&.exist?
+        fail_config_conflict!(org_dir, cfg_file)
+      elsif org_dir&.exist?
+        org_dir / "config.yml"
+      elsif cfg_file
+        cfg_file  # May or may not exist
+      else
+        @root / "config.yml"  # Fallback
+      end
+    end
+
+    def detect_tools
+      if organized_mode?
+        @root / organized_dir_name / "tools"
+      else
+        @root / (@config&.tools_dir || "tools")
+      end
+    end
+
+    def detect_templates
+      if organized_mode?
+        @root / organized_dir_name / "templates"
+      else
+        @root / "templates"
+      end
+    end
+
+    def detect_hooks
+      if organized_mode?
+        @root / organized_dir_name / "hooks"
+      else
+        @root / "hooks"
+      end
+    end
+
+    def detect_version
+      # Check common version file locations
+      candidates = [
+        @root / "VERSION",
+        @root / "version"
+      ]
+
+      # Also check lib/*/version.rb patterns
+      version_rbs = @root.glob("lib/*/version.rb")
+      candidates.concat(version_rbs)
+
+      found = candidates.find(&:exist?)
+      found || fail_missing!(:version, ["VERSION", "lib/*/version.rb"])
+    end
+
+    # ─────────────────────────────────────────────────────────────
+    # Fail-Fast with Feedback
+    # ─────────────────────────────────────────────────────────────
+
+    def fail_missing!(name, tried)
+      cfg_file = config_file_name || "config file"
+
+      message = <<~ERR
+        ERROR: Project #{name} directory not found
+
+          Looked for: #{tried.join(', ')}
+          Project root: #{@root}
+
+          To configure a custom location, add to #{cfg_file}:
+            paths:
+              #{name}: your/#{name}/dir/
+
+        Exit code: 78 (EX_CONFIG)
+      ERR
+
+      raise message
+    end
+
+    def fail_config_conflict!(org_dir, cfg_file)
+      org_dir_time = begin
+        org_dir.mtime
+      rescue StandardError
+        Time.now
+      end
+      cfg_file_time = begin
+        cfg_file.mtime
+      rescue StandardError
+        Time.now
+      end
+
+      org_name = organized_dir_name
+      cfg_name = config_file_name
+
+      message = <<~ERR
+        ERROR: Conflicting configuration
+
+          Found both:
+            #{cfg_name}      (modified: #{cfg_file_time.strftime('%Y-%m-%d %H:%M:%S')})
+            #{org_name}/         (modified: #{org_dir_time.strftime('%Y-%m-%d %H:%M:%S')})
+
+          Please use one or the other:
+            - Simple:    #{cfg_name} + tools/
+            - Organized: #{org_name}/config.yml + #{org_name}/tools/
+
+          To migrate from simple to organized:
+            mkdir -p #{org_name}
+            mv #{cfg_name} #{org_name}/config.yml
+            mv tools/ #{org_name}/tools/
+
+        Exit code: 78 (EX_CONFIG)
+      ERR
+
+      raise message
+    end
+  end
+
+  # Backward compatibility: CONVENTIONS constant
+  ProjectPaths::CONVENTIONS = ProjectPaths::DEFAULT_CONVENTIONS.merge(ProjectPaths::DX_CONVENTIONS).freeze
+end