mxup 0.3.1 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e54d64b96a5c0a433b057548e5fab1488f368ce0f8dc76eb13143247d375b76f
-  data.tar.gz: 7b5aba9d337cdd67584bdd7650df537cd745fbe6bcc7f1fe3b04b618cd47ae57
+  metadata.gz: 4531ad3aa556a0ca370760f6f2021bbbf4c9a111d404989cd6b24fb6e88f1e06
+  data.tar.gz: 93a8f02afacc7332e064124807f5ea47c400d0de44584c90fbcc18b7e8399134
 SHA512:
-  metadata.gz: a684f0279fc7a09f59dc9aa34765ce5b1fd451e20fb3aadb5612d574d16328e12d938221ac68a36ec746f9dd977585194fa69d9483e18b13d49624aaae0310c8
-  data.tar.gz: a88115c2a794c40cb11800f7380f8e6d65d69b07a0f565f0606b3142062b82c352bd5f8717a76111e391e1bef8731cd80fa373d6ddbc1281ee703734e0b33f14
+  metadata.gz: 4a3c824064e22953dd14a56a6cef28548b62d2b0d8d7bd0603d61070a89c602476436977d16da51e13e5511d0ca6249fb223784456407bae5c4e777e76efd334
+  data.tar.gz: 8df2f3eade22728fca31fcd384de5a7820358b0ec2d4512898b4c5424601bc60dddfae6a12845de428ee4a8a9e24dadbb48b25f725054268433b6452eb058a2f

data/README.md

@@ -6,20 +6,37 @@ Run `mxup up` any time — it creates what's missing, restarts what crashed, rem
 
 ## Install
 
-Requires `tmux` and Ruby 3.1+ (stdlib only — no runtime gem dependencies).
+### Homebrew (recommended on macOS)
 
-### RubyGems
+Current Homebrew versions require third-party taps to be added and trusted
+explicitly:
 
 ```bash
-gem install mxup
+brew tap Recognized/mxup
+brew trust Recognized/mxup
+brew install mxup
+mxup --version
 ```
 
-### Homebrew
+Homebrew installs the required `tmux` and Ruby versions automatically. If
+Homebrew reports that Xcode or the Command Line Tools are outdated, update
+them through System Settings or Apple Developer Downloads, then retry.
+
+### RubyGems
+
+RubyGems installation requires Ruby 3.1+ and `tmux`:
 
 ```bash
-brew install Recognized/mxup/mxup
+ruby --version
+gem install mxup
+mxup --version
 ```
 
+The Ruby bundled with older macOS versions is too old. Install a current Ruby
+first (for example with `brew install ruby`). If installation succeeds but
+`mxup` is not found, add the executable directory shown by `gem environment`
+to your `PATH`.
+
 ### From source
 
 ```bash
@@ -112,6 +129,7 @@ windows:
 | Field | Required | Description |
 |-------|----------|-------------|
 | `session` | yes | tmux session name |
+| `mxup_version` | no | Config format generation this config is written for. Omit it and the config is read as the pre-1.0 format, which keeps working (see [Config format versions](#config-format-versions)) |
 | `setup` | no | Shell snippet prepended to every window's command |
 | `root` | no | Base directory for relative window `root` values. Relative paths resolve against the config file's directory — or, if the config lives in a project-local `.mxup/` directory, against `.mxup/`'s parent (the project root). `~` and absolute paths are kept as-is. Supports `$VAR` / `${VAR}` env-var expansion (an unset variable is an error). |
 | `required_env` | no | Env vars that must be filled in before `mxup up` will start (see [Required env vars](#required-env-vars)) |
@@ -127,6 +145,96 @@ Per window:
 | `wait_for` | no | Readiness check to pass before running command (see below) |
 | `commands` | no | Map of named one-off commands runnable via `mxup <config> <window>:<name>` (see [Named commands](#named-commands-mxup-configwindowname)) |
 
+### Config format versions
+
+`mxup_version` names the **config format generation** a config is written
+for, and mxup reads every generation up to its own:
+
+```yaml
+mxup_version: '1'
+session: my-project
+```
+
+Only the major is read, so `'1'`, `'1.0'` and `'1.4.2'` all name the same
+generation — write whichever reads best. Majors compare numerically, so
+`10.x` is newer than `9.x`.
+
+**Omitting the key is fine, and always will be.** A config with no
+`mxup_version` is read as the pre-1.0 format, major 0 — including the way
+its [profiles](#profiles) work — so every config written for `0.3.1` or
+earlier keeps running under `1.x` untouched. Nothing to migrate, no flag to
+pass.
+
+Two things follow from that:
+
+- **Upgrading mxup never forces a config rewrite.** A new generation ships
+  with a new mxup major, and older generations keep being read. `mxup_version`
+  selects how your config is interpreted; it is not a gate that locks you out.
+- **The generation is a choice, not a version check.** Set `mxup_version: '1'`
+  when you want the 1.x format's behaviour — [additive
+  profiles](#profiles), and selecting several at once. Until then your config
+  behaves the way it always did.
+
+The one thing mxup can't read is a config from the *future* — a generation
+newer than it knows about:
+
+```
+$ mxup up my-project
+This config targets the mxup 2.x config format, but mxup 1.0.0
+reads up to 1.x. Update mxup, then try again:
+  brew upgrade mxup   # if installed via Homebrew
+  gem update mxup     # if installed via RubyGems
+```
+
+That's resolved before any other validation, so such a config says so
+instead of failing on a key it doesn't recognise.
+
+Because format 0 and format 1 read the same `profiles:` block differently,
+a config that uses profiles and hasn't picked a generation is told which
+meaning it's getting, once per command, on stderr:
+
+```
+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.
+```
+
+Configs with no `profiles:` block stay silent — the two generations are
+identical for them. So does one that pins `mxup_version: '0'`, which says
+the 0.x reading is deliberate.
+
+### What each major changed (`mxup migrations`)
+
+`mxup migrations` prints the config format's history — for every major, what
+changed and how to update a config written for the previous one. It needs no
+config file, which is the point: it's what you run when your config won't
+load.
+
+```
+$ mxup migrations
+mxup 1.0.0 — config format changes by major version.
+
+0.x -> 1.x
+
+  1. 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. …
+```
+
+One caveat this can't solve retroactively, and it points the other way:
+mxup versions released before `mxup_version` existed (0.3.1 and earlier)
+don't know the key, so a config carrying `mxup_version: '1'` is refused by
+an *old* mxup as an unknown top-level key. New mxup reading old configs is
+the direction that's seamless.
+
 ### Wait-for checks
 
 `wait_for` blocks a window's command until a readiness condition is met.
@@ -336,19 +444,24 @@ mxup layout my-project compact
 
 ### Profiles
 
-A single project often needs to run under different stacks — "local
-everything", "staging backend with local frontend", etc. Profiles express
-those variants as a set of overrides on top of a shared base. Only one
-profile of a given config may be live at a time; `mxup up` of a different
-profile automatically tears the current one down first.
+A single project often needs to run under different stacks — "just the
+backend", "frontend against staging", "everything plus a scratch shell".
+Profiles are **additive slices** of the `windows:` block: each profile
+lists the windows it runs, and you can select as many as you like at
+once. The live selection is the union of what those profiles include.
+
+This describes the `1.x` config format, so the config declares it with
+[`mxup_version`](#config-format-versions). A config that omits the key
+keeps the older, subtractive meaning — see [Profiles in the 0.x
+format](#profiles-in-the-0x-format) below.
 
 ```yaml
+mxup_version: '1'
 session: my-project
 
-windows:
+windows:                         # a catalog; nothing here runs on its own
   backend:
     root: ~/projects/my-app/backend
-    command: ./start-server.sh
     env:
       DATABASE_URL: postgres://localhost/myapp_dev
 
@@ -356,56 +469,150 @@ windows:
     root: ~/projects/my-app/frontend
     command: npm run dev
 
+  scratch:
+    root: ~/projects/my-app
+
 profiles:
-  local: {}                      # uses the base as-is
+  backend:                       # backend, served locally
+    windows:
+      backend:
+        command: ./start-server.sh
 
-  staging:
+  staging-backend:               # same window, pointed at staging
     windows:
       backend:
         command: ./connect-staging.sh
         env:
           DATABASE_URL: postgres://staging-db/myapp
+
+  frontend:
+    windows:
+      frontend: {}               # include as declared in the catalog
+
+  scratch:
+    windows:
+      scratch: {}
 ```
 
-Pick a profile with `--profile` (short: `-p`):
+Settings shared by every variant of a window live in the catalog; the bits
+that differ live in the profiles that select it.
+
+Select profiles with `--profile` (short: `-p`), which is repeatable and
+accepts a comma-separated list:
 
 ```bash
-mxup up my-project --profile=local
-mxup up my-project -p staging     # tears down 'local' first
-mxup status my-project            # shows "profile: staging" in the header
+mxup up my-project -p backend,frontend        # both slices
+mxup up my-project -p backend -p frontend     # same thing
+mxup up my-project -p staging-backend -p frontend
+mxup status my-project                        # shows the live selection
 ```
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `profiles` | no | Map of profile name → override block |
-| `default_profile` | no | Profile to use when `--profile` is omitted (defaults to the first declared) |
-
-**Override semantics**: the active profile's `setup`, `windows`, and
-`layouts` override the base. Window overrides are merged per-key (so you
-can tweak just `command` or `env` without redeclaring `root`). `env` maps
-are themselves merged — keys not in the profile are inherited from the
-base. A profile may not override `session`; profiles of the same group
-must share one tmux session.
-
-**Dropping windows**: to exclude a base window from a profile, map it to
-`~` (YAML null):
+| `profiles` | no | Map of profile name → the windows it runs (plus optional overrides) |
+| `default_profile` | no | Profile name, or list of names, selected when `--profile` is omitted (defaults to the first declared) |
+
+**Inclusion**: a window runs when at least one selected profile lists it.
+A window no selected profile lists stays down — including when it is
+declared in the base `windows:` block. A profile that lists no windows at
+all is an error, since it would bring up an empty session.
+
+Layout groups are pruned to the windows that actually run: names are
+stripped from `panes:` lists, and a group that ends up empty is removed
+from its layout.
+
+**Overrides**: `{}` includes a window as declared in the catalog. A
+non-empty block overrides it per key, so you can tweak just `command` or
+`env` without redeclaring `root`; `env` and `commands` maps are merged
+entry by entry. A profile may also declare a window that isn't in the base
+catalog at all. `setup`, `root` and `layouts` replace their base value; a
+profile may not override `session`, since all profiles of a config share
+one tmux session.
+
+**Vetoing**: mapping a window to `~` (YAML null) is an explicit "this must
+not run". On its own it changes nothing — an unlisted window is already
+down — but it collides loudly if another selected profile includes the
+same window:
 
 ```yaml
 profiles:
-  minimal:
+  no-db:
     windows:
-      dev-kit: ~         # don't start dev-kit under the `minimal` profile
-      scratch: ~
+      backend: {}
+      db: ~              # refuse to run alongside anything that starts db
+```
+
+#### Collisions
+
+Overlap between selected profiles is fine as long as they agree. Two
+profiles including the same window, or setting the same key to the same
+value, merge silently. A genuine disagreement aborts before anything
+starts, naming the setting and both profiles:
+
 ```
+$ mxup up my-project -p backend,staging-backend
+Profile collision: the selected profiles (backend, staging-backend) disagree.
 
-Any layout groups that reference a dropped window are automatically
-pruned — entries are stripped from `panes:` lists, and a group that ends
-up empty is removed from its layout.
+  window 'backend' → command
+    backend          sets "./start-server.sh"
+    staging-backend  sets "./connect-staging.sh"
+
+Select fewer profiles, or make the conflicting values agree.
+```
+
+| Situation | Result |
+|-----------|--------|
+| Several profiles include the same window | fine — included once |
+| One includes a window, another includes it with overrides | fine |
+| Two profiles set different keys of one window | fine — merged |
+| Two profiles set the same key to the same value | fine |
+| Two profiles set the same key to different values | **collision** |
+| One profile vetoes a window another includes | **collision** |
+| Several profiles veto the same window | fine — it stays down |
+
+The same rule covers `setup`, `root` and `layouts` (compared whole) and
+`live_env` (compared per variable). Every conflict in a selection is
+reported at once, not one per run.
 
 **Switching**: if the tmux session is already running under a different
-profile, `mxup up` for a new profile runs `down` first (including the
-graceful-stop dance), then brings the new profile up from a clean slate.
-`mxup status` always shows the currently live profile in its header.
+selection, `mxup up` runs `down` first (including the graceful-stop
+dance), then brings the new selection up from a clean slate. Order doesn't
+matter — `-p a,b` and `-p b,a` are the same live stack, so re-running
+either leaves the panes alone. `mxup status` always shows the currently
+live selection in its header.
+
+#### Profiles in the 0.x format
+
+A config with no [`mxup_version`](#config-format-versions) — anything
+written for mxup `0.3.1` or earlier — keeps the profile semantics it was
+written against. They are **subtractive**, and the differences are worth
+knowing if you're reading the section above with an old config in hand:
+
+| | 0.x format (no `mxup_version`) | 1.x format (`mxup_version: '1'`) |
+|---|---|---|
+| `windows:` | the live set — everything in it runs | a catalog — nothing runs until a profile opts in |
+| A profile listing nothing (`staging: {}`) | runs every window, unchanged | runs nothing |
+| A window no profile mentions | runs | stays down |
+| `name: ~` in a profile | drops that window | vetoes it; collides with a profile that includes it |
+| Profiles selected at once | exactly one | any number, unioned |
+| `default_profile` | one name | a name or a list |
+
+Everything else — `setup`, `root` and `layouts` replacing their base
+value, `live_env` merging per variable, `env` and `commands` merging entry
+by entry, the ban on overriding `session` — behaves the same in both.
+
+So under a 0.x config, `-p` takes a single profile:
+
+```bash
+mxup up my-project -p staging      # fine
+mxup up my-project -p a,b          # rejected: multi-select is a 1.x feature
+```
+
+To move a config to the 1.x format, run `mxup migrations`, list the
+windows each profile should run, then add `mxup_version: '1'`. There's no
+deadline: mxup goes on reading the 0.x format. The one thing that changed
+is that a profile which drops *every* window is now an error ("Config
+declares no windows") rather than an empty session.
 
 ## Commands
 
@@ -422,6 +629,7 @@ graceful-stop dance), then brings the new profile up from a clean slate.
 | `mxup target [name]` | Print targets for every declared window (tab-separated) |
 | `mxup exec -t [name:]<window> "<cmd>"` | Run `<cmd>` in a pane, wait for completion, print output, exit with its status |
 | `mxup [name] <window>:<command>` | Run a window's named `command` in a copy of its environment, streaming output to your shell |
+| `mxup migrations` | Print what each major version changed in the config format, and how to update a config (needs no config file) |
 
 ### Flags
 
@@ -431,7 +639,7 @@ graceful-stop dance), then brings the new profile up from a clean slate.
 | `--dry-run` | Preview changes without applying (for `up`, `restart`, `exec`) |
 | `--lines N` | Output lines to show (for `status` default 15, for `exec` default 50) |
 | `--layout NAME` | Layout to use (for `up`) |
-| `-p`, `--profile NAME` | Profile to use; auto-teardowns a live session running under a different profile (for `up`, `status`, `restart`) |
+| `-p`, `--profile NAME` | Profile(s) to select; repeatable and comma-separated. Auto-teardowns a live session running under a different selection (for `up`, `status`, `restart`) |
 | `-t TARGET` | Pane target (for `exec`); accepts `name:window`, `window`, or `window.pane` |
 | `--timeout N` | Max seconds to wait for the command (for `exec`; exit 124 on timeout) |
 | `--force` | Send the command even if the pane is busy with another process (for `exec`) |
@@ -519,6 +727,12 @@ session is up, and won't disturb the long-running process. (The window's
 
 ## Releasing
 
+**Versioning promise.** The major version is bumped **only** when the config
+format gains a new generation, and every older generation goes on being read
+— so a config that any release accepts is accepted by every later release,
+whatever its major. That's what [`mxup_version`](#config-format-versions)
+selects. Additive config features (new optional keys) go in a minor release.
+
 Releases are automated by `.github/workflows/release.yml`. To cut a new version:
 
 1. Bump `Mxup::VERSION` in `lib/mxup/version.rb`.

data/bin/mxup

@@ -7,4 +7,9 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 require 'mxup'
 
-Mxup::CLI.new.run(ARGV) if __FILE__ == $PROGRAM_NAME
+# No `__FILE__ == $PROGRAM_NAME` guard: this file is only ever an entry point,
+# and RubyGems' generated wrapper `load`s it with $PROGRAM_NAME pointing at the
+# wrapper — so the guard was false for every `gem install` and the CLI silently
+# did nothing. Homebrew's wrapper execs this file directly, which is why the
+# formula kept working and hid it.
+Mxup::CLI.new.run(ARGV)

data/examples/myapp-dev.yml

@@ -2,8 +2,8 @@
 #
 # This is a showcase config — it exercises most mxup features (multiple
 # windows, wait_for probes, per-window env, alternative layouts, and
-# profiles that drop or override windows). Adapt the paths, commands,
-# and env vars to your own project.
+# combinable profiles). Adapt the paths, commands, and env vars to your
+# own project.
 #
 # Place your copy at ~/.config/mxup/myapp-dev.yml, then:
 #   mxup up myapp-dev
@@ -15,13 +15,23 @@
 #   mxup layout myapp-dev compact
 #   mxup up myapp-dev --layout=flat
 #
-# Switch profiles (tears down the current profile first):
-#   mxup up myapp-dev --profile=local     # default, everything on localhost
-#   mxup up myapp-dev --profile=staging   # frontend only, talks to hosted API
+# Select profiles (tears down a different live selection first):
+#   mxup up myapp-dev                          # the default_profile selection
+#   mxup up myapp-dev -p backend,frontend      # everything on localhost
+#   mxup up myapp-dev -p frontend-staging      # frontend only, hosted API
+#   mxup up myapp-dev -p backend -p scratch    # the flag is repeatable too
 #
 # Parameterize via env vars:
 #   DOCKER_PROFILES=core mxup up myapp-dev
 
+# The config format generation this file is written for. Optional: mxup reads
+# every generation up to its own, so a file without this key is read as the
+# pre-1.0 format (major 0) and keeps working. Declaring '1' is what opts this
+# file in to the 1.x format — most visibly, additive profiles (see the bottom
+# of this file). Only the major is read; minor and patch don't matter. Run
+# `mxup migrations` to see what each generation changed.
+mxup_version: '1'
+
 session: myapp-dev
 
 # Base directory for the windows below. Relative values are resolved against
@@ -97,8 +107,8 @@ windows:
     wait_for:
       http: http://localhost:8080/health
       timeout: 60
-    env:
-      API_URL: http://localhost:8080
+    # API_URL is deliberately absent: each profile that selects this window
+    # supplies the backend it should talk to.
     command: pnpm run dev
 
   storybook:
@@ -126,16 +136,41 @@ layouts:
 
   flat: {}
 
+# Selection used when `--profile` is omitted. Without this, `mxup up` would
+# select only the first profile declared below.
+default_profile: [backend, frontend]
+
+# Profiles are additive slices of the `windows:` block above: each one lists
+# the windows it runs, and any number can be selected at once. A window no
+# selected profile lists simply doesn't start. Selecting two profiles that
+# override the same setting differently aborts with an explanation.
 profiles:
-  # Everything runs locally via docker + ./gradlew run (the base config).
-  local: {}
+  # Everything backend, running locally via docker + ./gradlew run.
+  backend:
+    windows:
+      docker: {}
+      api: {}
+      worker: {}
+      scheduler: {}
+
+  frontend:
+    windows:
+      frontend:
+        env:
+          API_URL: http://localhost:8080
+      storybook: {}
 
-  # Staging: skip local backends, point the frontend at the hosted API.
-  staging:
+  # The same frontend windows, pointed at the hosted API. Selecting this
+  # together with `frontend` collides — both set `frontend`'s API_URL, to
+  # different values — so pick one or the other.
+  frontend-staging:
     windows:
-      api: ~
-      worker: ~
-      scheduler: ~
       frontend:
         env:
           API_URL: https://api.staging.example.com
+      storybook: {}
+
+  # Add-on slice: composes with any of the above.
+  scratch:
+    windows:
+      scratch: {}

data/lib/mxup/cli.rb

@@ -6,7 +6,7 @@ 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 watch].freeze
+    COMMANDS = %w[up status down restart layout target exec watch migrations].freeze
 
     def run(argv)
       args, options = parse(argv.dup)
@@ -28,7 +28,7 @@ module Mxup
       options = {
         dry_run: false, config: nil, lines: nil, layout: nil,
         target: nil,    timeout: nil, force: false, quiet: false,
-        profile: nil
+        profiles: []
       }
 
       parser = OptionParser.new do |opts|
@@ -38,7 +38,8 @@ module Mxup
         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 }
+                'Profile(s) to use; repeatable or comma-separated ' \
+                '(for up/status/restart/layout)')                     { |p| options[:profiles] << 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 }
@@ -69,6 +70,8 @@ module Mxup
       when 'layout'                     then run_layout(args, options)
       when 'exec'                       then run_exec(args, options)
       when 'watch'                      then run_watch(args, options)
+      # Needs no config — it's what you run when your config won't load.
+      when 'migrations'                 then Migrations.render
       else
         abort "Unknown command: #{command}. Use: #{COMMANDS.join(', ')}"
       end
@@ -126,7 +129,7 @@ module Mxup
     # declares any `live_env`. Useful in the foreground for debugging.
     def run_watch(args, options)
       name   = args.shift
-      config = load_config(options[:config], name, options[:profile])
+      config = load_config(options[:config], name, options[:profiles])
       if config.live_env.empty?
         abort "Config has no live_env declared; nothing to watch."
       end
@@ -176,17 +179,17 @@ module Mxup
     end
 
     def build_runner(options, name)
-      config = load_config(options[:config], name, options[:profile])
+      config = load_config(options[:config], name, options[:profiles])
       Runner.new(config, dry_run: options[:dry_run], layout: options[:layout])
     end
 
-    def load_config(explicit_path, name, profile = nil)
+    def load_config(explicit_path, name, profiles = [])
       path = resolve_config(explicit_path, name)
       unless path
         abort "Config not found. Provide -f path, place config in #{CONFIG_DIR}/, " \
               "or in a local ./#{LOCAL_CONFIG_DIR}/ directory."
       end
-      Config.new(path, profile: profile)
+      Config.new(path, profiles: profiles)
     rescue ArgumentError => e
       abort e.message
     end