mxup 0.2.0

data/lib/mxup/cli.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Mxup
+  # Argv parser + dispatch. Keeps parsing rules in one place; the actual
+  # behaviour lives in Runner and the focused modules it drives.
+  class CLI
+    COMMANDS = %w[up status down restart layout target exec].freeze
+
+    def run(argv)
+      args, options = parse(argv.dup)
+      command       = extract_command(args)
+      dispatch(command, args, options)
+    end
+
+    private
+
+    def parse(args)
+      options = {
+        dry_run: false, config: nil, lines: nil, layout: nil,
+        target: nil,    timeout: nil, force: false, quiet: false,
+        profile: nil
+      }
+
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: mxup [command] [name] [options]'
+        opts.on('-f', '--file FILE', 'Config file path')              { |f| options[:config]  = f }
+        opts.on('--dry-run', 'Preview changes without applying')      { options[:dry_run] = true }
+        opts.on('--lines N', Integer, 'Output lines (status/exec)')   { |n| options[:lines]   = n }
+        opts.on('--layout NAME', 'Layout to use (for up/layout)')     { |l| options[:layout]  = l }
+        opts.on('-p', '--profile NAME',
+                'Profile to use (for up/status/restart/layout)')      { |p| options[:profile] = p }
+        opts.on('-t', '--target TARGET',
+                'Target window/pane for exec (e.g. name:window)')     { |t| options[:target]  = t }
+        opts.on('--timeout N', Integer, 'Timeout in seconds (exec)')  { |n| options[:timeout] = n }
+        opts.on('--force', 'Force exec on a busy pane')               { options[:force] = true }
+        opts.on('-q', '--quiet', 'Suppress captured output (exec)')   { options[:quiet] = true }
+        opts.on('-v', '--version', 'Show version') { puts "mxup #{VERSION}"; exit }
+        opts.on('-h', '--help',    'Show help')    { puts opts; exit }
+      end
+
+      parser.parse!(args)
+      [args, options]
+    end
+
+    # Peek at the first non-file positional; if it's a recognised command,
+    # pop it. Otherwise default to "up".
+    def extract_command(args)
+      first = args.first
+      return 'up' if first.nil?
+      return 'up' if first.include?('.yml') || first.include?('/')
+
+      COMMANDS.include?(first) ? args.shift : 'up'
+    end
+
+    def dispatch(command, args, options)
+      case command
+      when 'up', 'status', 'down'       then run_basic(command, args, options)
+      when 'restart', 'target'          then run_restart_or_target(command, args, options)
+      when 'layout'                     then run_layout(args, options)
+      when 'exec'                       then run_exec(args, options)
+      else
+        abort "Unknown command: #{command}. Use: #{COMMANDS.join(', ')}"
+      end
+    end
+
+    def run_basic(command, args, options)
+      name   = args.shift
+      runner = build_runner(options, name)
+      case command
+      when 'up'     then runner.up
+      when 'status' then runner.status(lines: options[:lines] || 2)
+      when 'down'   then runner.down
+      end
+    end
+
+    def run_restart_or_target(command, args, options)
+      name, window_names = split_restart_spec(args, options)
+      runner = build_runner(options, name)
+
+      if command == 'restart'
+        runner.restart(window_names)
+      else
+        runner.target(window_names)
+      end
+    end
+
+    def run_layout(args, options)
+      name          = args.shift
+      target_layout = args.shift
+      runner        = build_runner(options, name)
+      target_layout ? runner.switch_layout(target_layout) : runner.show_layouts
+    end
+
+    def run_exec(args, options)
+      target = options[:target] || args.shift
+      abort 'Usage: mxup exec -t [name:]WINDOW "command"' if target.nil? || target.empty?
+
+      command_str = args.shift
+      abort 'Usage: mxup exec -t [name:]WINDOW "command"' if command_str.nil?
+
+      name = target.include?(':') ? target.split(':', 2).first : nil
+      build_runner(options, name).exec(
+        target, command_str,
+        lines: options[:lines] || 50,
+        timeout: options[:timeout],
+        force: options[:force],
+        quiet: options[:quiet]
+      )
+    end
+
+    # Parse the first positional of `restart` / `target`. Supports:
+    #   "session:win1,win2"   → explicit session + window list
+    #   "session"             → session name, no windows (if it resolves to a config)
+    #   "win1"                → bare window name (no session prefix)
+    def split_restart_spec(args, options)
+      spec = args.shift
+      if spec.nil?
+        return [nil, []]
+      elsif spec.include?(':')
+        name, windows_str = spec.split(':', 2)
+        return [name, windows_str ? windows_str.split(',') : []]
+      end
+
+      # Ambiguous: is `spec` a config name or a window name?
+      looks_like_config = File.exist?(File.join(CONFIG_DIR, "#{spec}.yml")) ||
+                          (options[:config] && spec !~ /,/)
+      return [spec, args] if looks_like_config
+      [nil, [spec] + args]
+    end
+
+    def build_runner(options, name)
+      config = load_config(options[:config], name, options[:profile])
+      Runner.new(config, dry_run: options[:dry_run], layout: options[:layout])
+    end
+
+    def load_config(explicit_path, name, profile = nil)
+      path = resolve_config(explicit_path, name)
+      abort "Config not found. Provide -f path or place config in #{CONFIG_DIR}/" unless path
+      Config.new(path, profile: profile)
+    rescue ArgumentError => e
+      abort e.message
+    end
+
+    # Config resolution order:
+    #   1. explicit -f path
+    #   2. ~/.config/mxup/<name>.yml
+    #   3. ./mxup.yml
+    #   4. sole *.yml in ~/.config/mxup/
+    def resolve_config(explicit, name)
+      return explicit if explicit && File.exist?(explicit)
+
+      if name
+        candidate = File.join(CONFIG_DIR, "#{name}.yml")
+        return candidate if File.exist?(candidate)
+      end
+
+      local = File.join(Dir.pwd, 'mxup.yml')
+      return local if File.exist?(local)
+
+      if Dir.exist?(CONFIG_DIR)
+        configs = Dir.glob(File.join(CONFIG_DIR, '*.yml'))
+        return configs.first if configs.size == 1
+      end
+
+      nil
+    end
+  end
+end

data/lib/mxup/config.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'set'
+
+module Mxup
+  # Parsed mxup YAML config. Pure data; no tmux or filesystem side effects.
+  #
+  # Profiles (optional): a config may declare a `profiles:` map where each
+  # entry is a partial override on top of the base `setup`, `windows`, and
+  # `layouts`. A single active profile is resolved at parse time and its
+  # overrides are merged in before the rest of the Config is built — so the
+  # rest of the system (Launcher, Reconciler, StatusView…) never has to know
+  # about profiles.
+  class Config
+    attr_reader :session, :setup, :windows, :layouts, :layout_names,
+                :profile, :profile_names, :default_profile
+
+    def initialize(path, profile: nil)
+      raw = YAML.safe_load(File.read(path), permitted_classes: [Symbol])
+      resolve_profile!(raw, profile)
+      @session = raw.fetch('session')
+      @setup   = raw['setup']&.strip
+      @windows = parse_windows(raw.fetch('windows'))
+      @layouts, @layout_names = parse_layouts(raw['layouts'])
+    end
+
+    def default_layout
+      @layout_names.first
+    end
+
+    def groups_for(layout_name)
+      return [] if layout_name.nil?
+      @layouts.fetch(layout_name)
+    end
+
+    # Returns an ordered list of entries describing how windows should appear
+    # in tmux under the given layout. Each entry is one of:
+    #   { type: :group,      name: <group name>, group: PaneGroup }
+    #   { type: :standalone, name: <window name> }
+    def effective_window_order(layout_name)
+      groups  = groups_for(layout_name)
+      grouped = groups.flat_map(&:window_names).to_set
+      entries = groups.map { |g| { type: :group, name: g.name, group: g } }
+      @windows.each do |w|
+        entries << { type: :standalone, name: w.name } unless grouped.include?(w.name)
+      end
+      entries
+    end
+
+    def window_by_name(name)
+      @windows.find { |w| w.name == name }
+    end
+
+    # Returns [group, index_within_group] or nil.
+    def find_group_for_window(layout_name, window_name)
+      groups_for(layout_name).each do |g|
+        idx = g.window_names.index(window_name)
+        return [g, idx] if idx
+      end
+      nil
+    end
+
+    private
+
+    # Pick the active profile (if any) and merge its overrides into `raw`.
+    # Sets @profile / @profile_names / @default_profile.
+    def resolve_profile!(raw, requested)
+      profiles = raw['profiles'] || {}
+      @profile_names    = profiles.keys
+      @default_profile  = raw['default_profile'] || @profile_names.first
+
+      if profiles.empty?
+        if requested
+          raise ArgumentError,
+                "--profile '#{requested}' was given, but this config declares no profiles"
+        end
+        @profile = nil
+        return
+      end
+
+      @profile = requested || @default_profile
+      unless profiles.key?(@profile)
+        raise ArgumentError,
+              "Unknown profile '#{@profile}' (available: #{@profile_names.join(', ')})"
+      end
+
+      apply_profile_overrides!(raw, profiles.fetch(@profile))
+    end
+
+    def apply_profile_overrides!(raw, override)
+      return unless override.is_a?(Hash)
+
+      if override.key?('session')
+        raise ArgumentError,
+              "Profile '#{@profile}' cannot override 'session'; profiles of the " \
+              'same group must share one tmux session name'
+      end
+
+      raw['setup']   = override['setup']   if override.key?('setup')
+      raw['layouts'] = override['layouts'] if override.key?('layouts')
+
+      removed = []
+      (override['windows'] || {}).each do |wname, woverride|
+        raw['windows'] ||= {}
+        if woverride.nil?
+          # Explicit null ("dev-kit: ~") drops this window for this profile.
+          # `parse_windows` skips absent keys; `prune_layouts!` keeps layouts
+          # from referencing the now-missing name.
+          raw['windows'].delete(wname)
+          removed << wname
+        else
+          base = raw['windows'][wname] || {}
+          raw['windows'][wname] = merge_window(base, woverride)
+        end
+      end
+
+      prune_layouts!(raw, removed) if removed.any?
+    end
+
+    # Strip any removed window names from layout groups so parse_layouts
+    # doesn't raise "window not found". A group whose panes list becomes
+    # empty is dropped from the layout entirely.
+    def prune_layouts!(raw, removed)
+      return unless raw['layouts'].is_a?(Hash)
+      removed_set = removed.to_set
+
+      raw['layouts'].each_value do |layout_def|
+        next unless layout_def.is_a?(Hash)
+        layout_def.reject! do |_group_name, group_def|
+          next false unless group_def.is_a?(Hash) && group_def['panes'].is_a?(Array)
+          group_def['panes'] -= removed_set.to_a
+          group_def['panes'].empty?
+        end
+      end
+    end
+
+    # Shallow merge with a special case: `env` is itself a hash that should
+    # be merged (so a profile can tweak one key without redeclaring the rest).
+    def merge_window(base, override)
+      base.merge(override) do |key, base_val, prof_val|
+        if key == 'env' && base_val.is_a?(Hash) && prof_val.is_a?(Hash)
+          base_val.merge(prof_val)
+        else
+          prof_val
+        end
+      end
+    end
+
+    def parse_windows(hash)
+      hash.map do |name, opts|
+        opts ||= {}
+        Window.new(
+          name:     name,
+          root:     File.expand_path(opts.fetch('root')),
+          command:  opts['command']&.strip,
+          env:      opts['env'] || {},
+          wait_for: WaitSpec.parse(opts['wait_for'])
+        )
+      end
+    end
+
+    def parse_layouts(raw)
+      return [{}, []] if raw.nil?
+
+      valid_windows = @windows.map(&:name).to_set
+      layouts = {}
+      order   = []
+
+      raw.each do |layout_name, groups_hash|
+        order << layout_name
+        groups_hash ||= {}
+        seen   = Set.new
+        groups = []
+
+        groups_hash.each do |group_name, group_opts|
+          group_opts ||= {}
+          pane_names = Array(group_opts['panes'])
+
+          pane_names.each do |pn|
+            unless valid_windows.include?(pn)
+              raise ArgumentError,
+                    "Layout '#{layout_name}': window '#{pn}' not found in windows"
+            end
+            if seen.include?(pn)
+              raise ArgumentError,
+                    "Layout '#{layout_name}': window '#{pn}' appears in multiple groups"
+            end
+            seen << pn
+          end
+
+          groups << PaneGroup.new(
+            name:         group_name,
+            window_names: pane_names,
+            split:        group_opts['split'] || 'tiled'
+          )
+        end
+
+        layouts[layout_name] = groups
+      end
+
+      [layouts, order]
+    end
+  end
+
+  Window    = Struct.new(:name, :root, :command, :env, :wait_for, keyword_init: true)
+  PaneGroup = Struct.new(:name, :window_names, :split,           keyword_init: true)
+
+  # A readiness check attached to a window.
+  WaitSpec = Struct.new(:type, :target, :timeout, :interval, :label, keyword_init: true) do
+    CHECK_TYPES = %w[tcp http path script].freeze
+
+    def self.parse(raw)
+      case raw
+      when nil
+        nil
+      when String
+        new(type: :tcp, target: raw, timeout: nil, interval: 2, label: raw)
+      when Hash
+        found = CHECK_TYPES & raw.keys
+        unless found.size == 1
+          raise ArgumentError,
+                "wait_for must specify exactly one of: #{CHECK_TYPES.join(', ')}"
+        end
+        type          = found.first
+        target        = raw[type]
+        default_label = type == 'script' ? 'readiness check' : target
+        new(
+          type:     type.to_sym,
+          target:   target,
+          timeout:  raw['timeout'],
+          interval: raw['interval'] || 2,
+          label:    raw['label'] || default_label
+        )
+      else
+        raise ArgumentError, "wait_for must be a string or hash, got #{raw.class}"
+      end
+    end
+  end
+end

data/lib/mxup/exec_runner.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'shellwords'
+require 'tmpdir'
+require 'timeout'
+
+module Mxup
+  # Implements `mxup exec`: send a command to a pane, block until it finishes,
+  # print its output, and exit with its return code. The three interesting
+  # parts are:
+  #
+  #   1. Resolving a logical window name to a real tmux pane target.
+  #   2. Using `tmux wait-for -S <marker>` so we know the command finished.
+  #   3. Capturing both the output (tmux capture-pane) and the exit code
+  #      (written to a temp file by the wrapped command).
+  class ExecRunner
+    def initialize(config, resolver:, dry_run: false,
+                   out: nil, err: nil, exiter: ->(n) { exit(n) })
+      @config       = config
+      @session      = config.session
+      @resolver     = resolver
+      @dry_run      = dry_run
+      @out_override = out
+      @err_override = err
+      @exit         = exiter
+    end
+
+    def out
+      @out_override || $stdout
+    end
+
+    def err
+      @err_override || $stderr
+    end
+
+    # target_spec may be:
+    #   "session:window"      — session must match config
+    #   "window"              — logical name from config, or a raw tmux window
+    #   "window.pane_index"   — raw tmux pane address
+    def run(target_spec, command, lines: 50, timeout: nil, force: false, quiet: false)
+      abort "Session #{@session} is not running." unless Tmux.has_session?(@session)
+      abort 'mxup exec: command is required.' if command.nil? || command.strip.empty?
+
+      window_part = strip_session_prefix(target_spec)
+      resolved    = resolve_target(window_part)
+      abort "Target '#{window_part}' not found in session '#{@session}'." unless resolved
+
+      full_target = "#{@session}:#{resolved}"
+      refuse_if_busy(resolved, full_target) unless force
+
+      if @dry_run
+        out.puts "[dry-run] Would exec on #{full_target}: #{command}"
+        return 0
+      end
+
+      send_and_wait(full_target, command, lines: lines, timeout: timeout, quiet: quiet)
+    end
+
+    private
+
+    def strip_session_prefix(spec)
+      return spec unless spec.include?(':')
+      sess, rest = spec.split(':', 2)
+      if sess != @session
+        abort "Target session '#{sess}' does not match config session '#{@session}'."
+      end
+      rest
+    end
+
+    def resolve_target(window_part)
+      # First try: logical config window (handles group membership).
+      if @config.windows.any? { |w| w.name == window_part }
+        resolved = @resolver.pane_target(window_part)
+        return resolved if resolved
+      end
+
+      # Explicit "window.pane_index" form — accept if the window exists.
+      if window_part =~ /\A(.+)\.\d+\z/
+        raw_win = Regexp.last_match(1)
+        return window_part if tmux_window_names.include?(raw_win)
+      end
+
+      # Fallback: raw tmux window name that isn't in the config.
+      tmux_window_names.include?(window_part) ? window_part : nil
+    end
+
+    def tmux_window_names
+      Tmux.list_windows(@session).map { |w| w[:name] }
+    end
+
+    def refuse_if_busy(resolved, full_target)
+      pane = @resolver.pane_for(resolved)
+      return unless pane && !SHELLS.include?(pane[:fg_cmd])
+
+      abort "Target pane #{full_target} is busy (#{pane[:fg_cmd]}). " \
+            'Pass --force to send anyway.'
+    end
+
+    def send_and_wait(full_target, command, lines:, timeout:, quiet:)
+      marker    = fresh_marker
+      exit_file = File.join(Dir.tmpdir, "#{marker}.rc")
+      FileUtils.rm_f(exit_file)
+
+      cmd_clean = command.strip.sub(/;+\s*\z/, '')
+      # Wrap in a subshell so `exit`, `set -e`, or a failing command can't
+      # terminate the pane's interactive shell (which would strand us waiting
+      # for the marker forever).
+      wrapped = "( #{cmd_clean} ); " \
+                '__mxup_rc=$?; ' \
+                "echo $__mxup_rc > #{Shellwords.escape(exit_file)}; " \
+                "tmux wait-for -S #{Shellwords.escape(marker)}"
+
+      unless system("tmux send-keys -t #{Tmux.esc(full_target)} #{Shellwords.escape(wrapped)} Enter")
+        abort "Failed to send command to #{full_target}."
+      end
+
+      timed_out = wait_for_marker(marker, timeout)
+
+      output = `tmux capture-pane -t #{Tmux.esc(full_target)} -p -S -#{lines.to_i}`
+      unless quiet
+        out.print output
+        out.puts unless output.end_with?("\n")
+      end
+
+      if timed_out
+        err.puts "[mxup] exec: timed out after #{timeout}s waiting for command on #{full_target}."
+        FileUtils.rm_f(exit_file)
+        @exit.call(124)
+        return
+      end
+
+      rc = read_exit_code(exit_file)
+      FileUtils.rm_f(exit_file)
+      @exit.call(rc || 0)
+    end
+
+    def wait_for_marker(marker, timeout)
+      if timeout.nil?
+        system("tmux wait-for #{Tmux.esc(marker)}")
+        return false
+      end
+
+      pid = Process.spawn("tmux wait-for #{Tmux.esc(marker)}")
+      begin
+        Timeout.timeout(timeout) { Process.waitpid(pid) }
+        false
+      rescue Timeout::Error
+        kill_waiter(pid)
+        # Release anyone else still blocked on the marker.
+        system("tmux wait-for -S #{Tmux.esc(marker)} 2>/dev/null")
+        true
+      end
+    end
+
+    def kill_waiter(pid)
+      Process.kill('TERM', pid)
+    rescue StandardError
+      # already gone
+    ensure
+      begin
+        Process.waitpid(pid)
+      rescue StandardError
+        # already reaped
+      end
+    end
+
+    def read_exit_code(path)
+      return nil unless File.exist?(path)
+      val = File.read(path).strip
+      val.empty? ? nil : val.to_i
+    end
+
+    def fresh_marker
+      "mxup-exec-#{Process.pid}-#{Time.now.to_i}-#{rand(10**9)}"
+    end
+  end
+end

data/lib/mxup/graceful_stop.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Mxup
+  # Sends SIGINT to every non-shell pane in a session, then waits for them to
+  # exit. Used by `mxup down` before the final kill-session.
+  class GracefulStop
+    # Interval (seconds) between SIGINT rounds. Overridable for tests that
+    # don't want to pay the 1s settle between retries.
+    DEFAULT_ROUND_INTERVAL = 1.0
+
+    class << self
+      attr_writer :round_interval
+
+      def round_interval
+        @round_interval || DEFAULT_ROUND_INTERVAL
+      end
+    end
+
+    def initialize(session, out: nil, err: nil)
+      @session      = session
+      @out_override = out
+      @err_override = err
+    end
+
+    def out
+      @out_override || $stdout
+    end
+
+    def err
+      @err_override || $stderr
+    end
+
+    def call(timeout: 30)
+      out.puts "Stopping session #{@session}..."
+      deadline = Time.now + timeout
+      round    = 0
+
+      loop do
+        break unless Tmux.has_session?(@session)
+
+        busy = busy_panes
+        break if busy.empty?
+
+        if round.positive?
+          remaining = (deadline - Time.now).ceil
+          plural    = busy.size == 1 ? 'process' : 'processes'
+          out.puts "  waiting... #{busy.size} #{plural} still running (#{remaining}s left)"
+        end
+
+        busy.each do |pane|
+          target = Tmux.pane_target(pane[:name], pane[:pane_index])
+          Tmux.send_interrupt(@session, target)
+        end
+
+        if Time.now >= deadline
+          names = busy.map { |p| p[:title].to_s.empty? ? p[:name] : p[:title] }.uniq
+          err.puts "  timeout: #{names.join(', ')} did not exit in #{timeout}s — killing anyway"
+          break
+        end
+
+        round += 1
+        sleep GracefulStop.round_interval
+      end
+    end
+
+    private
+
+    def busy_panes
+      Tmux.list_panes(@session).reject { |p| SHELLS.include?(p[:fg_cmd]) }
+    end
+  end
+end