mxup 0.3.1 → 1.0.1

data/lib/mxup/config.rb

@@ -7,26 +7,57 @@ require_relative 'env_file'
 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.
+  # Config format generations: `mxup_version` names the generation a config was
+  # written for, and mxup reads every generation up to its own — so upgrading
+  # mxup never forces a config rewrite. The declared major selects how
+  # `profiles:` is read; nothing else in the format differs between them.
+  #
+  # Profiles (optional): a config may declare a `profiles:` map. What selecting
+  # one means depends on the generation:
+  #
+  # * Format 1 (`mxup_version: '1'`) — *additive*, and any number of profiles
+  #   may be selected at once. The base `windows:` block is a catalog, and a
+  #   window only runs when at least one selected profile opts in to it.
+  #   Several profiles opting in to the same window is fine; two of them
+  #   overriding the same setting differently is a collision and aborts with an
+  #   explanation.
+  # * Format 0 (no `mxup_version` — every config written for 0.3.1 or earlier)
+  #   — *subtractive*, one profile at a time. Every window in `windows:` runs;
+  #   the active profile overrides some of them and drops others with `~`.
+  #
+  # Either way the merged result is applied before the rest of the Config is
+  # built — so the rest of the system (Launcher, Reconciler, StatusView…) never
+  # has to know about profiles or generations.
   class Config
-    KNOWN_TOP_LEVEL_KEYS    = %w[session setup root live_env required_env windows layouts profiles default_profile].freeze
+    # Config format generations this mxup can read. Generation N ships in mxup
+    # N.0.0 and every older one keeps working, so this range only ever grows.
+    CURRENT_FORMAT_MAJOR    = 1
+    SUPPORTED_FORMAT_MAJORS = (0..CURRENT_FORMAT_MAJOR).freeze
+
+    KNOWN_TOP_LEVEL_KEYS    = %w[mxup_version session setup root live_env required_env windows layouts profiles default_profile].freeze
     KNOWN_WINDOW_KEYS       = %w[root command env wait_for live_env commands].freeze
     KNOWN_LAYOUT_GROUP_KEYS = %w[panes split].freeze
     KNOWN_PROFILE_KEYS      = %w[setup root layouts live_env windows].freeze
 
+    # Profile keys that replace their base value wholesale, so two profiles
+    # declaring them differently cannot be reconciled.
+    PROFILE_SCALAR_KEYS = %w[setup root layouts].freeze
+
+    # Window keys that are themselves maps, compared entry-by-entry so two
+    # profiles can each contribute a different env var to the same window.
+    NESTED_WINDOW_KEYS = %w[env commands].freeze
+
     attr_reader :session, :setup, :root, :windows, :layouts, :layout_names,
-                :profile, :profile_names, :default_profile, :live_env,
-                :live_env_dir, :required_env, :env_file_path
+                :profiles, :profile_names, :default_profiles, :live_env,
+                :live_env_dir, :required_env, :env_file_path, :format_major
 
-    def initialize(path, profile: nil)
+    # `profiles` accepts nil, a single name, or a list; `-p a,b` and
+    # `-p a -p b` both arrive here as the same selection.
+    def initialize(path, profiles: nil)
       raw = YAML.safe_load(File.read(path), permitted_classes: [Symbol])
+      @format_major = resolve_format_major!(raw)
       validate_keys!(raw, KNOWN_TOP_LEVEL_KEYS, 'top level')
-      resolve_profile!(raw, profile)
+      resolve_profiles!(raw, profiles)
       @session      = raw.fetch('session')
       @setup        = raw['setup']&.strip
       @live_env_dir = config_base_dir(path)
@@ -36,10 +67,17 @@ module Mxup
       load_env_file_into_env!
       @root         = resolve_root(raw['root'], path)
       @windows      = parse_windows(raw.fetch('windows'))
+      validate_windows_present!
       validate_window_live_env!
       @layouts, @layout_names = parse_layouts(raw['layouts'])
     end
 
+    # The selection as stored in the session's tmux environment (MXUP_PROFILE),
+    # so `status` can display it and `up` can detect a switch.
+    def profiles_label
+      @profiles.join(',')
+    end
+
     def default_layout
       @layout_names.first
     end
@@ -78,98 +116,407 @@ module Mxup
 
     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
+    # A config declares the format generation it was written for, and mxup
+    # reads every generation up to its own. The declared major therefore
+    # *selects* the profile semantics rather than gating the config out, so an
+    # mxup upgrade never forces a config rewrite; only a config aimed at a
+    # newer mxup is refused. Resolved before any other validation, so such a
+    # config explains itself instead of tripping over a key it doesn't know.
+    def resolve_format_major!(raw)
+      @format_pinned = false
+      return CURRENT_FORMAT_MAJOR unless raw.is_a?(Hash)
+
+      declared = raw['mxup_version']
+      # No `mxup_version` means the config predates the key, which only existed
+      # from major 1 on — so it is read as the original format, major 0.
+      @format_pinned = !declared.nil?
+      wanted   = declared.nil? ? 0 : parse_mxup_major(declared)
+      return wanted if SUPPORTED_FORMAT_MAJORS.include?(wanted)
+
+      raise ArgumentError, format_from_the_future(wanted)
+    end
+
+    def legacy_format?
+      @format_major.zero?
+    end
+
+    def parse_mxup_major(declared)
+      # Guarded explicitly: Gem::Version reads a blank string as 0, which would
+      # quietly pass as "major 0" instead of flagging the empty value.
+      if declared.to_s.strip.empty?
+        raise ArgumentError, "mxup_version must name a major version, e.g. '1'"
+      end
+      unless Gem::Version.correct?(declared.to_s)
+        raise ArgumentError, "mxup_version '#{declared}' is not a valid version"
+      end
+
+      # Only the major is compared, so anything after it is decoration: '2',
+      # '2.0' and '2.7.3' all pin the same format generation.
+      Gem::Version.new(declared.to_s).segments.first
+    end
 
-      if profiles.empty?
-        if requested
+    # Only reachable for a generation newer than this mxup knows: older ones
+    # are read, not refused.
+    def format_from_the_future(wanted)
+      <<~MSG.chomp
+        This config targets the mxup #{wanted}.x config format, but mxup #{VERSION}
+        reads up to #{CURRENT_FORMAT_MAJOR}.x. Update mxup, then try again:
+          brew upgrade mxup   # if installed via Homebrew
+          gem update mxup     # if installed via RubyGems
+      MSG
+    end
+
+    # Resolve the selected profiles and merge them into `raw`.
+    # Sets @profiles / @profile_names / @default_profiles.
+    def resolve_profiles!(raw, requested)
+      declared          = raw['profiles'] || {}
+      @profile_names    = declared.keys
+      @default_profiles = Array(raw['default_profile']).map(&:to_s)
+      selected          = normalize_profile_selection(requested)
+
+      if declared.empty?
+        unless selected.empty?
           raise ArgumentError,
-                "--profile '#{requested}' was given, but this config declares no profiles"
+                "--profile '#{selected.join(', ')}' was given, but this config " \
+                'declares no profiles'
         end
-        @profile = nil
+        @profiles = []
         return
       end
 
-      @profile = requested || @default_profile
-      unless profiles.key?(@profile)
+      validate_legacy_selection!(selected) if legacy_format?
+      @profiles = selected.empty? ? default_profile_selection : selected
+
+      unknown = @profiles - @profile_names
+      unless unknown.empty?
         raise ArgumentError,
-              "Unknown profile '#{@profile}' (available: #{@profile_names.join(', ')})"
+              "Unknown profile(s) #{unknown.map { |n| "'#{n}'" }.join(', ')} " \
+              "(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)
+      overrides = @profiles.map do |n|
+        override = declared.fetch(n)
+        [n, override.is_a?(Hash) ? override : {}]
+      end
 
-      validate_keys!(override, KNOWN_PROFILE_KEYS, "profile '#{@profile}'")
+      if legacy_format?
+        warn_legacy_profiles unless @format_pinned
+        apply_legacy_profile!(raw, *overrides.first)
+      else
+        apply_profiles!(raw, overrides)
+      end
+    end
 
-      if override.key?('session')
+    # Selecting several profiles at once, and pointing `default_profile` at
+    # several, both arrived with format 1. Under format 0 exactly one profile is
+    # active, so say what to change instead of quietly using just the first.
+    def validate_legacy_selection!(selected)
+      if selected.size > 1
         raise ArgumentError,
-              "Profile '#{@profile}' cannot override 'session'; profiles of the " \
-              'same group must share one tmux session name'
+              legacy_single_profile_message(
+                "--profile '#{selected.join(', ')}' selects #{selected.size} profiles"
+              )
       end
+      return unless @default_profiles.size > 1
 
-      raw['setup']   = override['setup']   if override.key?('setup')
-      raw['root']    = override['root']    if override.key?('root')
-      raw['layouts'] = override['layouts'] if override.key?('layouts')
+      raise ArgumentError,
+            legacy_single_profile_message(
+              "default_profile lists #{@default_profiles.size} profiles"
+            )
+    end
+
+    def legacy_single_profile_message(subject)
+      <<~MSG.chomp
+        #{subject}, which the mxup 1.x config format added.
+        This config is read as the 0.x format, where one profile is active at a
+        time. Run `mxup migrations` to see what 1.x changed, then set
+        `mxup_version: '1'` to select several at once.
+      MSG
+    end
+
+    # Format 0 and format 1 read the same `profiles:` text differently, and this
+    # is the only place they diverge — so a config that hasn't opted in is told
+    # which meaning it is getting. Two cases stay quiet: a config without
+    # `profiles:` (the generations are identical for it, so there is nothing to
+    # do) and one that pins `mxup_version: '0'`, which is an informed choice
+    # rather than a config that never heard about the key.
+    def warn_legacy_profiles
+      warn <<~MSG.chomp
+        mxup: reading `profiles:` with the 0.x meaning (every window in `windows:` runs;
+        the profile overrides some and drops others with `~`). Run `mxup migrations`,
+        then set `mxup_version: '1'` to switch to additive profiles.
+      MSG
+    end
+
+    # Format 0 profile semantics, kept so configs written for mxup 0.3.1 and
+    # earlier keep running unchanged: the profile is a partial override on the
+    # base config, and every window it does not mention still runs.
+    def apply_legacy_profile!(raw, name, override)
+      validate_profile!(name, override)
+
+      PROFILE_SCALAR_KEYS.each { |key| raw[key] = override[key] if override.key?(key) }
 
       if override.key?('live_env')
-        base_le = raw['live_env'] || {}
-        prof_le = override['live_env'] || {}
-        raw['live_env'] = base_le.merge(prof_le)
+        raw['live_env'] = (raw['live_env'] || {}).merge(override['live_env'] || {})
       end
 
+      apply_legacy_windows!(raw, override['windows'] || {})
+    end
+
+    # `~` drops a window for this profile; any other value is merged onto the
+    # base entry, adding the window when the base declares none.
+    def apply_legacy_windows!(raw, windows)
+      return if windows.empty?
+
+      raw['windows'] ||= {}
       removed = []
-      (override['windows'] || {}).each do |wname, woverride|
-        raw['windows'] ||= {}
+
+      windows.each do |wname, woverride|
         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)
+          raw['windows'][wname] = merge_legacy_window(raw['windows'][wname] || {}, woverride)
         end
       end
 
-      prune_layouts!(raw, removed) if removed.any?
+      prune_removed_from_layouts!(raw, removed)
+    end
+
+    # Shallow merge, except that `env` and `commands` are themselves maps and
+    # merge entry by entry — so a profile can tweak one of their keys without
+    # redeclaring the rest.
+    def merge_legacy_window(base, override)
+      base.merge(override) do |key, base_val, prof_val|
+        if NESTED_WINDOW_KEYS.include?(key) && base_val.is_a?(Hash) && prof_val.is_a?(Hash)
+          base_val.merge(prof_val)
+        else
+          prof_val
+        end
+      end
     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)
+    # Strip only the windows this profile dropped from layout groups, so
+    # parse_layouts still reports a pane naming a window that was never in
+    # `windows:` as the typo it is — as 0.3.1 did. (The format 1 path prunes by
+    # what was *kept*, because there a window is absent until a profile opts in.)
+    def prune_removed_from_layouts!(raw, removed)
+      return if removed.empty?
       return unless raw['layouts'].is_a?(Hash)
-      removed_set = removed.to_set
+      dropped = 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'].reject! { |pn| dropped.include?(pn) }
           group_def['panes'].empty?
         end
       end
     end
 
-    # Shallow merge with a special case: `env` and `commands` are themselves
-    # hashes 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 %w[env commands].include?(key) && base_val.is_a?(Hash) && prof_val.is_a?(Hash)
-          base_val.merge(prof_val)
-        else
-          prof_val
+    # Duplicates collapse — naming the same profile twice is not a collision
+    # with itself.
+    def normalize_profile_selection(requested)
+      Array(requested)
+        .flat_map { |p| p.to_s.split(',') }
+        .map(&:strip).reject(&:empty?).uniq
+    end
+
+    def default_profile_selection
+      @default_profiles.empty? ? [@profile_names.first] : @default_profiles
+    end
+
+    # Merge every selected profile into `raw`, collecting disagreements as we
+    # go so a config with several conflicts reports all of them at once rather
+    # than one per run.
+    def apply_profiles!(raw, selected)
+      selected.each { |name, override| validate_profile!(name, override) }
+
+      collisions = []
+      claims     = {}
+
+      apply_profile_scalars!(raw, selected, claims, collisions)
+      apply_profile_live_env!(raw, selected, claims, collisions)
+      windows = resolve_profile_windows(raw, selected, claims, collisions)
+
+      raise ArgumentError, collision_report(collisions) if collisions.any?
+
+      raw['windows'] = windows
+      prune_layouts!(raw, windows.keys)
+    end
+
+    def validate_profile!(name, override)
+      validate_keys!(override, KNOWN_PROFILE_KEYS, "profile '#{name}'")
+
+      return unless override.key?('session')
+      raise ArgumentError,
+            "Profile '#{name}' cannot override 'session'; profiles of the " \
+            'same group must share one tmux session name'
+    end
+
+    def apply_profile_scalars!(raw, selected, claims, collisions)
+      PROFILE_SCALAR_KEYS.each do |key|
+        selected.each do |name, override|
+          next unless override.key?(key)
+          claim!(claims, collisions, "top-level '#{key}'", name, override[key])
+          raw[key] = override[key]
+        end
+      end
+    end
+
+    # Profile live_env entries override the base per variable, so two profiles
+    # collide only when they declare the *same* variable differently.
+    def apply_profile_live_env!(raw, selected, claims, collisions)
+      merged = (raw['live_env'] || {}).dup
+
+      selected.each do |name, override|
+        (override['live_env'] || {}).each do |var, command|
+          claim!(claims, collisions, "live_env '#{var}'", name, command)
+          merged[var] = command
         end
       end
+
+      raw['live_env'] = merged unless merged.empty?
+    end
+
+    # Build the effective `windows:` map from the selected profiles. A window
+    # is included when at least one profile lists it with a (possibly empty)
+    # override; mapping it to null ("db: ~") is an explicit veto, which
+    # collides with any profile that includes the same window.
+    def resolve_profile_windows(raw, selected, claims, collisions)
+      catalog  = raw['windows'] || {}
+      vetoes   = {}
+      includes = {}
+
+      selected.each do |name, override|
+        (override['windows'] || {}).each do |wname, woverride|
+          if woverride.nil?
+            (vetoes[wname]   ||= []) << name
+          else
+            (includes[wname] ||= []) << [name, woverride]
+          end
+        end
+      end
+
+      flag_veto_collisions(vetoes, includes, collisions)
+
+      order_included_windows(catalog, includes).each_with_object({}) do |wname, acc|
+        acc[wname] = merge_profile_window(
+          wname, catalog[wname] || {}, includes[wname], claims, collisions
+        )
+      end
+    end
+
+    def flag_veto_collisions(vetoes, includes, collisions)
+      includes.each_key do |wname|
+        vetoed_by = vetoes[wname]
+        next unless vetoed_by
+
+        collisions << {
+          label: "window '#{wname}'",
+          text:  "vetoed by #{vetoed_by.join(', ')}, but included by " \
+                 "#{includes[wname].map(&:first).join(', ')}"
+        }
+      end
+    end
+
+    # Catalog order first, so window and pane ordering stays stable no matter
+    # which profile happened to mention a window first. Windows a profile
+    # declares from scratch follow, in the order they were encountered.
+    def order_included_windows(catalog, includes)
+      catalog.keys.select { |n| includes.key?(n) } + (includes.keys - catalog.keys)
+    end
+
+    # Layer every including profile's override onto the catalog entry. Keys are
+    # claimed one at a time (and `env`/`commands` entry by entry) so profiles
+    # touching different settings of the same window merge cleanly.
+    def merge_profile_window(wname, base, entries, claims, collisions)
+      entries.each_with_object(base.dup) do |(pname, override), merged|
+        override.each do |key, value|
+          if NESTED_WINDOW_KEYS.include?(key) && value.is_a?(Hash)
+            nested = (merged[key] || {}).dup
+            value.each do |nkey, nvalue|
+              claim!(claims, collisions, "window '#{wname}' → #{key}.#{nkey}", pname, nvalue)
+              nested[nkey] = nvalue
+            end
+            merged[key] = nested
+          else
+            claim!(claims, collisions, "window '#{wname}' → #{key}", pname, value)
+            merged[key] = value
+          end
+        end
+      end
+    end
+
+    # Record "profile P set LABEL to VALUE". A later profile setting the same
+    # label to a *different* value is the collision we report; setting it to
+    # the same value silently agrees.
+    def claim!(claims, collisions, label, profile, value)
+      previous = claims[label]
+      if previous && previous.last != value
+        collisions << { label: label, first: previous, second: [profile, value] }
+      end
+      claims[label] = [profile, value]
+    end
+
+    def collision_report(collisions)
+      lines = ["Profile collision: the selected profiles " \
+               "(#{@profiles.join(', ')}) disagree.", '']
+
+      collisions.each do |c|
+        lines.concat(c[:text] ? ["  #{c[:label]}: #{c[:text]}"] : disagreement_lines(c))
+        lines << ''
+      end
+
+      lines << 'Select fewer profiles, or make the conflicting values agree.'
+      lines.join("\n")
+    end
+
+    def disagreement_lines(collision)
+      first, second = collision.values_at(:first, :second)
+      width         = [first.first.length, second.first.length].max
+
+      ["  #{collision[:label]}"] + [first, second].map do |profile, value|
+        "    #{profile.ljust(width)}  sets #{format_collision_value(value)}"
+      end
+    end
+
+    def format_collision_value(value)
+      text = value.inspect
+      text.length > 70 ? "#{text[0, 67]}..." : text
+    end
+
+    # Strip window names that no selected profile included 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, kept_names)
+      return unless raw['layouts'].is_a?(Hash)
+      kept = kept_names.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'].select! { |pn| kept.include?(pn) }
+          group_def['panes'].empty?
+        end
+      end
+    end
+
+    # Under additive profiles an empty selection is a realistic mistake (a
+    # profile that declares no `windows:` runs nothing), so say so plainly
+    # instead of letting the reconciler fail on a session with zero windows.
+    def validate_windows_present!
+      return unless @windows.empty?
+
+      if @profiles.any? && !legacy_format?
+        raise ArgumentError,
+              "Profile(s) #{@profiles.join(', ')} include no windows — nothing " \
+              'would run. Each profile lists the windows it runs under `windows:`.'
+      end
+
+      raise ArgumentError, 'Config declares no windows'
     end
 
     def parse_windows(hash)

data/lib/mxup/migrations.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Mxup
+  # The config format's history, one entry per major version, plus the renderer
+  # behind `mxup migrations`.
+  #
+  # A new config format generation ships with a new mxup major, and mxup goes on
+  # reading every older generation (see Config#resolve_format_major!) — so every
+  # major above the first has exactly one entry here describing what changed and
+  # how to move a config written for the previous one. When cutting a new major,
+  # add an entry and bump Config::CURRENT_FORMAT_MAJOR to match its `to`.
+  module Migrations
+    # `from`/`to` are majors. `changes` each have a title and, for readability
+    # at the terminal, pre-wrapped `before` / `now` / `fix` prose.
+    ENTRIES = [
+      {
+        from: 0,
+        to: 1,
+        changes: [
+          {
+            title: 'Profiles select windows additively instead of subtracting them',
+            before: 'Every window in `windows:` ran. A profile overrode some of ' \
+                    'them and dropped others with `~`, so `staging: {}` meant ' \
+                    '"run everything, unchanged".',
+            now:    '`windows:` is a catalog and nothing in it runs on its own. ' \
+                    'Each profile lists the windows it runs, and several profiles ' \
+                    'can be selected at once (`-p a,b`) — the live set is their ' \
+                    'union. A window no selected profile lists stays down.',
+            fix:    'In every profile, list the windows it should run: `name: {}` ' \
+                    'to include one as declared in the catalog, or a non-empty ' \
+                    'block to include it with overrides. A profile that listed ' \
+                    'nothing (`staging: {}`) must now name every window it wants, ' \
+                    'and a profile that dropped windows with `name: ~` should ' \
+                    'instead list the ones it keeps. `~` still parses, but it now ' \
+                    'means "veto": it collides if another selected profile ' \
+                    'includes that window.'
+          },
+          {
+            title: '`default_profile` may name several profiles',
+            before: 'A single profile name.',
+            now:    'A name or a list of names, selected together when ' \
+                    '`--profile` is omitted.',
+            fix:    'Nothing to change — a single name still works.'
+          },
+          {
+            title: '`mxup_version` selects which format a config is read as',
+            before: 'The key did not exist.',
+            now:    'A config with no `mxup_version` is read as the 0.x format — ' \
+                    'profiles included — so it goes on running under mxup 1.x ' \
+                    'exactly as it did under 0.3.1. The key is what opts a ' \
+                    'config in to the format described above.',
+            fix:    'Nothing, to keep a 0.x config working. Set ' \
+                    "`mxup_version: '1'` once you have migrated its profiles; " \
+                    'that is also what unlocks selecting several at once.'
+          }
+        ]
+      }
+    ].freeze
+
+    class << self
+      def render(out: $stdout)
+        out.puts "mxup #{VERSION} — config format changes by major version."
+        out.puts
+
+        ENTRIES.each { |entry| render_entry(entry, out) }
+
+        out.puts '`mxup_version` names the generation a config is written for, and'
+        out.puts 'mxup reads every generation up to its own — so a config with no'
+        out.puts '`mxup_version` keeps running as 0.x. Set it to the major you have'
+        out.puts 'migrated to.'
+      end
+
+      private
+
+      def render_entry(entry, out)
+        out.puts "#{entry[:from]}.x -> #{entry[:to]}.x"
+        out.puts
+
+        entry[:changes].each_with_index do |change, i|
+          out.puts "  #{i + 1}. #{change[:title]}"
+          %i[before now fix].each do |key|
+            out.puts wrap(change[key], label: "#{key.to_s.capitalize}:")
+          end
+          out.puts
+        end
+      end
+
+      # Hanging-indent wrap so each paragraph's continuation lines line up under
+      # its text rather than under the label.
+      def wrap(text, label:, width: 76, indent: 5)
+        prefix   = "#{' ' * indent}#{label.ljust(8)}"
+        continue = ' ' * prefix.length
+        lines    = []
+
+        text.split(' ').each do |word|
+          if lines.empty?
+            lines << prefix + word
+          elsif (lines.last.length + 1 + word.length) > width
+            lines << continue + word
+          else
+            lines[-1] = "#{lines.last} #{word}"
+          end
+        end
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/mxup/reconciler.rb

@@ -64,7 +64,7 @@ module Mxup
       order.drop(1).each { |entry| create_entry(entry) }
 
       Tmux.set_environment(@session, 'MXUP_LAYOUT', layout) if layout
-      Tmux.set_environment(@session, 'MXUP_PROFILE', @config.profile) if @config.profile
+      Tmux.set_environment(@session, 'MXUP_PROFILE', @config.profiles_label) if @config.profiles.any?
       out.puts "Session #{@session} is up (#{@config.windows.size} windows)."
     end
 
@@ -113,7 +113,9 @@ module Mxup
 
       @layout_manager.reorder(layout) unless @dry_run
       Tmux.set_environment(@session, 'MXUP_LAYOUT', layout) if layout && !@dry_run
-      Tmux.set_environment(@session, 'MXUP_PROFILE', @config.profile) if @config.profile && !@dry_run
+      if @config.profiles.any? && !@dry_run
+        Tmux.set_environment(@session, 'MXUP_PROFILE', @config.profiles_label)
+      end
       out.puts 'Reconciliation complete.'
     end