ace-tmux 0.11.0

data/lib/ace/tmux/models/window.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Ace
+  module Tmux
+    module Models
+      # Represents a tmux window configuration
+      class Window
+        attr_reader :name, :layout, :root, :panes, :pre_window, :focus, :options, :layout_tree
+
+        # @param name [String, nil] Window name
+        # @param layout [String, nil] tmux layout (e.g., "main-vertical", "tiled")
+        # @param root [String, nil] Working directory for the window
+        # @param panes [Array<Pane>] Pane configurations
+        # @param pre_window [String, nil] Command to run before each pane
+        # @param focus [Boolean] Whether this window should be focused
+        # @param options [Hash] Raw tmux window options (passed to set-window-option)
+        # @param layout_tree [Models::LayoutNode, nil] Nested layout tree (nil for flat layouts)
+        def initialize(name: nil, layout: nil, root: nil, panes: [], pre_window: nil, focus: false, options: {}, layout_tree: nil)
+          @name = name
+          @layout = layout
+          @root = root
+          @panes = panes
+          @pre_window = pre_window
+          @focus = focus
+          @options = options || {}
+          @layout_tree = layout_tree
+        end
+
+        # @return [Boolean] true if this window uses a nested layout tree
+        def nested_layout?
+          !@layout_tree.nil?
+        end
+
+        def focus?
+          @focus == true
+        end
+
+        def to_h
+          hash = {"name" => @name, "panes" => @panes.map(&:to_h)}
+          hash["layout"] = @layout if @layout
+          hash["root"] = @root if @root
+          hash["pre_window"] = @pre_window if @pre_window
+          hash["focus"] = @focus if @focus
+          hash["options"] = @options unless @options.empty?
+          hash
+        end
+      end
+    end
+  end
+end

data/lib/ace/tmux/molecules/config_loader.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "ace/support/config"
+
+module Ace
+  module Tmux
+    module Molecules
+      # Loads general tmux configuration via the ACE config cascade
+      module ConfigLoader
+        module_function
+
+        # Load tmux config from cascade
+        #
+        # @param gem_root [String] Gem root directory
+        # @return [Hash] Merged configuration hash
+        def load(gem_root:)
+          resolver = Ace::Support::Config.create(
+            config_dir: ".ace",
+            defaults_dir: ".ace-defaults",
+            gem_path: gem_root
+          )
+
+          config = resolver.resolve_namespace("tmux")
+          config.data
+        rescue => e
+          warn "ace-tmux: Could not load config: #{e.class} - #{e.message}" if Tmux.debug?
+          load_fallback(gem_root)
+        end
+
+        # Load gem defaults directly as fallback
+        #
+        # @param gem_root [String] Gem root directory
+        # @return [Hash] Defaults hash or empty hash
+        def load_fallback(gem_root)
+          defaults_path = File.join(gem_root, ".ace-defaults", "tmux", "config.yml")
+          return {} unless File.exist?(defaults_path)
+
+          require "yaml"
+          YAML.safe_load_file(defaults_path, permitted_classes: [Date], aliases: true) || {}
+        rescue
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/ace/tmux/molecules/preset_loader.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "ace/support/config"
+
+module Ace
+  module Tmux
+    module Molecules
+      # Finds and loads YAML presets across the ACE config cascade
+      #
+      # Uses VirtualConfigResolver to discover presets from:
+      #   1. Project .ace/tmux/ (highest priority)
+      #   2. User ~/.ace/tmux/
+      #   3. Gem .ace-defaults/tmux/ (lowest priority)
+      class PresetLoader
+        PRESET_TYPES = %w[sessions windows panes].freeze
+
+        # @param gem_root [String] Gem root directory for defaults
+        # @param start_path [String, nil] Starting path for cascade traversal
+        def initialize(gem_root:, start_path: nil)
+          @resolver = Ace::Support::Config.virtual_resolver(
+            config_dir: ".ace",
+            defaults_dir: ".ace-defaults",
+            start_path: start_path,
+            gem_path: gem_root
+          )
+        end
+
+        # Load a preset by type and name
+        #
+        # @param type [String] Preset type: "sessions", "windows", or "panes"
+        # @param name [String] Preset name (without .yml extension)
+        # @return [Hash, nil] Parsed YAML hash, or nil if not found
+        def load(type, name)
+          relative_path = "tmux/#{type}/#{name}.yml"
+          absolute_path = @resolver.resolve_path(relative_path)
+          return nil unless absolute_path && File.exist?(absolute_path)
+
+          YAML.safe_load_file(absolute_path, permitted_classes: [Date], aliases: true) || {}
+        end
+
+        # List available presets for a type
+        #
+        # @param type [String] Preset type: "sessions", "windows", or "panes"
+        # @return [Array<String>] Preset names (without .yml extension)
+        def list(type)
+          pattern = "tmux/#{type}/*.yml"
+          @resolver.glob(pattern).keys.map do |relative_path|
+            File.basename(relative_path, ".yml")
+          end.sort.uniq
+        end
+
+        # List all preset types and their presets
+        #
+        # @return [Hash<String, Array<String>>] Map of type => preset names
+        def list_all
+          PRESET_TYPES.each_with_object({}) do |type, result|
+            presets = list(type)
+            result[type] = presets unless presets.empty?
+          end
+        end
+
+        # Create a lookup proc for PresetResolver
+        #
+        # @param type [String] Preset type to look up
+        # @return [Proc] Proc that takes a name and returns a preset hash
+        def to_lookup(type)
+          ->(name) { load(type, name) }
+        end
+      end
+    end
+  end
+end

data/lib/ace/tmux/molecules/session_builder.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Ace
+  module Tmux
+    module Molecules
+      # Combines PresetLoader + PresetResolver to build fully resolved models
+      #
+      # Loads a session preset, resolves all nested window/pane presets,
+      # and constructs the model hierarchy (Session → Window → Pane).
+      class SessionBuilder
+        # @param preset_loader [PresetLoader] Loader for finding presets
+        def initialize(preset_loader:)
+          @preset_loader = preset_loader
+        end
+
+        # Build a fully resolved Session model from a preset name
+        #
+        # @param preset_name [String] Session preset name
+        # @return [Models::Session] Fully resolved session model
+        # @raise [PresetNotFoundError] If session preset doesn't exist
+        def build(preset_name)
+          raw = @preset_loader.load("sessions", preset_name)
+          raise PresetNotFoundError, "Session preset not found: #{preset_name}" unless raw
+
+          # Resolve all preset references
+          resolved = Atoms::PresetResolver.resolve_session(
+            raw,
+            window_lookup: @preset_loader.to_lookup("windows"),
+            pane_lookup: @preset_loader.to_lookup("panes")
+          )
+
+          build_session_model(resolved)
+        end
+
+        # Build a fully resolved Window model from a preset name
+        #
+        # @param preset_name [String] Window preset name
+        # @return [Models::Window] Fully resolved window model
+        # @raise [PresetNotFoundError] If window preset doesn't exist
+        def build_window(preset_name)
+          raw = @preset_loader.load("windows", preset_name)
+          raise PresetNotFoundError, "Window preset not found: #{preset_name}" unless raw
+
+          resolved = Atoms::PresetResolver.resolve_window(
+            raw,
+            pane_lookup: @preset_loader.to_lookup("panes")
+          )
+
+          build_window_model(resolved)
+        end
+
+        private
+
+        def build_session_model(hash)
+          windows = (hash["windows"] || []).map { |w| build_window_model(w) }
+
+          Models::Session.new(
+            name: hash["name"],
+            root: hash["root"],
+            windows: windows,
+            pre_window: hash["pre_window"],
+            startup_window: hash["startup_window"],
+            on_project_start: hash["on_project_start"],
+            on_project_exit: hash["on_project_exit"],
+            attach: hash.fetch("attach", true),
+            tmux_options: hash["tmux_options"]
+          )
+        end
+
+        def build_window_model(hash)
+          if nested_layout?(hash)
+            build_nested_window_model(hash)
+          else
+            build_flat_window_model(hash)
+          end
+        end
+
+        def build_flat_window_model(hash)
+          panes = (hash["panes"] || []).map { |p| build_pane_model(p) }
+
+          Models::Window.new(
+            name: hash["name"],
+            layout: hash["layout"],
+            root: hash["root"],
+            panes: panes,
+            pre_window: hash["pre_window"],
+            focus: hash["focus"] || false,
+            options: hash["options"] || {}
+          )
+        end
+
+        def build_nested_window_model(hash)
+          direction = parse_direction(hash["direction"] || "horizontal")
+          tree = build_layout_tree(hash, direction: direction)
+          panes = tree.leaves.map(&:pane)
+
+          Models::Window.new(
+            name: hash["name"],
+            root: hash["root"],
+            panes: panes,
+            pre_window: hash["pre_window"],
+            focus: hash["focus"] || false,
+            options: hash["options"] || {},
+            layout_tree: tree
+          )
+        end
+
+        def build_layout_tree(hash, direction:)
+          children = (hash["panes"] || []).map do |entry|
+            if entry.is_a?(Hash) && entry.key?("direction")
+              child_dir = parse_direction(entry["direction"])
+              child_tree = build_layout_tree(entry, direction: child_dir)
+              child_tree
+            else
+              pane = build_pane_model(entry)
+              Models::LayoutNode.new(pane: pane, size: entry.is_a?(Hash) ? entry["size"] : nil)
+            end
+          end
+
+          size = hash.is_a?(Hash) ? hash["size"] : nil
+          Models::LayoutNode.new(direction: direction, children: children, size: size)
+        end
+
+        def nested_layout?(hash)
+          return true if hash.is_a?(Hash) && hash.key?("direction")
+
+          panes = hash["panes"]
+          return false unless panes.is_a?(Array)
+
+          panes.any? { |p| p.is_a?(Hash) && p.key?("direction") }
+        end
+
+        def parse_direction(str)
+          (str.to_s == "vertical") ? :vertical : :horizontal
+        end
+
+        def build_pane_model(hash)
+          hash = Atoms::PresetResolver.normalize_pane(hash)
+
+          Models::Pane.new(
+            commands: hash["commands"] || [],
+            focus: hash["focus"] || false,
+            root: hash["root"],
+            name: hash["name"],
+            options: hash["options"] || {}
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ace/tmux/molecules/tmux_executor.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Ace
+  module Tmux
+    module Molecules
+      # Executes tmux commands via different execution strategies
+      #
+      # Provides three modes:
+      #   - capture: Run and capture stdout/stderr (for queries)
+      #   - run: Run via system() (for mutations)
+      #   - exec: Replace process via Kernel.exec (for attach)
+      class TmuxExecutor
+        # Run a command and capture output
+        #
+        # @param cmd [Array<String>] Command array
+        # @return [ExecutionResult] Result with stdout, stderr, success?
+        def capture(cmd)
+          stdout, stderr, status = Open3.capture3(*cmd)
+          ExecutionResult.new(
+            stdout: stdout.strip,
+            stderr: stderr.strip,
+            success: status.success?,
+            exit_code: status.exitstatus
+          )
+        end
+
+        # Run a command via system (fire and forget with status)
+        #
+        # @param cmd [Array<String>] Command array
+        # @return [Boolean] true if command succeeded
+        def run(cmd)
+          system(*cmd)
+        end
+
+        # Replace current process with command (for tmux attach)
+        #
+        # @param cmd [Array<String>] Command array
+        # @return [void] Never returns (replaces process)
+        def exec(cmd)
+          Kernel.exec(*cmd)
+        end
+
+        # Check if tmux is available
+        #
+        # @param tmux [String] tmux binary path
+        # @return [Boolean]
+        def tmux_available?(tmux: "tmux")
+          result = capture([tmux, "-V"])
+          result.success?
+        rescue Errno::ENOENT
+          false
+        end
+      end
+
+      # Immutable result of a tmux command execution
+      class ExecutionResult
+        attr_reader :stdout, :stderr, :exit_code
+
+        def initialize(stdout:, stderr:, success:, exit_code:)
+          @stdout = stdout
+          @stderr = stderr
+          @success = success
+          @exit_code = exit_code
+        end
+
+        def success?
+          @success
+        end
+      end
+    end
+  end
+end

data/lib/ace/tmux/organisms/session_manager.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+module Ace
+  module Tmux
+    module Organisms
+      # Orchestrates session creation from a preset
+      #
+      # Flow:
+      #   1. Check if session already exists
+      #   2. Run on_project_start hooks
+      #   3. Create session (first window implicitly created)
+      #   4. Set up additional windows and panes
+      #   5. Set layouts and focus
+      #   6. Select startup window
+      #   7. Attach (unless --detach)
+      class SessionManager
+        POLLUTING_ENV_VARS = %w[BUNDLE_GEMFILE BUNDLE_BIN_PATH RUBYOPT RUBYLIB].freeze
+
+        # @param executor [Molecules::TmuxExecutor] Command executor
+        # @param session_builder [Molecules::SessionBuilder] Preset resolver/builder
+        # @param tmux [String] tmux binary path
+        def initialize(executor:, session_builder:, tmux: "tmux")
+          @executor = executor
+          @session_builder = session_builder
+          @tmux = tmux
+        end
+
+        # Start a session from a preset
+        #
+        # @param preset_name [String] Session preset name
+        # @param detach [Boolean] Skip attach after creation
+        # @param force [Boolean] Kill existing session and recreate
+        # @param root [String, nil] Override working directory for the session
+        # @return [void]
+        def start(preset_name, detach: false, force: false, root: nil)
+          session = @session_builder.build(preset_name)
+          session.root = root if root
+
+          if session_exists?(session.name)
+            if force
+              kill_session(session.name)
+            else
+              attach_session(session) unless detach
+              return
+            end
+          end
+
+          run_hooks(session.on_project_start)
+          first_window_target = create_session(session, root_override: root)
+          clean_environment(session)
+          setup_windows(session)
+          select_startup_window(session, first_window_target: first_window_target)
+          attach_session(session) unless detach
+        end
+
+        private
+
+        # Derive the first window name from the effective working directory.
+        # Mirrors WindowManager#resolve_window_name: root basename wins over preset name.
+        def resolve_first_window_name(preset_window_name, root_override, session_root)
+          effective_root = root_override || session_root || Dir.pwd
+          File.basename(effective_root)
+        end
+
+        def session_exists?(name)
+          cmd = Atoms::TmuxCommandBuilder.has_session(name, tmux: @tmux)
+          result = @executor.capture(cmd)
+          result.success?
+        end
+
+        def kill_session(name)
+          cmd = Atoms::TmuxCommandBuilder.kill_session(name, tmux: @tmux)
+          @executor.run(cmd)
+        end
+
+        def create_session(session, root_override: nil)
+          first_window = session.windows.first
+          first_window_name = resolve_first_window_name(first_window&.name, root_override, session.root)
+          cmd = Atoms::TmuxCommandBuilder.new_session(
+            session.name,
+            root: session.root,
+            window_name: first_window_name,
+            tmux_options: session.tmux_options,
+            print_format: '#{window_id}',
+            tmux: @tmux
+          )
+          result = @executor.capture(cmd)
+          window_target = result.stdout.strip
+
+          # Set up panes for the first window (it was created with the session)
+          setup_panes(session, first_window, window_target) if first_window
+          window_target
+        end
+
+        def setup_windows(session)
+          # Skip first window (already created with session)
+          session.windows.drop(1).each do |window|
+            window_root = window.root || session.root
+            cmd = Atoms::TmuxCommandBuilder.new_window(
+              session.name,
+              name: window.name,
+              root: window_root,
+              print_format: '#{window_id}',
+              tmux: @tmux
+            )
+            result = @executor.capture(cmd)
+            window_target = result.stdout.strip
+            setup_panes(session, window, window_target)
+          end
+        end
+
+        def setup_panes(session, window, window_target)
+          return unless window.panes.any?
+
+          if window.nested_layout?
+            setup_nested_panes(session, window, window_target)
+          else
+            setup_flat_panes(session, window, window_target)
+          end
+        end
+
+        def setup_flat_panes(session, window, window_target)
+          # Create additional panes via split (first pane already exists)
+          window.panes.drop(1).each do |pane|
+            pane_root = pane.root || window.root || session.root
+            cmd = Atoms::TmuxCommandBuilder.split_window(
+              window_target,
+              root: pane_root,
+              tmux: @tmux
+            )
+            @executor.run(cmd)
+          end
+
+          # Apply window options before layout (e.g., main-pane-width)
+          apply_window_options(window, window_target)
+
+          # Apply layout after all panes are created
+          if window.layout
+            cmd = Atoms::TmuxCommandBuilder.select_layout(window_target, window.layout, tmux: @tmux)
+            @executor.run(cmd)
+          end
+
+          # Send commands to all panes (after layout is stable)
+          window.panes.each_with_index do |pane, idx|
+            send_pane_commands(session, window, pane, "#{window_target}.#{idx}")
+          end
+
+          # Focus the appropriate pane
+          focus_pane = window.panes.index(&:focus?)
+          if focus_pane
+            cmd = Atoms::TmuxCommandBuilder.select_pane("#{window_target}.#{focus_pane}", tmux: @tmux)
+            @executor.run(cmd)
+          end
+        end
+
+        def setup_nested_panes(session, window, window_target)
+          tree = window.layout_tree
+          leaves = tree.leaves
+          leaves.length
+
+          # Create leaf_count - 1 additional panes via flat splits
+          # Use per-leaf root when available, falling back to window/session root
+          leaves.drop(1).each do |leaf|
+            pane_root = leaf.pane.root || window.root || session.root
+            cmd = Atoms::TmuxCommandBuilder.split_window(
+              window_target,
+              root: pane_root,
+              tmux: @tmux
+            )
+            @executor.run(cmd)
+          end
+
+          # Get pane IDs
+          pane_ids = query_pane_ids(window_target)
+
+          # Get window dimensions
+          width, height = query_window_dimensions(window_target, pane_ids.first || 0)
+
+          # Build and apply custom layout string
+          layout_string = Atoms::LayoutStringBuilder.build(
+            tree, width: width, height: height, pane_ids: pane_ids
+          )
+          cmd = Atoms::TmuxCommandBuilder.select_layout(window_target, layout_string, tmux: @tmux)
+          @executor.run(cmd)
+
+          # Apply window options
+          apply_window_options(window, window_target)
+
+          # Send commands to each leaf pane
+          # First leaf was created with window/session root; cd if it has its own root
+          first_leaf = leaves.first
+          leaves.each do |leaf|
+            pane_target = "#{window_target}.#{leaf.pane_id}"
+            if leaf == first_leaf && leaf.pane.root
+              cd_cmd = Atoms::TmuxCommandBuilder.send_keys(pane_target, "cd #{leaf.pane.root}", tmux: @tmux)
+              @executor.run(cd_cmd)
+            end
+            send_pane_commands(session, window, leaf.pane, pane_target)
+          end
+
+          # Focus the appropriate leaf pane
+          focus_leaf = leaves.find { |l| l.pane.focus? }
+          if focus_leaf
+            cmd = Atoms::TmuxCommandBuilder.select_pane("#{window_target}.#{focus_leaf.pane_id}", tmux: @tmux)
+            @executor.run(cmd)
+          end
+        end
+
+        def query_pane_ids(window_target)
+          cmd = Atoms::TmuxCommandBuilder.list_panes(window_target, format: '#{pane_index}', tmux: @tmux)
+          result = @executor.capture(cmd)
+          return [] unless result.success?
+
+          result.stdout.split("\n").map(&:to_i)
+        end
+
+        def query_window_dimensions(window_target, pane_id)
+          cmd = Atoms::TmuxCommandBuilder.display_message_target(
+            "#{window_target}.#{pane_id}",
+            '#{window_width}x#{window_height}',
+            tmux: @tmux
+          )
+          result = @executor.capture(cmd)
+          return [200, 50] unless result.success?
+
+          parts = result.stdout.strip.split("x")
+          [parts[0].to_i, parts[1].to_i]
+        end
+
+        def send_pane_commands(session, window, pane, pane_target)
+          # Send pre_window command if set (session-level, then window-level)
+          pre_window = window.pre_window || session.pre_window
+          if pre_window
+            cmd = Atoms::TmuxCommandBuilder.send_keys(pane_target, pre_window, tmux: @tmux)
+            @executor.run(cmd)
+          end
+
+          # Apply pane options
+          apply_pane_options(pane, pane_target)
+
+          # Send pane commands
+          pane.commands.each do |command|
+            cmd = Atoms::TmuxCommandBuilder.send_keys(pane_target, command, tmux: @tmux)
+            @executor.run(cmd)
+          end
+        end
+
+        def apply_window_options(window, target)
+          window.options.each do |option, value|
+            cmd = Atoms::TmuxCommandBuilder.set_window_option(target, option, value, tmux: @tmux)
+            @executor.run(cmd)
+          end
+        end
+
+        def apply_pane_options(pane, target)
+          pane.options.each do |option, value|
+            cmd = Atoms::TmuxCommandBuilder.set_pane_option(target, option, value, tmux: @tmux)
+            @executor.run(cmd)
+          end
+        end
+
+        def select_startup_window(session, first_window_target: nil)
+          target = if session.startup_window
+            "#{session.name}:#{session.startup_window}"
+          else
+            first_window_target || "#{session.name}:#{session.windows.first&.name || 0}"
+          end
+
+          cmd = Atoms::TmuxCommandBuilder.select_window(target, tmux: @tmux)
+          @executor.run(cmd)
+        end
+
+        def attach_session(session)
+          cmd = Atoms::TmuxCommandBuilder.attach_session(session.name, tmux: @tmux)
+          @executor.exec(cmd)
+        end
+
+        def clean_environment(session)
+          POLLUTING_ENV_VARS.each do |var|
+            cmd = Atoms::TmuxCommandBuilder.set_environment(session.name, var, unset: true, tmux: @tmux)
+            @executor.run(cmd)
+          end
+        end
+
+        def run_hooks(commands)
+          return if commands.nil? || commands.empty?
+
+          commands.each do |command|
+            system(command)
+          end
+        end
+      end
+    end
+  end
+end