mxup 0.2.0

data/lib/mxup/runner.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module Mxup
+  # Public programmatic API. Composes the focused helpers — nothing here
+  # should contain real business logic, only wiring and delegation.
+  class Runner
+    # Delay (seconds) between the two Ctrl-C presses during a restart, and
+    # between Ctrl-C and sending the new command. In production 1s is enough
+    # to let the pane's shell redraw its prompt; tests shorten this to avoid
+    # paying multi-second waits for a purely cosmetic settle.
+    DEFAULT_INTERRUPT_DELAY = 1.0
+
+    class << self
+      attr_writer :interrupt_delay
+
+      def interrupt_delay
+        @interrupt_delay || DEFAULT_INTERRUPT_DELAY
+      end
+    end
+
+    def initialize(config, dry_run: false, layout: nil)
+      @config  = config
+      @session = config.session
+      @dry_run = dry_run
+      @layout  = layout
+    end
+
+    # --- primary commands --------------------------------------------------
+
+    def up
+      handle_profile_switch
+      reconciler.up
+    end
+
+    def status(lines:)
+      status_view.render(lines: lines)
+    end
+
+    def down
+      unless Tmux.has_session?(@session)
+        $stdout.puts "Session #{@session} is not running."
+        return
+      end
+
+      if @dry_run
+        $stdout.puts "[dry-run] Would gracefully stop session #{@session}"
+        return
+      end
+
+      graceful_stop.call
+      Tmux.kill_session(@session)
+      launcher.cleanup
+      $stdout.puts "Session #{@session} killed."
+    end
+
+    def restart(window_names)
+      abort "Session #{@session} is not running." unless Tmux.has_session?(@session)
+      launcher.write_all unless @dry_run
+
+      targets = resolve_restart_targets(window_names)
+
+      targets.each do |win|
+        target_ref = resolver.pane_target(win.name)
+        if target_ref
+          restart_existing(win, target_ref)
+        else
+          create_missing(win)
+        end
+      end
+    end
+
+    def switch_layout(target_layout)
+      layout_manager.switch(target_layout)
+    end
+
+    def show_layouts
+      layout_manager.show(
+        active: Tmux.has_session?(@session) ? resolver.stored_layout : nil
+      )
+    end
+
+    def target(window_names)
+      abort "Session #{@session} is not running." unless Tmux.has_session?(@session)
+
+      requested = Array(window_names).flat_map { |n| n.split(',') }.reject(&:empty?)
+
+      if requested.empty?
+        print_all_targets
+      else
+        print_requested_targets(requested)
+      end
+    end
+
+    def exec(target_spec, command, lines: 50, timeout: nil, force: false, quiet: false)
+      exec_runner.run(target_spec, command,
+                      lines: lines, timeout: timeout,
+                      force: force, quiet: quiet)
+    end
+
+    private
+
+    # --- profile switching -------------------------------------------------
+
+    # Before `up` runs, make sure we aren't stepping on a different profile
+    # of the same group. If the live session was brought up under a different
+    # profile, tear it down first so the new profile starts from a clean
+    # slate. Running profiles are expected to be mutually exclusive.
+    def handle_profile_switch
+      return unless @config.profile
+      return unless Tmux.has_session?(@session)
+
+      stored = Tmux.show_environment(@session, 'MXUP_PROFILE')
+      return if stored.nil? || stored == @config.profile
+
+      if @dry_run
+        $stdout.puts "[dry-run] Would tear down profile '#{stored}' before " \
+                     "bringing up '#{@config.profile}'"
+        return
+      end
+
+      $stdout.puts "Switching profile: '#{stored}' -> '#{@config.profile}' " \
+                   '(tearing down current profile first)...'
+      down
+    end
+
+    # --- restart helpers ---------------------------------------------------
+
+    def resolve_restart_targets(names)
+      return @config.windows if names.nil? || names.empty?
+
+      names.flat_map { |n| n.split(',') }.map do |n|
+        @config.windows.find { |w| w.name == n } ||
+          abort("Window '#{n}' not found in config.")
+      end
+    end
+
+    def restart_existing(win, target_ref)
+      if @dry_run
+        $stdout.puts "[dry-run] Would restart #{win.name}"
+        return
+      end
+      # Two C-c's handle both "foreground is command" and "foreground is a
+      # sub-prompt waiting on input"; the sleep gives the shell time to redraw.
+      delay = Runner.interrupt_delay
+      Tmux.send_interrupt(@session, target_ref)
+      sleep delay
+      Tmux.send_interrupt(@session, target_ref)
+      sleep delay
+      Tmux.send_keys(@session, target_ref, launcher.command_for(win))
+      $stdout.puts "  #{win.name}: restarted"
+    end
+
+    def create_missing(win)
+      if @dry_run
+        $stdout.puts "[dry-run] Would create #{win.name}"
+      else
+        Tmux.new_window(@session, win.name, win.root)
+        Tmux.set_pane_title(@session, win.name, 0, win.name)
+        Tmux.send_keys(@session, win.name, launcher.command_for(win))
+        $stdout.puts "  #{win.name}: created"
+      end
+    end
+
+    # --- target helpers ----------------------------------------------------
+
+    def print_all_targets
+      @config.windows.each do |win|
+        t = resolver.pane_target(win.name)
+        $stdout.puts(t ? "#{win.name}\t#{@session}:#{t}" : "#{win.name}\t(not running)")
+      end
+    end
+
+    def print_requested_targets(requested)
+      requested.each do |wn|
+        @config.windows.find { |w| w.name == wn } ||
+          abort("Window '#{wn}' not found in config.")
+
+        t = resolver.pane_target(wn)
+        abort("Window '#{wn}' is not currently in the session.") unless t
+
+        if requested.size == 1
+          $stdout.puts "#{@session}:#{t}"
+        else
+          $stdout.puts "#{wn}\t#{@session}:#{t}"
+        end
+      end
+    end
+
+    # --- lazily-built collaborators ---------------------------------------
+
+    def resolver
+      @resolver ||= PaneResolver.new(@config, session: @session, layout_override: @layout)
+    end
+
+    def launcher
+      @launcher ||= Launcher.new(@config)
+    end
+
+    def layout_manager
+      @layout_manager ||= LayoutManager.new(
+        @config, session: @session, dry_run: @dry_run, resolver: resolver
+      )
+    end
+
+    def reconciler
+      @reconciler ||= Reconciler.new(
+        @config,
+        launcher: launcher, resolver: resolver,
+        layout_manager: layout_manager, dry_run: @dry_run
+      )
+    end
+
+    def status_view
+      @status_view ||= StatusView.new(@config, resolver: resolver)
+    end
+
+    def exec_runner
+      @exec_runner ||= ExecRunner.new(@config, resolver: resolver, dry_run: @dry_run)
+    end
+
+    def graceful_stop
+      @graceful_stop ||= GracefulStop.new(@session)
+    end
+
+    # --- backward-compat shims (referenced by the unit tests) -------------
+
+    # These delegate to the launcher / layout manager so tests that poke at
+    # Runner's internals via .send(:...) keep working unchanged.
+    def assemble_command(win)
+      launcher.command_for(win)
+    end
+
+    def write_launcher_scripts
+      launcher.write_all
+    end
+
+    def launcher_script_path(name)
+      launcher.script_path(name)
+    end
+
+    def session_runtime_dir
+      launcher.session_runtime_dir
+    end
+
+    def cleanup_runtime_dir
+      launcher.cleanup
+    end
+
+    def generate_wait_block(_name, spec)
+      launcher.build_wait_block(spec)
+    end
+  end
+end

data/lib/mxup/status_view.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Mxup
+  # Renders `mxup status` output.
+  class StatusView
+    INDENT = '    '
+
+    def initialize(config, resolver:, out: nil)
+      @config       = config
+      @session      = config.session
+      @resolver     = resolver
+      @out_override = out
+    end
+
+    def out
+      @out_override || $stdout
+    end
+
+    def render(lines:)
+      unless Tmux.has_session?(@session)
+        out.puts "SESSION: #{@session} — NOT RUNNING"
+        out.puts "Start with: mxup up #{@session}"
+        return
+      end
+
+      active       = @resolver.active_layout
+      created      = Tmux.session_created(@session)
+      created_at   = Time.at(created.to_i).strftime('%Y-%m-%d %H:%M:%S')
+      stored_prof  = Tmux.show_environment(@session, 'MXUP_PROFILE')
+      bits         = []
+      bits << "profile: #{stored_prof}"       if stored_prof
+      bits << "layout: #{active}"             if active
+      suffix       = bits.empty? ? '' : " (#{bits.join(', ')})"
+      out.puts "SESSION: #{@session} — up since #{created_at}#{suffix}"
+      out.puts
+
+      panes           = Tmux.list_panes(@session)
+      declared_names  = @config.windows.map(&:name)
+      printed         = Set.new
+      order           = @config.effective_window_order(active)
+
+      order.each do |entry|
+        if entry[:type] == :group
+          render_group(entry[:group], panes, lines, printed)
+        else
+          render_standalone(entry[:name], panes, lines, declared_names, printed)
+        end
+      end
+
+      render_extras(panes, lines, printed)
+    end
+
+    private
+
+    def render_group(group, panes, lines, printed)
+      group_panes = panes.select { |p| p[:name] == group.name }
+                         .sort_by { |p| p[:pane_index] }
+
+      if group_panes.empty?
+        group.window_names.each do |wn|
+          out.puts "[?] #{wn}  MISSING (group: #{group.name})"
+          out.puts
+        end
+        return
+      end
+
+      header_idx = group_panes.first[:window_index]
+      out.puts "[#{header_idx}] #{group.name} " \
+                "(#{group.window_names.join(', ')})  split=#{group.split}"
+
+      group.window_names.each_with_index do |wn, idx|
+        printed << wn
+        pane = group_panes.find { |p| p[:title] == wn } ||
+               group_panes.find { |p| p[:pane_index] == idx }
+        if pane.nil?
+          out.puts "  #{wn}: MISSING"
+          next
+        end
+        out.puts "  #{wn}:"
+        print_pane(pane, wn, lines, indent: '    ')
+      end
+      out.puts
+    end
+
+    def render_standalone(name, panes, lines, declared, printed)
+      printed << name
+      pane = panes.find { |p| p[:name] == name && p[:pane_index] == 0 }
+      if pane.nil?
+        out.puts "[?] #{name}  MISSING"
+        out.puts
+        return
+      end
+
+      tag = declared.include?(pane[:name]) ? '' : ' [NOT IN CONFIG]'
+      out.puts "[#{pane[:window_index]}] #{pane[:name]}#{tag}"
+      print_pane(pane, name, lines, indent: INDENT)
+      out.puts
+    end
+
+    # Surface any panes that weren't already printed (unexpected windows).
+    def render_extras(panes, lines, printed)
+      panes.each do |pane|
+        logical = pane[:title].to_s.empty? ? pane[:name] : pane[:title]
+        next if printed.include?(logical) || printed.include?(pane[:name])
+
+        out.puts "[#{pane[:window_index]}] #{pane[:name]} [NOT IN CONFIG]"
+        print_pane(pane, pane[:name], lines, indent: INDENT)
+        out.puts
+      end
+    end
+
+    def print_pane(pane, logical_name, lines, indent: INDENT)
+      idle   = SHELLS.include?(pane[:fg_cmd])
+      status = idle ? idle_status(pane) : running_status(pane, indent)
+
+      in_group = pane[:name] != logical_name
+      target   = in_group ? Tmux.pane_target(pane[:name], pane[:pane_index]) : pane[:name]
+      out.puts "#{indent}target: #{@session}:#{target}"
+      out.puts "#{indent}cwd: #{pane[:cwd]}"
+      out.puts "#{indent}#{status}"
+
+      tail = Tmux.capture_pane(@session, target)
+                 .split("\n")
+                 .reject { |l| l.strip.empty? }
+                 .last(lines)
+      return if tail.empty?
+
+      out.puts "#{indent}--- last output (up to #{lines} lines) ---"
+      tail.each { |l| out.puts "#{indent}#{l}" }
+      out.puts "#{indent}---"
+    end
+
+    def idle_status(pane)
+      "IDLE (shell: #{pane[:fg_cmd]}, pid=#{pane[:pid]})"
+    end
+
+    def running_status(pane, indent)
+      leaf    = ProcessProbe.leaf_pid(pane[:pid])
+      cmd     = ProcessProbe.ps_field(leaf, 'args') || pane[:fg_cmd]
+      elapsed = ProcessProbe.ps_field(leaf, 'etime')&.strip || '?'
+      started = ProcessProbe.ps_field(leaf, 'lstart') || '?'
+      "RUNNING  pid=#{leaf}  elapsed=#{elapsed}  fg=#{pane[:fg_cmd]}\n" \
+        "#{indent}command: #{cmd}\n" \
+        "#{indent}started: #{started}"
+    end
+  end
+end

data/lib/mxup/tmux.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module Mxup
+  # Thin wrapper over the tmux(1) CLI. Every method shells out; nothing here
+  # knows about mxup's own config. Kept as a module so callers can reference
+  # Mxup::Tmux.list_panes(...) without instantiating anything.
+  module Tmux
+    module_function
+
+    # --- inspection --------------------------------------------------------
+
+    def has_session?(name)
+      system("tmux has-session -t #{esc(name)} 2>/dev/null")
+    end
+
+    def session_created(name)
+      `tmux display-message -t #{esc(name)} -p '\#{session_created}'`.strip
+    end
+
+    def list_windows(session)
+      `tmux list-windows -t #{esc(session)} -F '\#{window_index}|\#{window_name}'`
+        .strip.split("\n").map do |line|
+          idx, name = line.split('|', 2)
+          { index: idx.to_i, name: name }
+        end
+    end
+
+    def list_panes(session)
+      fmt = '#{window_index}|#{window_name}|#{pane_index}|#{pane_pid}|' \
+            '#{pane_current_path}|#{pane_current_command}|#{pane_title}'
+      `tmux list-panes -t #{esc(session)} -s -F '#{fmt}'`
+        .strip.split("\n").map do |line|
+          win_idx, name, pane_idx, pid, cwd, fg, title = line.split('|', 7)
+          { window_index: win_idx.to_i, name: name, pane_index: pane_idx.to_i,
+            pid: pid.to_i, cwd: cwd, fg_cmd: fg, title: title.to_s }
+        end
+    end
+
+    def pane_count(session, window)
+      `tmux list-panes -t #{esc(session)}:#{esc(window)} 2>/dev/null`
+        .strip.split("\n").size
+    end
+
+    # Capture the pane's *entire* scrollback (-S - is "start of history") so
+    # callers can filter and tail as they see fit. We deliberately don't pass
+    # -S -N here: if the interesting output scrolled past the visible window,
+    # a lower bound would silently hide it.
+    def capture_pane(session, target, _lines = nil)
+      `tmux capture-pane -t #{esc(session)}:#{esc(target)} -p -S - 2>/dev/null`
+    end
+
+    # --- mutation ----------------------------------------------------------
+
+    def new_session(name, first_window_name, root)
+      system("tmux new-session -d -s #{esc(name)} -n #{esc(first_window_name)} -c #{esc(root)}")
+    end
+
+    def new_window(session, name, root)
+      system("tmux new-window -t #{esc(session)} -n #{esc(name)} -c #{esc(root)}")
+    end
+
+    def split_window(session, window, root, target_pane: nil)
+      target = target_pane \
+        ? "#{esc(session)}:#{esc(window)}.#{target_pane}" \
+        : "#{esc(session)}:#{esc(window)}"
+      system("tmux split-window -t #{target} -c #{esc(root)} -d")
+    end
+
+    def select_layout(session, window, layout)
+      system("tmux select-layout -t #{esc(session)}:#{esc(window)} #{esc(layout)}")
+    end
+
+    def join_pane(session, src_window, dst_window)
+      system("tmux join-pane -s #{esc(session)}:#{esc(src_window)} -t #{esc(session)}:#{esc(dst_window)} -d")
+    end
+
+    # Break a pane out into its own window. Without an explicit -t target,
+    # tmux places the new window in the *current client's* session, which
+    # would send it to whichever session the user happens to be attached to
+    # when running tests. Always pin the destination to the source session.
+    def break_pane(session, window, pane_index, new_window_name)
+      system("tmux break-pane -s #{esc(session)}:#{esc(window)}.#{pane_index} " \
+             "-t #{esc(session)}: -n #{esc(new_window_name)} -d")
+    end
+
+    def rename_window(session, old_name, new_name)
+      system("tmux rename-window -t #{esc(session)}:#{esc(old_name)} #{esc(new_name)}")
+    end
+
+    def set_pane_title(session, window, pane_index, title)
+      system("tmux select-pane -t #{esc(session)}:#{esc(window)}.#{pane_index} -T #{esc(title)}")
+    end
+
+    def set_environment(session, key, value)
+      system("tmux set-environment -t #{esc(session)} #{esc(key)} #{esc(value)}")
+    end
+
+    # Returns the value stored in the session's environment, or nil if unset
+    # (tmux prefixes unset entries with '-').
+    def show_environment(session, key)
+      out = `tmux show-environment -t #{esc(session)} #{esc(key)} 2>/dev/null`.strip
+      return nil if out.empty? || out.start_with?('-')
+      out.split('=', 2).last
+    end
+
+    def kill_window(session, name)
+      system("tmux kill-window -t #{esc(session)}:#{esc(name)}")
+    end
+
+    def kill_session(name)
+      system("tmux kill-session -t #{esc(name)}")
+    end
+
+    def send_keys(session, target, keys)
+      system("tmux send-keys -t #{esc(session)}:#{esc(target)} #{esc(keys)} Enter")
+    end
+
+    def send_interrupt(session, target)
+      system("tmux send-keys -t #{esc(session)}:#{esc(target)} C-c")
+    end
+
+    def move_window(session, src_name, dst_index)
+      system("tmux move-window -s #{esc(session)}:#{esc(src_name)} -t #{esc(session)}:#{dst_index} 2>/dev/null")
+    end
+
+    def swap_window(session, idx_a, idx_b)
+      system("tmux swap-window -s #{esc(session)}:#{idx_a} -t #{esc(session)}:#{idx_b}")
+    end
+
+    # --- helpers -----------------------------------------------------------
+
+    # Format a pane target string "window.index" for use in other tmux calls.
+    def pane_target(window, pane_index)
+      "#{window}.#{pane_index}"
+    end
+
+    def esc(val)
+      Shellwords.escape(val.to_s)
+    end
+  end
+end

data/lib/mxup/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Mxup
+  VERSION = '0.2.0'
+end

data/lib/mxup.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Declarative tmux session manager with reconciliation.
+#
+# Public entry points:
+#   Mxup::CLI.new.run(argv)     — command-line dispatch
+#   Mxup::Config.new(path)      — parse a YAML config
+#   Mxup::Runner.new(config)    — programmatic API (up/down/status/...)
+#
+# Internals are organised into focused modules under lib/mxup/:
+#   Config / Window / PaneGroup / WaitSpec   — pure data
+#   Tmux                                     — thin tmux(1) wrapper
+#   Launcher                                 — per-window launcher scripts
+#   PaneResolver                             — logical-name → tmux target
+#   Reconciler                               — `up` / `reconcile` orchestration
+#   LayoutManager                            — layout switching (flatten + regroup)
+#   StatusView                               — `status` rendering
+#   ExecRunner                               — `exec` with marker + timeout
+#   GracefulStop                             — cooperative SIGINT-then-wait
+#   ProcessProbe                             — pane → real leaf process info
+#   Runner                                   — facade delegating to the above
+#   CLI                                      — argv parsing + command dispatch
+
+require_relative 'mxup/version'
+
+module Mxup
+  CONFIG_DIR   = File.expand_path('~/.config/mxup')
+  RUNTIME_DIR  = File.expand_path('~/.local/share/mxup')
+  SHELLS       = %w[zsh bash sh fish dash].freeze
+end
+
+require_relative 'mxup/config'
+require_relative 'mxup/tmux'
+require_relative 'mxup/launcher'
+require_relative 'mxup/process_probe'
+require_relative 'mxup/pane_resolver'
+require_relative 'mxup/graceful_stop'
+require_relative 'mxup/layout_manager'
+require_relative 'mxup/reconciler'
+require_relative 'mxup/status_view'
+require_relative 'mxup/exec_runner'
+require_relative 'mxup/runner'
+require_relative 'mxup/cli'

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: mxup
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Vladislav Saifulin
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.1'
+description: |
+  mxup brings a live tmux session into agreement with a YAML description of
+  windows, commands, and layouts. It creates missing windows, restarts crashed
+  ones, removes undeclared ones, and leaves healthy windows alone. Re-running
+  `mxup up` is always safe.
+email:
+- vladislav.saifulin@jetbrains.com
+executables:
+- mxup
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/mxup
+- examples/myapp-dev.yml
+- lib/mxup.rb
+- lib/mxup/cli.rb
+- lib/mxup/config.rb
+- lib/mxup/exec_runner.rb
+- lib/mxup/graceful_stop.rb
+- lib/mxup/launcher.rb
+- lib/mxup/layout_manager.rb
+- lib/mxup/pane_resolver.rb
+- lib/mxup/process_probe.rb
+- lib/mxup/reconciler.rb
+- lib/mxup/runner.rb
+- lib/mxup/status_view.rb
+- lib/mxup/tmux.rb
+- lib/mxup/version.rb
+homepage: https://github.com/Recognized/mxup
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Recognized/mxup
+  source_code_uri: https://github.com/Recognized/mxup
+  bug_tracker_uri: https://github.com/Recognized/mxup/issues
+  changelog_uri: https://github.com/Recognized/mxup/releases
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Declarative tmux session manager with reconciliation.
+test_files: []