legionio 1.4.53 → 1.4.58

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c0d47e1dc027fcf06d57aad2e04cc5217189555f4c2801bad0339bd97b2cef4
-  data.tar.gz: 591da91efe655fe18c84fa248ef9446c0708d06d5a4ddab2fc7b785ef95aedfc
+  metadata.gz: b941e35cffdc0cee05b505548896ec05866dc24c517f42ecc4d9a3f16a77c53f
+  data.tar.gz: f0e5f2a91dc3627a3124bd9cbe74fb02ed235fad0fee966b221e48acc935bee7
 SHA512:
-  metadata.gz: 4736ccb5a8f385295543757bc8a8e7d26d4aa70fe7fce868cae656dc8217e5c409e82f429c813bb61e8d44c1144587fd6979b06827872df26f44fc959be1371c
-  data.tar.gz: 35888fd8a241fac71a4d5738b8322b33fdff3114ce2001ad4098d3fb0c84bafdd4c3d5d04febeb8f2a7ee90fd61f800135ec72c37011efe39071fc4097d60764
+  metadata.gz: 67561fe5e20de1e404b63218fa971989d44767ff9df893ddc922598e94086e14b5134884c434264bb47449065018c8fe99dad88274c3ed629be0f98345ac0036
+  data.tar.gz: fcb1fbe1f834f856410ce41d319dabc115bbbccbd23562783d26cc0efc8672c09eae205a5e7c376533744008cd3675f8b2208b393ba2e0dbc6335d4cb8e27ed8

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Legion Changelog
 
+## [1.4.58] - 2026-03-17
+
+### Added
+- `legion lex list` now groups output by category (tier order) by default.
+- `legion lex list CATEGORY` filters the list to a specific category (e.g., `legion lex list agentic`).
+- `--flat` option to `legion lex list` restores the original flat table without grouping.
+- `category` and `tier` columns added to the extension table in all display modes.
+- `discover_all` now includes `:category` and `:tier` keys in each extension info hash,
+  derived via `Legion::Extensions::Helpers::Segments.categorize_gem`.
+- Results sorted by tier then name for deterministic ordering.
+
+## [1.4.57] - 2026-03-17
+
+### Added
+- `--category` option to `legion lex create`: generates categorized extension gems with nested module
+  declarations, nested directory structure, and correct `VERSION` constant paths.
+  Example: `legion lex create cognitive-anchor --category agentic` produces gem `lex-agentic-cognitive-anchor`
+  with module `Legion::Extensions::Agentic::Cognitive::Anchor`.
+- `LexGenerator` now accepts `gem_name:` keyword argument and uses `Legion::Extensions::Helpers::Segments`
+  to derive all namespace, const, and require-path values for both flat and nested extensions.
+- `legion lex create` emits a warning via `Legion::Extensions.check_reserved_words` when reserved
+  category prefixes or framework words are used in the gem name.
+
+## [1.4.56] - 2026-03-17
+
+### Fixed
+- `lex_class` now returns the full extension module constant by walking the namespace up to the first `NAMESPACE_BOUNDARIES` word, instead of always stopping at index 2. For nested extensions (`Legion::Extensions::Agentic::Cognitive::Anchor`), this returns `Legion::Extensions::Agentic::Cognitive::Anchor` rather than the incorrect `Legion::Extensions::Agentic`.
+- `lex_const` now derives from `lex_class.to_s.split('::').last` so it returns the extension's root constant name (`Anchor`) rather than always returning the third element of the namespace array.
+- `full_path` now builds the gem name from dash-joined segments (`lex-agentic-cognitive-anchor`) instead of underscore-joined `lex_name`, so `Gem::Specification.find_by_name` works for nested extensions.
+
+## [1.4.55] - 2026-03-17
+
+### Changed
+- `build_default_exchange` now sets `exchange_name` on dynamically created exchange classes to return `amqp_prefix` (dot-joined segments with `legion.` prefix) instead of defaulting to the parent class behavior
+- `auto_create_exchange` now derives `exchange_name` from `amqp_prefix` + the exchange's own downcased class name, replacing the index-based `split('::')[5].downcase` extraction that broke for nested extension namespaces
+### Fixed
+- `legion config scaffold` now writes to `~/.legionio/settings/` by default instead of `./settings/`
+- Removed Thor `default: './settings'` that shadowed the Ruby fallback in `ConfigScaffold.run`
+- Added `~/.legionio/settings` to `legion config path` search paths to match `Service#default_paths`
+
+## [1.4.54] - 2026-03-17
+
+### Changed
+- `Helpers::Logger#log` now passes `lex_segments:` array to `Legion::Logging::Logger` when the object responds to `:segments`
+- Falls back to `lex:` string for legacy flat extensions that do not implement `:segments`
+
 ## [1.4.53] - 2026-03-17
 
 ### Fixed

data/lib/legion/cli/config_command.rb

@@ -167,12 +167,12 @@ module Legion
       desc 'scaffold', 'Generate starter config files for each subsystem'
       long_desc <<~DESC
         Generates JSON config files for LegionIO subsystems (transport, data, cache,
-        crypt, logging, llm). Files are written to --dir (default: ./settings/).
+        crypt, logging, llm). Files are written to --dir (default: ~/.legionio/settings/).
 
         By default, generates minimal starter files with only the most commonly
         changed fields. Use --full for the complete schema with all defaults.
       DESC
-      option :dir, type: :string, default: './settings', desc: 'Output directory'
+      option :dir, type: :string, desc: 'Output directory (default: ~/.legionio/settings)'
       option :only, type: :string, desc: 'Comma-separated subsystems (transport,data,cache,crypt,logging,llm)'
       option :full, type: :boolean, default: false, desc: 'Include all fields with defaults'
       option :force, type: :boolean, default: false, desc: 'Overwrite existing files'
@@ -194,6 +194,7 @@ module Legion
           active_found = false
           [
             '/etc/legionio',
+            File.expand_path('~/.legionio/settings'),
             File.expand_path('~/legionio'),
             File.expand_path('./settings')
           ].map do |path|

data/lib/legion/cli/lex_command.rb

@@ -1,10 +1,18 @@
 # frozen_string_literal: true
 
 require 'fileutils'
+require 'legion/extensions/helpers/segments'
 
 module Legion
   module CLI
     class Lex < Thor
+      DEFAULT_CATEGORIES = {
+        core:    { type: :list, tier: 1 },
+        ai:      { type: :list, tier: 2 },
+        gaia:    { type: :list, tier: 3 },
+        agentic: { type: :prefix, tier: 4 }
+      }.freeze
+
       def self.exit_on_failure?
         true
       end
@@ -12,32 +20,21 @@ module Legion
       class_option :json, type: :boolean, default: false, desc: 'Output as JSON'
       class_option :no_color, type: :boolean, default: false, desc: 'Disable color output'
 
-      desc 'list', 'List all installed extensions'
-      option :all, type: :boolean, default: false, aliases: ['-a'], desc: 'Include disabled extensions'
-      def list
-        out = formatter
+      desc 'list [CATEGORY]', 'List all installed extensions, optionally filtered by category'
+      option :all,  type: :boolean, default: false, aliases: ['-a'], desc: 'Include disabled extensions'
+      option :flat, type: :boolean, default: false, desc: 'Show all extensions in a flat list without category grouping'
+      def list(category = nil)
+        out  = formatter
         lexs = discover_all
 
-        rows = if options[:all]
-                 lexs
-               else
-                 lexs.reject { |l| l[:status] == 'disabled' }
-               end
-
-        table_rows = rows.map do |l|
-          [
-            l[:name],
-            l[:version],
-            out.status(l[:status]),
-            l[:runners].to_s,
-            l[:actors].to_s
-          ]
-        end
+        rows = options[:all] ? lexs : lexs.reject { |l| l[:status] == 'disabled' }
+        rows = rows.select { |l| l[:category] == category } if category
 
-        out.table(
-          %w[name version status runners actors],
-          table_rows
-        )
+        if options[:flat] || category
+          render_flat_table(out, rows)
+        else
+          render_grouped_table(out, rows)
+        end
       end
       default_task :list
 
@@ -92,13 +89,22 @@ module Legion
       end
 
       desc 'create NAME', 'Scaffold a new Legion extension'
-      option :rspec, type: :boolean, default: true, desc: 'Include RSpec setup'
-      option :github_ci, type: :boolean, default: true, desc: 'Include GitHub Actions CI'
-      option :git_init, type: :boolean, default: true, desc: 'Initialize git repository'
-      option :bundle_install, type: :boolean, default: true, desc: 'Run bundle install'
+      method_option :rspec, type: :boolean, default: true, desc: 'Include RSpec setup'
+      method_option :github_ci, type: :boolean, default: true, desc: 'Include GitHub Actions CI'
+      method_option :git_init, type: :boolean, default: true, desc: 'Initialize git repository'
+      method_option :bundle_install, type: :boolean, default: true, desc: 'Run bundle install'
+      method_option :category, type: :string, default: nil,
+                               desc: 'Extension category (agentic, ai, gaia). Determines namespace nesting and gem prefix.'
       def create(name)
         out = formatter
-        target_dir = "lex-#{name}"
+
+        if options[:category] && options[:category] !~ /\A[a-z][a-z0-9_-]*\z/
+          out.error('--category must be lowercase letters, numbers, underscores, or hyphens')
+          return
+        end
+
+        gem_name = options[:category] ? "lex-#{options[:category]}-#{name}" : "lex-#{name}"
+        target_dir = gem_name
 
         if Dir.exist?(target_dir)
           out.error("Directory #{target_dir} already exists")
@@ -110,15 +116,17 @@ module Legion
           raise SystemExit, 1
         end
 
-        out.success("Creating lex-#{name}...")
+        Legion::Extensions.check_reserved_words(gem_name, known_org: false)
+
+        out.success("Creating #{gem_name}...")
 
         vars = { filename: target_dir, class_name: name.split('_').map(&:capitalize).join, lex: name }
 
-        generator = LexGenerator.new(name, vars, options)
+        generator = LexGenerator.new(name, vars, options, gem_name: gem_name)
         generator.generate(out)
 
         out.spacer
-        out.success("Extension lex-#{name} created in ./#{target_dir}")
+        out.success("Extension #{gem_name} created in ./#{target_dir}")
         out.spacer
         puts '  Next steps:'
         puts "    cd #{target_dir}"
@@ -166,6 +174,25 @@ module Legion
           )
         end
 
+        def render_flat_table(out, rows)
+          table_rows = rows.map do |l|
+            [l[:name], l[:version], l[:category].to_s, l[:tier].to_s, out.status(l[:status]), l[:runners].to_s, l[:actors].to_s]
+          end
+          out.table(%w[name version category tier status runners actors], table_rows)
+        end
+
+        def render_grouped_table(out, rows)
+          grouped = rows.group_by { |l| [l[:tier], l[:category]] }
+          grouped.keys.sort_by { |tier, cat| [tier, cat.to_s] }.each do |key|
+            tier, cat = key
+            out.header("=== #{cat} (tier #{tier}) ===")
+            group_rows = grouped[key].map do |l|
+              [l[:name], l[:version], l[:category].to_s, l[:tier].to_s, out.status(l[:status]), l[:runners].to_s, l[:actors].to_s]
+            end
+            out.table(%w[name version category tier status runners actors], group_rows)
+          end
+        end
+
         def discover_all
           installed = Gem::Specification.select { |s| s.name.start_with?('lex-') }
 
@@ -177,20 +204,19 @@ module Legion
             ext_settings = {}
           end
 
+          categories = resolve_categories
+          cat_lists  = resolve_cat_lists
+
           result = installed.map do |spec|
             short_name = spec.name.sub('lex-', '')
-            class_name = short_name.split('_').map(&:capitalize).join
-            extension_class = "Legion::Extensions::#{class_name}"
+            extension_class = Legion::Extensions::Helpers::Segments.derive_const_path(spec.name)
 
             setting = ext_settings[short_name.to_sym] || {}
-            status = if setting[:enabled] == false
-                       'disabled'
-                     else
-                       'installed'
-                     end
+            status  = setting[:enabled] == false ? 'disabled' : 'installed'
 
             runner_info = extract_runners(spec)
-            actor_info = extract_actors(spec)
+            actor_info  = extract_actors(spec)
+            cat_info    = Legion::Extensions::Helpers::Segments.categorize_gem(spec.name, categories: categories, lists: cat_lists)
 
             {
               name:            short_name,
@@ -200,10 +226,25 @@ module Legion
               extension_class: extension_class,
               runners:         runner_info,
               actors:          actor_info,
-              dependencies:    spec.runtime_dependencies.map(&:to_s)
+              dependencies:    spec.runtime_dependencies.map(&:to_s),
+              category:        cat_info[:category].to_s,
+              tier:            cat_info[:tier]
             }
           end
-          result.sort_by { |l| l[:name] }
+          result.sort_by { |l| [l[:tier], l[:name]] }
+        end
+
+        def resolve_categories
+          raw = Legion::Settings.dig(:extensions, :categories)
+          raw.nil? || raw.empty? ? DEFAULT_CATEGORIES : raw
+        end
+
+        def resolve_cat_lists
+          {
+            core: Array(Legion::Settings.dig(:extensions, :core)),
+            ai:   Array(Legion::Settings.dig(:extensions, :ai)),
+            gaia: Array(Legion::Settings.dig(:extensions, :gaia))
+          }
         end
 
         def find_lex(name)
@@ -212,7 +253,8 @@ module Legion
         end
 
         def extract_runners(spec)
-          runner_dir = File.join(spec.gem_dir, 'lib', 'legion', 'extensions', spec.name.sub('lex-', ''), 'runners')
+          runner_dir = File.join(spec.gem_dir, 'lib', 'legion', 'extensions',
+                                 Legion::Extensions::Helpers::Segments.derive_segments(spec.name).join('/'), 'runners')
           return [] unless Dir.exist?(runner_dir)
 
           Dir.glob("#{runner_dir}/*.rb").map { |f| File.basename(f, '.rb') }
@@ -221,7 +263,8 @@ module Legion
         end
 
         def extract_actors(spec)
-          actor_dir = File.join(spec.gem_dir, 'lib', 'legion', 'extensions', spec.name.sub('lex-', ''), 'actors')
+          actor_dir = File.join(spec.gem_dir, 'lib', 'legion', 'extensions',
+                                Legion::Extensions::Helpers::Segments.derive_segments(spec.name).join('/'), 'actors')
           return [] unless Dir.exist?(actor_dir)
 
           Dir.glob("#{actor_dir}/*.rb").map do |f|
@@ -255,11 +298,12 @@ module Legion
 
     # Thin generator class that wraps the template logic
     class LexGenerator
-      def initialize(name, vars, options)
-        @name = name
-        @vars = vars
+      def initialize(name, vars, options, gem_name: nil)
+        @name    = name
+        @vars    = vars
         @options = options
-        @target = "lex-#{name}"
+        @gem_name = gem_name || "lex-#{name}"
+        @target = @gem_name
       end
 
       def generate(out)
@@ -270,24 +314,76 @@ module Legion
 
       private
 
-      def create_structure(out)
+      attr_reader :gem_name
+
+      def target_dir
+        @target
+      end
+
+      def namespace_segments
+        @namespace_segments ||= Legion::Extensions::Helpers::Segments.derive_namespace(@gem_name)
+      end
+
+      def const_path
+        @const_path ||= Legion::Extensions::Helpers::Segments.derive_const_path(@gem_name)
+      end
+
+      def require_path
+        @require_path ||= Legion::Extensions::Helpers::Segments.derive_require_path(@gem_name)
+      end
+
+      def extension_dirs
+        base = "#{@target}/lib/legion/extensions"
+        segs = Legion::Extensions::Helpers::Segments.derive_segments(@gem_name)
         dirs = [
           @target,
           "#{@target}/lib",
           "#{@target}/lib/legion",
-          "#{@target}/lib/legion/extensions",
-          "#{@target}/lib/legion/extensions/#{@name}",
-          "#{@target}/lib/legion/extensions/#{@name}/runners",
-          "#{@target}/lib/legion/extensions/#{@name}/actors",
-          "#{@target}/lib/legion/extensions/#{@name}/tools",
+          base
+        ]
+        segs.each_with_index do |_, i|
+          dirs << "#{base}/#{segs[0..i].join('/')}"
+        end
+        dirs += [
+          "#{base}/#{segs.join('/')}/runners",
+          "#{base}/#{segs.join('/')}/actors",
+          "#{base}/#{segs.join('/')}/tools",
           "#{@target}/spec",
           "#{@target}/spec/legion"
         ]
+        dirs
+      end
+
+      def module_open_lines
+        indent = '  '
+        lines = ["module Legion\n", "#{indent}module Extensions\n"]
+        namespace_segments.each_with_index do |seg, i|
+          lines << "#{indent * (i + 2)}module #{seg}\n"
+        end
+        lines
+      end
+
+      def module_close_lines
+        depth = namespace_segments.length + 2
+        (1..depth).map { |i| "#{'  ' * (depth - i)}end\n" }
+      end
+
+      def nested_module_wrap(inner_lines)
+        opens  = module_open_lines
+        closes = module_close_lines
+        (opens + inner_lines + closes).join
+      end
 
+      def create_structure(out)
+        dirs = extension_dirs
         dirs << "#{@target}/.github/workflows" if @options[:github_ci]
 
         dirs.each { |d| FileUtils.mkdir_p(d) }
-        FileUtils.touch("#{@target}/lib/legion/extensions/#{@name}/tools/.gitkeep")
+
+        ext_base = "lib/legion/extensions/#{Legion::Extensions::Helpers::Segments.derive_segments(@gem_name).join('/')}"
+        FileUtils.touch("#{@target}/#{ext_base}/tools/.gitkeep")
+
+        entry_file = "lib/legion/extensions/#{require_path.split('legion/extensions/').last}"
 
         write_template("#{@target}/#{@target}.gemspec", gemspec_content)
         write_template("#{@target}/Gemfile", gemfile_content)
@@ -295,13 +391,15 @@ module Legion
         write_template("#{@target}/.rubocop.yml", rubocop_content)
         write_template("#{@target}/LICENSE", license_content)
         write_template("#{@target}/README.md", readme_content)
-        write_template("#{@target}/lib/legion/extensions/#{@name}.rb", extension_entry_content)
-        write_template("#{@target}/lib/legion/extensions/#{@name}/version.rb", version_content)
-        write_template("#{@target}/lib/legion/extensions/#{@name}/client.rb", client_content)
+        write_template("#{@target}/lib/#{entry_file}.rb", extension_entry_content)
+        write_template("#{@target}/#{ext_base}/version.rb", version_content)
+        write_template("#{@target}/#{ext_base}/client.rb", client_content)
 
         if @options[:rspec]
+          spec_relative = Legion::Extensions::Helpers::Segments.derive_segments(@gem_name).join('/')
+          FileUtils.mkdir_p("#{@target}/spec/legion/extensions/#{File.dirname(spec_relative)}")
           write_template("#{@target}/spec/spec_helper.rb", spec_helper_content)
-          write_template("#{@target}/spec/legion/#{@name}_spec.rb", spec_content)
+          write_template("#{@target}/spec/legion/extensions/#{spec_relative}_spec.rb", spec_content)
         end
 
         if @options[:github_ci]
@@ -336,16 +434,16 @@ module Legion
         <<~RUBY
           # frozen_string_literal: true
 
-          require_relative 'lib/legion/extensions/#{@name}/version'
+          require_relative 'lib/#{require_path}/version'
 
           Gem::Specification.new do |spec|
-            spec.name          = '#{@target}'
-            spec.version       = Legion::Extensions::#{@vars[:class_name]}::VERSION
+            spec.name          = '#{@gem_name}'
+            spec.version       = #{const_path}::VERSION
             spec.authors       = ['Esity']
             spec.email         = ['matthewdiverson@gmail.com']
-            spec.summary       = 'A LegionIO Extension for #{@vars[:class_name]}'
-            spec.description   = 'A LegionIO Extension (LEX) for #{@vars[:class_name]}'
-            spec.homepage      = 'https://github.com/LegionIO/#{@target}'
+            spec.summary       = 'A LegionIO Extension for #{namespace_segments.last}'
+            spec.description   = 'A LegionIO Extension (LEX) for #{namespace_segments.last}'
+            spec.homepage      = 'https://github.com/LegionIO/#{@gem_name}'
             spec.license       = 'MIT'
             spec.required_ruby_version = '>= 3.4'
 
@@ -432,14 +530,14 @@ module Legion
 
       def readme_content
         <<~MD
-          # lex-#{@name}
+          # #{@gem_name}
 
-          A [LegionIO](https://github.com/LegionIO) extension for #{@vars[:class_name]}.
+          A [LegionIO](https://github.com/LegionIO) extension for #{namespace_segments.last}.
 
           ## Installation
 
           ```ruby
-          gem 'lex-#{@name}'
+          gem '#{@gem_name}'
           ```
 
           ## Usage
@@ -461,64 +559,44 @@ module Legion
       end
 
       def extension_entry_content
-        <<~RUBY
-          # frozen_string_literal: true
-
-          require_relative '#{@name}/version'
-          require_relative '#{@name}/client'
-
-          module Legion
-            module Extensions
-              module #{@vars[:class_name]}
-              end
-            end
-          end
-        RUBY
+        segs     = Legion::Extensions::Helpers::Segments.derive_segments(@gem_name)
+        last_seg = segs.last
+        inner    = ["  require_relative '#{last_seg}/version'\n",
+                    "  require_relative '#{last_seg}/client'\n",
+                    "\n"]
+        "# frozen_string_literal: true\n\n#{nested_module_wrap(inner)}"
       end
 
       def version_content
-        <<~RUBY
-          # frozen_string_literal: true
-
-          module Legion
-            module Extensions
-              module #{@vars[:class_name]}
-                VERSION = '0.1.0'
-              end
-            end
-          end
-        RUBY
+        depth  = namespace_segments.length + 2
+        inner  = ["#{'  ' * depth}VERSION = '0.1.0'\n"]
+        "# frozen_string_literal: true\n\n#{nested_module_wrap(inner)}"
       end
 
       def client_content
-        <<~RUBY
-          # frozen_string_literal: true
-
-          module Legion
-            module Extensions
-              module #{@vars[:class_name]}
-                class Client
-                  attr_reader :opts
-
-                  def initialize(**kwargs)
-                    @opts = kwargs
-                  end
-
-                  def connection(**override)
-                    Helpers::Client.connection(**@opts, **override)
-                  end
-                end
-              end
-            end
-          end
-        RUBY
+        depth = namespace_segments.length + 2
+        pad   = '  ' * depth
+        inner = [
+          "#{pad}class Client\n",
+          "#{pad}  attr_reader :opts\n",
+          "\n",
+          "#{pad}  def initialize(**kwargs)\n",
+          "#{pad}    @opts = kwargs\n",
+          "#{pad}  end\n",
+          "\n",
+          "#{pad}  def connection(**override)\n",
+          "#{pad}    Helpers::Client.connection(**@opts, **override)\n",
+          "#{pad}  end\n",
+          "#{pad}end\n"
+        ]
+        "# frozen_string_literal: true\n\n#{nested_module_wrap(inner)}"
       end
 
       def spec_helper_content
         <<~RUBY
           # frozen_string_literal: true
 
-          require 'legion/extensions/#{@name}'
+          require '#{require_path}'
 
           RSpec.configure do |config|
             config.expect_with :rspec do |expectations|
@@ -532,9 +610,9 @@ module Legion
         <<~RUBY
           # frozen_string_literal: true
 
-          RSpec.describe Legion::Extensions::#{@vars[:class_name]} do
+          RSpec.describe #{const_path} do
             it 'has a version number' do
-              expect(Legion::Extensions::#{@vars[:class_name]}::VERSION).not_to be_nil
+              expect(#{const_path}::VERSION).not_to be_nil
             end
           end
         RUBY

data/lib/legion/extensions/core.rb

@@ -5,6 +5,7 @@ require_relative 'builders/helpers'
 require_relative 'builders/hooks'
 require_relative 'builders/runners'
 
+require_relative 'helpers/segments'
 require_relative 'helpers/core'
 require_relative 'helpers/task'
 require_relative 'helpers/logger'

data/lib/legion/extensions/helpers/base.rb

@@ -4,19 +4,62 @@ module Legion
   module Extensions
     module Helpers
       module Base
+        # Words that mark the boundary between extension namespace segments and
+        # internal module structure. Segment extraction stops at these words.
+        NAMESPACE_BOUNDARIES = %w[Actor Actors Runners Helpers Transport Data].freeze
+
+        def segments
+          @segments ||= derive_segments_from_namespace
+        end
+
+        def lex_slug
+          segments.join('.')
+        end
+
+        def log_tag
+          Helpers::Segments.segments_to_log_tag(segments)
+        end
+
+        def amqp_prefix
+          Helpers::Segments.segments_to_amqp_prefix(segments)
+        end
+
+        def settings_path
+          Helpers::Segments.segments_to_settings_path(segments)
+        end
+
+        def table_prefix
+          Helpers::Segments.segments_to_table_prefix(segments)
+        end
+
         def lex_class
-          @lex_class ||= Kernel.const_get(calling_class_array[0..2].join('::'))
+          @lex_class ||= begin
+            parts = calling_class_array
+            ext_idx = parts.index('Extensions')
+            # All LEX extensions must be under Legion::Extensions::. If 'Extensions'
+            # is not present, this is a misconfigured caller — fail loudly.
+            raise ArgumentError, "#{calling_class} is not under Legion::Extensions namespace" unless ext_idx
+
+            end_idx = ext_idx + 1
+            end_idx += 1 while end_idx < parts.length && !NAMESPACE_BOUNDARIES.include?(parts[end_idx])
+            # NameError cannot occur here: lex_class is only ever called from autobuild,
+            # build_transport, build_runners, build_actors, and transport helpers — all of
+            # which execute while the extension module is already required and fully defined.
+            # The constant we resolve (e.g. Legion::Extensions::Http) is the very module
+            # that owns this method, so it must already exist.
+            Kernel.const_get(parts[0...end_idx].join('::'))
+          end
         end
         alias extension_class lex_class
 
         def lex_name
-          @lex_name ||= calling_class_array[2].gsub(/(?<!^)[A-Z]/) { "_#{Regexp.last_match(0)}" }.downcase
+          segments.join('_')
         end
         alias extension_name lex_name
         alias lex_filename lex_name
 
         def lex_const
-          @lex_const ||= calling_class_array[2]
+          @lex_const ||= lex_class.to_s.split('::').last
         end
 
         def calling_class
@@ -52,7 +95,12 @@ module Legion
         end
 
         def full_path
-          @full_path ||= "#{Gem::Specification.find_by_name("lex-#{lex_name}").gem_dir}/lib/legion/extensions/#{lex_filename}"
+          @full_path ||= begin
+            gem_name = "lex-#{segments.join('-')}"
+            gem_dir = Gem::Specification.find_by_name(gem_name).gem_dir
+            require_path = Helpers::Segments.derive_require_path(gem_name)
+            "#{gem_dir}/lib/#{require_path}"
+          end
         end
         alias extension_path full_path
 
@@ -78,6 +126,28 @@ module Legion
             end
           end
         end
+
+        private
+
+        def derive_segments_from_namespace
+          parts = calling_class_array
+          ext_idx = parts.index('Extensions')
+          return [camelize_to_snake(parts[0])] unless ext_idx
+
+          ext_parts = []
+          ((ext_idx + 1)...parts.length).each do |i|
+            break if NAMESPACE_BOUNDARIES.include?(parts[i])
+
+            ext_parts << camelize_to_snake(parts[i])
+          end
+          ext_parts.empty? ? [camelize_to_snake(parts[ext_idx + 1])] : ext_parts
+        end
+
+        def camelize_to_snake(str)
+          str.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+             .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+             .downcase
+        end
       end
     end
   end

data/lib/legion/extensions/helpers/logger.rb

@@ -7,8 +7,11 @@ module Legion
         def log
           return @log unless @log.nil?
 
-          logger_hash = { lex: lex_filename || nil }
-          logger_hash[:lex] = lex_filename.first if logger_hash[:lex].is_a? Array
+          logger_hash = if respond_to?(:segments)
+                          { lex_segments: Array(segments) }
+                        else
+                          { lex: lex_filename.is_a?(Array) ? lex_filename.first : lex_filename }
+                        end
           if respond_to?(:settings) && settings.key?(:logger)
             logger_hash[:level] = settings[:logger].key?(:level) ? settings[:logger][:level] : 'info'
             logger_hash[:log_file] = settings[:logger][:log_file] if settings[:logger].key? :log_file

data/lib/legion/extensions/helpers/segments.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Helpers
+      module Segments
+        module_function
+
+        def derive_segments(gem_name)
+          gem_name.delete_prefix('lex-').split('-')
+        end
+
+        def derive_namespace(gem_name)
+          derive_segments(gem_name).map { |s| s.split('_').map(&:capitalize).join }
+        end
+
+        def derive_const_path(gem_name)
+          "Legion::Extensions::#{derive_namespace(gem_name).join('::')}"
+        end
+
+        def derive_require_path(gem_name)
+          "legion/extensions/#{derive_segments(gem_name).join('/')}"
+        end
+
+        def segments_to_log_tag(segments)
+          segments.map { |s| "[#{s}]" }.join
+        end
+
+        def segments_to_amqp_prefix(segments)
+          "legion.#{segments.join('.')}"
+        end
+
+        def segments_to_settings_path(segments)
+          segments.map(&:to_sym)
+        end
+
+        def segments_to_table_prefix(segments)
+          segments.join('_')
+        end
+
+        def categorize_gem(gem_name, categories:, lists:)
+          # Check defined lists first (list membership takes priority)
+          lists.each do |cat_name, gem_list|
+            next unless categories.key?(cat_name)
+
+            return { category: cat_name, tier: categories[cat_name][:tier] } if gem_list.include?(gem_name)
+          end
+
+          # Check prefix-matched categories
+          bare = gem_name.delete_prefix('lex-')
+          categories.each do |cat_name, cat_config|
+            next unless cat_config[:type] == :prefix
+
+            return { category: cat_name, tier: cat_config[:tier] } if bare.start_with?("#{cat_name}-")
+          end
+
+          { category: :default, tier: 5 }
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/helpers/transport.rb

@@ -33,12 +33,13 @@ module Legion
         end
 
         def build_default_exchange
-          exchange = "#{transport_class}::Exchanges::#{lex_const}"
-          return Object.const_get(exchange) if transport_class::Exchanges.const_defined? lex_const
+          return transport_class::Exchanges.const_get(lex_const) if transport_class::Exchanges.const_defined? lex_const
 
-          transport_class::Exchanges.const_set(lex_const, Class.new(Legion::Transport::Exchange))
-          @default_exchange = Kernel.const_get(exchange)
-          @default_exchange
+          amqp = amqp_prefix
+          transport_class::Exchanges.const_set(lex_const, Class.new(Legion::Transport::Exchange) do
+            define_method(:exchange_name) { amqp }
+          end)
+          @default_exchange = transport_class::Exchanges.const_get(lex_const)
         end
       end
     end

data/lib/legion/extensions/transport.rb

@@ -52,10 +52,9 @@ module Legion
         end
         return build_default_exchange if default_exchange
 
+        ext_amqp = amqp_prefix
         transport_class::Exchanges.const_set(exchange.split('::').pop, Class.new(Legion::Transport::Exchange) do
-          def exchange_name
-            self.class.ancestors.first.to_s.split('::')[5].downcase
-          end
+          define_method(:exchange_name) { "#{ext_amqp}.#{self.class.to_s.split('::').last.downcase}" }
         end)
       end
 

data/lib/legion/extensions.rb

@@ -39,23 +39,25 @@ module Legion
       end
 
       def load_extensions
-        @extensions ||= {}
+        @extensions ||= []
         @loaded_extensions ||= []
-        @extensions.each do |extension, values|
-          if values.key(:enabled) && !values[:enabled]
-            Legion::Logging.info "Skipping #{extension} because it's disabled"
+        @extensions.each do |entry|
+          gem_name = entry[:gem_name]
+          ext_name = entry[:require_path].split('/').last
+
+          if Legion::Settings[:extensions].key?(ext_name.to_sym) &&
+             Legion::Settings[:extensions][ext_name.to_sym].is_a?(Hash) &&
+             Legion::Settings[:extensions][ext_name.to_sym].key?(:enabled) &&
+             !Legion::Settings[:extensions][ext_name.to_sym][:enabled]
+            Legion::Logging.info "Skipping #{gem_name} because it's disabled"
             next
           end
 
-          if Legion::Settings[:extensions].key?(extension.to_sym) && Legion::Settings[:extensions][extension.to_sym].key?(:enabled) && !Legion::Settings[:extensions][extension.to_sym][:enabled] # rubocop:disable Layout/LineLength
+          unless load_extension(entry)
+            Legion::Logging.warn("#{gem_name} failed to load")
             next
           end
-
-          unless load_extension(extension, values)
-            Legion::Logging.warn("#{extension} failed to load")
-            next
-          end
-          @loaded_extensions.push(extension)
+          @loaded_extensions.push(gem_name)
         end
         Legion::Logging.info(
           "#{@extensions.count} extensions loaded with " \
@@ -67,38 +69,47 @@ module Legion
         )
       end
 
-      def load_extension(extension, values) # rubocop:disable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/AbcSize, Metrics/MethodLength
-        return unless gem_load(values[:gem_name], extension)
+      def load_extension(entry) # rubocop:disable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity, Metrics/AbcSize, Metrics/MethodLength
+        ensure_namespace(entry[:const_path]) if entry[:segments].length > 1
+        return unless gem_load(entry)
 
-        extension = Kernel.const_get(values[:extension_class])
+        extension = Kernel.const_get(entry[:const_path])
         extension.extend Legion::Extensions::Core unless extension.singleton_class.include?(Legion::Extensions::Core)
 
-        ext_settings = Legion::Settings[:extensions][values[:extension_name]]
+        ext_name = entry[:segments].join('_')
+        ext_settings = Legion::Settings[:extensions][ext_name.to_sym]
         min_version = ext_settings[:min_version] if ext_settings.is_a?(Hash)
-        Legion::Logging.fatal values if min_version.is_a?(String) && Gem::Version.new(values[:version]) >= Gem::Version.new(min_version)
+        if min_version.is_a?(String)
+          begin
+            gem_spec = Gem::Specification.find_by_name(entry[:gem_name])
+            Legion::Logging.fatal entry if Gem::Version.new(gem_spec.version.to_s) >= Gem::Version.new(min_version)
+          rescue Gem::MissingSpecError
+            Legion::Logging.warn "Could not find gem spec for #{entry[:gem_name]}, skipping min_version check"
+          end
+        end
 
         if extension.data_required? && Legion::Settings[:data][:connected] == false
-          Legion::Logging.warn "#{values[:extension_name]} requires Legion::Data but isn't enabled, skipping"
+          Legion::Logging.warn "#{ext_name} requires Legion::Data but isn't enabled, skipping"
           return false
         end
 
         if extension.cache_required? && Legion::Settings[:cache][:connected] == false
-          Legion::Logging.warn "#{values[:extension_name]} requires Legion::Cache but isn't enabled, skipping"
+          Legion::Logging.warn "#{ext_name} requires Legion::Cache but isn't enabled, skipping"
           return false
         end
 
         if extension.crypt_required? && Legion::Settings[:crypt][:cs].nil?
-          Legion::Logging.warn "#{values[:extension_name]} requires Legion::Crypt but isn't ready, skipping"
+          Legion::Logging.warn "#{ext_name} requires Legion::Crypt but isn't ready, skipping"
           return false
         end
 
         if extension.vault_required? && Legion::Settings[:crypt][:vault][:connected] == false
-          Legion::Logging.warn "#{values[:extension_name]} requires Legion::Crypt::Vault but isn't enabled, skipping"
+          Legion::Logging.warn "#{ext_name} requires Legion::Crypt::Vault but isn't enabled, skipping"
           return false
         end
 
         if extension.llm_required? && (!Legion::Settings.key?(:llm) || Legion::Settings[:llm][:connected] == false)
-          Legion::Logging.warn "#{values[:extension_name]} requires Legion::LLM but isn't enabled, skipping"
+          Legion::Logging.warn "#{ext_name} requires Legion::LLM but isn't enabled, skipping"
           return false
         end
 
@@ -120,14 +131,14 @@ module Legion
           hook_actor(**actor)
         end
         extension.log.info "Loaded v#{extension::VERSION}"
-        Legion::Events.emit('extension.loaded', name: values[:extension_name], version: values[:version])
+        Legion::Events.emit('extension.loaded', name: ext_name, version: entry[:gem_name])
 
         begin
           if defined?(Legion::Data) && defined?(Legion::Data::Model::DigitalWorker)
-            worker_id = "lex-#{values[:extension_name]}"
+            worker_id = "lex-#{ext_name}"
             worker = Legion::Data::Model::DigitalWorker.find_or_create(worker_id: worker_id) do |w|
-              w.name            = values[:extension_name]
-              w.extension_name  = values[:extension_name]
+              w.name            = ext_name
+              w.extension_name  = ext_name
               w.lifecycle_state = 'active'
               w.risk_tier       = 'low'
               w.team            = 'extensions'
@@ -198,15 +209,27 @@ module Legion
         end
       end
 
-      def gem_load(gem_name, name)
-        gem_dir = Gem::Specification.find_by_name(gem_name).gem_dir
-        require "#{gem_dir}/lib/legion/extensions/#{name}"
+      def gem_load(entry)
+        gem_name     = entry[:gem_name]
+        require_path = entry[:require_path]
+        gem_dir      = Gem::Specification.find_by_name(gem_name).gem_dir
+        require "#{gem_dir}/lib/#{require_path}"
         true
+      rescue Gem::MissingSpecError => e
+        Legion::Logging.warn "#{gem_name} gem not found: #{e.message}"
+        nil
       rescue LoadError => e
-        Legion::Logging.error e.message
-        Legion::Logging.error e.backtrace
-        Legion::Logging.error "gem_path: #{gem_dir}" if defined?(gem_dir) && gem_dir
-        false
+        Legion::Logging.warn "#{gem_name} failed to load: #{e.message}"
+        nil
+      end
+
+      def ensure_namespace(const_path)
+        parts   = const_path.split('::')
+        current = ::Legion::Extensions
+        parts[2...-1].each do |part|
+          current.const_set(part, Module.new) unless current.const_defined?(part, false)
+          current = current.const_get(part, false)
+        end
       end
 
       def gem_names_for_discovery
@@ -222,17 +245,11 @@ module Legion
         return if role.nil? || role[:profile].nil?
 
         profile = role[:profile].to_sym
-        allowed = case profile
-                  when :core      then core_extension_names
-                  when :cognitive then core_extension_names + agentic_extension_names
-                  when :service   then core_extension_names + service_extension_names + other_extension_names
-                  when :dev       then core_extension_names + ai_extension_names + dev_agentic_names
-                  when :custom    then Array(role[:extensions]).map(&:to_s)
-                  else return
-                  end
+        allowed = allowed_gem_names_for_profile(profile, role)
+        return if allowed.nil?
 
         before = @extensions.count
-        @extensions.select! { |name, _| allowed.include?(name) }
+        @extensions.select! { |entry| allowed.include?(entry[:gem_name]) }
         Legion::Logging.info "Role profile :#{profile} filtered #{before} -> #{@extensions.count} extensions"
       end
 
@@ -260,61 +277,160 @@ module Legion
       end
 
       def agentic_extension_names
-        known = core_extension_names + service_extension_names + other_extension_names + ai_extension_names
-        @extensions.keys.reject { |name| known.include?(name) }
+        known_gem_names = (core_extension_names + service_extension_names + other_extension_names + ai_extension_names).map { |n| "lex-#{n}" }
+        Array(@extensions).reject { |entry| known_gem_names.include?(entry[:gem_name]) }.map { |entry| entry[:gem_name] }
       end
 
-      def find_extensions
-        @extensions ||= {}
-        gem_names_for_discovery.each do |spec|
-          next unless spec[:name].start_with?('lex-')
-
-          ext_name = spec[:name].delete_prefix('lex-').tr('-', '_')
-          @extensions[ext_name] = { full_gem_name:   "#{spec[:name]}-#{spec[:version]}",
-                                    gem_name:        spec[:name],
-                                    extension_name:  ext_name,
-                                    version:         spec[:version],
-                                    extension_class: "Legion::Extensions::#{ext_name.split('_').collect(&:capitalize).join}" }
+      def categorize_and_order(gem_names)
+        ext_settings = ::Legion::Settings[:extensions] || {}
+        categories   = ext_settings[:categories] || default_category_registry
+        lists        = {
+          core: Array(ext_settings[:core]),
+          ai:   Array(ext_settings[:ai]),
+          gaia: Array(ext_settings[:gaia])
+        }
+        ctx = {
+          blocked:     Array(ext_settings[:blocked]),
+          agentic_cfg: ext_settings[:agentic] || {},
+          categories:  categories,
+          gem_set:     gem_names.to_set,
+          ordered:     [],
+          claimed:     Set.new
+        }
+
+        collect_list_category_gems(lists, ctx)
+        collect_prefix_category_gems(gem_names, ctx)
+
+        (gem_names.to_a - ctx[:claimed].to_a - ctx[:blocked]).sort.each do |gn|
+          ctx[:ordered] << build_extension_entry(gn, :default, categories, nesting: false)
+        end
+
+        ctx[:ordered]
+      end
+
+      def check_reserved_words(gem_name, known_org: true)
+        return if known_org
+
+        bare          = gem_name.delete_prefix('lex-')
+        first_segment = bare.split('-').first
+
+        configured_prefixes = begin
+          Array(::Legion::Settings.dig(:extensions, :reserved_prefixes))
+        rescue StandardError
+          []
+        end
+        reserved_prefixes = configured_prefixes.empty? ? %w[core ai agentic gaia] : configured_prefixes
+
+        configured_words = begin
+          Array(::Legion::Settings.dig(:extensions, :reserved_words))
+        rescue StandardError
+          []
+        end
+        reserved_words = configured_words.empty? ? %w[transport cache crypt data settings json logging llm rbac legion] : configured_words
+
+        if reserved_prefixes.include?(first_segment)
+          ::Legion::Logging.warn(
+            "#{gem_name} uses reserved prefix '#{first_segment}' — " \
+            "it will be loaded in the #{first_segment} category namespace"
+          )
+        elsif reserved_words.include?(first_segment)
+          ::Legion::Logging.warn(
+            "#{gem_name} uses reserved word '#{first_segment}' as its first segment — " \
+            'this may shadow framework modules'
+          )
         end
+      end
+
+      def find_extensions
+        return @extensions if @extensions
 
+        all_specs  = gem_names_for_discovery
+        lex_names  = all_specs.select { |s| s[:name].start_with?('lex-') }.map { |s| s[:name] }
+        @extensions = categorize_and_order(lex_names)
         apply_role_filter
+        @extensions
+      end
+
+      private
+
+      def lex_prefix(names)
+        names.map { |n| n.start_with?('lex-') ? n : "lex-#{n}" }
+      end
 
-        enabled = 0
-        requested = 0
-
-        Legion::Settings[:extensions].each do |extension, values|
-          next if @extensions.key? extension.to_s
-          next if values[:enabled] == false
-
-          requested += 1
-          next if values[:auto_install] == false
-          next if ENV['_'].include? 'bundle'
-
-          Legion::Logging.warn "#{extension} is missing, attempting to install automatically.."
-          install = Gem.install("lex-#{extension}", values[:version])
-          Legion::Logging.debug(install)
-          lex = Gem::Specification.find_by_name("lex-#{extension}")
-
-          @extensions[extension.to_s] = {
-            full_gem_name:   "lex-#{extension}-#{lex.version}",
-            gem_name:        "lex-#{extension}",
-            extension_name:  extension.to_s,
-            version:         lex.version,
-            extension_class: "Legion::Extensions::#{extension.to_s.split('_').collect(&:capitalize).join}"
-          }
-
-          enabled += 1
-        rescue StandardError, Gem::MissingSpecError => e
-          Legion::Logging.error "Failed to auto install #{extension}, e: #{e.message}"
+      def allowed_gem_names_for_profile(profile, role)
+        case profile
+        when :core      then lex_prefix(core_extension_names)
+        when :cognitive then lex_prefix(core_extension_names + agentic_extension_names)
+        when :service   then lex_prefix(core_extension_names + service_extension_names + other_extension_names)
+        when :dev       then lex_prefix(core_extension_names + ai_extension_names + dev_agentic_names)
+        when :custom    then lex_prefix(Array(role[:extensions]).map(&:to_s))
         end
-        return true if requested == enabled
+      end
+
+      def collect_list_category_gems(lists, ctx)
+        lists.sort_by { |cat, _| ctx[:categories].dig(cat, :tier) || 99 }.each do |cat_name, gem_list|
+          gem_list.each do |gn|
+            next unless ctx[:gem_set].include?(gn)
+            next if ctx[:blocked].include?(gn)
 
-        Legion::Logging.warn "A total of #{requested - enabled} where skipped"
-        if ENV.key?('_') && ENV['_'].include?('bundle')
-          Legion::Logging.warn 'Please add them to your Gemfile since you are using bundler'
+            ctx[:ordered] << build_extension_entry(gn, cat_name, ctx[:categories], nesting: false)
+            ctx[:claimed].add(gn)
+          end
+        end
+      end
+
+      def collect_prefix_category_gems(gem_names, ctx)
+        prefix_cats = ctx[:categories].select { |_, v| v[:type].to_s == 'prefix' }
+                                      .sort_by { |_, v| v[:tier] || 99 }
+                                      .to_h
+        prefix_cats.each_key do |cat_name|
+          prefix  = "lex-#{cat_name}-"
+          matched = gem_names.select { |gn| gn.start_with?(prefix) && !ctx[:claimed].include?(gn) }.sort
+          matched.each do |gn|
+            next if ctx[:blocked].include?(gn)
+            next if cat_name == :agentic && agentic_blocked?(gn, ctx[:agentic_cfg])
+            next if cat_name == :agentic && !agentic_allowed?(gn, ctx[:agentic_cfg])
+
+            ctx[:ordered] << build_extension_entry(gn, cat_name, ctx[:categories], nesting: true)
+            ctx[:claimed].add(gn)
+          end
+        end
+      end
+
+      def build_extension_entry(gem_name, category, categories, nesting:)
+        segments = Helpers::Segments.derive_segments(gem_name)
+        tier     = category == :default ? 5 : (categories.dig(category, :tier) || 5)
+
+        if nesting
+          const_path   = Helpers::Segments.derive_const_path(gem_name)
+          require_path = Helpers::Segments.derive_require_path(gem_name)
         else
-          Legion::Logging.warn 'You must have auto_install_missing_lex set to true to auto install missing extensions'
+          flat_name    = gem_name.delete_prefix('lex-').tr('-', '_')
+          const_path   = "Legion::Extensions::#{flat_name.split('_').map(&:capitalize).join}"
+          require_path = "legion/extensions/#{flat_name}"
         end
+
+        { gem_name: gem_name, category: category, tier: tier,
+          segments: segments, const_path: const_path, require_path: require_path }
+      end
+
+      def default_category_registry
+        {
+          core:    { type: :list, tier: 1 },
+          ai:      { type: :list, tier: 2 },
+          gaia:    { type: :list, tier: 3 },
+          agentic: { type: :prefix, tier: 4 }
+        }
+      end
+
+      def agentic_blocked?(gem_name, config)
+        Array(config[:blocked]).any? { |pat| File.fnmatch(pat, gem_name) }
+      end
+
+      def agentic_allowed?(gem_name, config)
+        return true if config[:allowed].nil?
+
+        Array(config[:allowed]).any? { |pat| File.fnmatch(pat, gem_name) }
       end
     end
   end

data/lib/legion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Legion
-  VERSION = '1.4.53'
+  VERSION = '1.4.58'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legionio
 version: !ruby/object:Gem::Version
-  version: 1.4.53
+  version: 1.4.58
 platform: ruby
 authors:
 - Esity
@@ -514,6 +514,7 @@ files:
 - lib/legion/extensions/helpers/data.rb
 - lib/legion/extensions/helpers/lex.rb
 - lib/legion/extensions/helpers/logger.rb
+- lib/legion/extensions/helpers/segments.rb
 - lib/legion/extensions/helpers/task.rb
 - lib/legion/extensions/helpers/transport.rb
 - lib/legion/extensions/hooks/base.rb