mxup 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2f166f4e87656548399fe98f82650123ef4fe98091cef4c3e3cc1d123ea8506
-  data.tar.gz: 5aea8148ab5bd0cbee4e3635a0df5a3e0513c8dfc3e110408db674c795552b84
+  metadata.gz: b091e5654c4a748617259e0ea10d9e028d96febfe91d808da4fa4bbc8c2fbe3b
+  data.tar.gz: d63f016660507556cde2cc66137bab6eff7a3e02ab14a39b5ec9d1209db5a07a
 SHA512:
-  metadata.gz: 10a37a6fad2a6409ceabf94f7bd0c63d36645a7a402d609b4207255753cefeffeee162fefcc0aee8d01777ac7535fba71842b5ff9298a43b48b5cf1c6393f5de
-  data.tar.gz: 4463a0a269f5cd7fa1ffecc85e30f05822420afe8796df195ffadc8fdab05191bb03f8bd590d99b1c01f60f1a4a199184535badb2e3ec410fe701bbcc6ce0c08
+  metadata.gz: 48326d3972367778ad604835d4f8d5c9417256bbc7266e9f8906ccec1d55eca23ad6424515208dc2a4dd9573912201f0760a410323ca74fc55571161bc281dbc
+  data.tar.gz: 5dcabc72786c9e48882a944fe583325efbdfb3cfce23ebad09bac7b09e479797288a959dcf8f9434bbc619953352eb0688ebd86b3bb409ca666bf57b72c2870e

data/README.md

@@ -53,11 +53,35 @@ mxup down myapp-dev
 
 ## Config format
 
-Configs live in `~/.config/mxup/<name>.yml` or can be passed via `-f path`.
+Configs live in `~/.config/mxup/<name>.yml`, in a project-local `./.mxup/<name>.yml`, or can be passed via `-f path`.
+
+### Where mxup looks for a config
+
+In order, `mxup` tries:
+
+1. `-f <path>` if supplied.
+2. `./.mxup/<name>.yml` — project-local, takes precedence over the global dir.
+3. `~/.config/mxup/<name>.yml`.
+4. `./mxup.yml` — bare config in the current directory.
+5. The sole `*.yml` in `./.mxup/`, if exactly one is present.
+6. The sole `*.yml` in `~/.config/mxup/`, if exactly one is present.
+
+A project-local `.mxup/` directory is handy for committing per-repo dev sessions alongside the code:
+
+```bash
+mkdir .mxup
+cp examples/myapp-dev.yml .mxup/dev.yml
+mxup up dev      # picks up ./.mxup/dev.yml
+```
 
 ```yaml
 session: my-project
 
+# Optional. Relative paths are resolved against the config file's directory
+# (or, when the config lives in `.mxup/`, against the project root that
+# contains it — so a checked-in `.mxup/dev.yml` can just say `root: .`).
+root: ~/projects/my-app
+
 # Shell snippet run in every window before the command
 setup: |
   direnv allow . 2>/dev/null
@@ -65,22 +89,22 @@ setup: |
 
 windows:
   database:
-    root: ~/projects/my-app
+    root: .                        # = ~/projects/my-app
     command: docker compose up postgres redis
 
   backend:
-    root: ~/projects/my-app/backend
+    root: backend                  # = ~/projects/my-app/backend
     wait_for: localhost:5432
     env:
       DATABASE_URL: postgres://localhost/myapp_dev
     command: ./start-server.sh
 
   frontend:
-    root: ~/projects/my-app/frontend
+    root: frontend
     command: npm run dev
 
   shell:
-    root: ~/projects/my-app
+    root: .
 ```
 
 ### Fields
@@ -89,16 +113,19 @@ windows:
 |-------|----------|-------------|
 | `session` | yes | tmux session name |
 | `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)) |
 | `windows` | yes | Ordered map of window definitions |
 
 Per window:
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `root` | yes | Working directory (supports `~`) |
+| `root` | yes | Working directory. `~` and absolute paths are kept as-is; relative paths resolve against the top-level `root` (or CWD if unset). Supports `$VAR` / `${VAR}` env-var expansion (an unset variable is an error). |
 | `command` | no | Command to run. Omit for an interactive shell. |
 | `env` | no | Map of environment variables to export |
 | `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)) |
 
 ### Wait-for checks
 
@@ -160,6 +187,107 @@ Then override at invocation:
 APP_ENV=production mxup up my-project
 ```
 
+### Live env (command-backed env vars with auto-restart)
+
+For env vars whose value comes from a command you re-run periodically (auth
+tokens, short-lived credentials), declare them under `live_env`. Each value
+is a shell command whose stdout becomes the variable's value:
+
+```yaml
+live_env:
+  GRAZIE_TOKEN: cat ~/.grazie-token
+  AWS_SESSION_TOKEN: aws configure export-credentials --format env | sed -n 's/.*AWS_SESSION_TOKEN=//p'
+
+windows:
+  api:
+    root: api
+    live_env: [GRAZIE_TOKEN]
+    command: ./gradlew run
+
+  worker:
+    root: worker
+    live_env: [GRAZIE_TOKEN, AWS_SESSION_TOKEN]
+    command: ./gradlew run
+```
+
+The window's launcher exports each variable from its command's output
+(`export GRAZIE_TOKEN="$(cat ~/.grazie-token)"`) before running its own
+command, so the value is always read fresh on (re)start. Commands run in
+the config's base directory, so relative paths inside them resolve the same
+way as `root` — regardless of an individual window's `root`.
+
+When `mxup up` finds a `live_env` block in the config, it spawns a
+background watcher process for the session. The watcher re-evaluates each
+command on an interval; whenever a command's output changes, it restarts
+every window whose `live_env` list references it. So `echo new >
+~/.grazie-token` is enough to bounce `api` and `worker` with the new value
+— no manual restart. A command that exits non-zero is treated as "no value
+yet" and never triggers a restart on its own.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `live_env` (top-level) | no | Map of env var name → shell command. The command's stdout is the value; it runs in the config's base directory. |
+| `live_env` (per-window) | no | List of names from the top-level pool that this window depends on. Unknown names are an error. |
+
+The watcher is stopped automatically by `mxup down`. Its PID, log, and
+last-restart state live under `~/.local/share/mxup/<session>/`. `mxup
+status` shows the watcher's PID and the most recent restart it issued.
+
+### Required env vars
+
+Some values can't live in the config because they're secret or
+machine-specific (API keys, DB passwords). Declare them under `required_env`
+and `mxup up` will refuse to start until they're supplied:
+
+```yaml
+required_env:
+  DATABASE_PASSWORD:                          # list/name-only form
+  STRIPE_SECRET_KEY: Test key from the dashboard   # map form: name => description
+
+windows:
+  api:
+    root: api
+    command: ./gradlew run
+```
+
+Values are read from a dotenv-style file named after the config, sitting
+right next to it — `~/.config/mxup/myapp-dev.yml` → `~/.config/mxup/myapp-dev.env`
+(a project-local `.mxup/dev.yml` → `.mxup/dev.env`).
+
+On `mxup up`, mxup checks that each required var has a non-empty value in
+that file. If any are missing, it **creates or extends** the file with a
+blank `NAME=` line for each (descriptions become `#` comments), tells you
+what's missing, and aborts:
+
+```
+$ mxup up myapp-dev
+Missing required environment variable(s):
+  DATABASE_PASSWORD
+  STRIPE_SECRET_KEY — Test key from the dashboard
+Fill in the values in /Users/me/.config/mxup/myapp-dev.env, then re-run `mxup up`.
+```
+
+```ini
+# myapp-dev.env  (generated)
+DATABASE_PASSWORD=
+
+# Test key from the dashboard
+STRIPE_SECRET_KEY=
+```
+
+Fill in the blanks and re-run. Existing values are never overwritten, so the
+file is safe to keep around. Each window's launcher sources it (`set -a; . file;
+set +a`) before `setup` and `command`, so every window inherits the values.
+
+`--dry-run` reports what's missing but writes nothing and doesn't abort.
+
+> **Keep it out of git.** The `.env` file holds secrets — add `*.env` (or
+> `.mxup/*.env` for project-local configs) to your `.gitignore`.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `required_env` | no | List of names (`[A, B]`) or a map of `name => description`. Gates `mxup up`; values come from the adjacent `<config-name>.env` file. |
+
 ### Layouts
 
 Define multiple named layouts to control how windows are grouped as tmux panes:
@@ -293,6 +421,7 @@ graceful-stop dance), then brings the new profile up from a clean slate.
 | `mxup target [name:]<window>` | Print the tmux target (`session:window.pane`) for a logical window |
 | `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 |
 
 ### Flags
 
@@ -345,6 +474,39 @@ send to a pane that's currently running a non-shell process — pass `--force`
 to override. Use `--timeout N` to avoid hanging indefinitely on a runaway
 command (exits 124 on timeout).
 
+### Named commands (`mxup <config> <window>:<name>`)
+
+A window can declare named one-off commands under `commands`. These are handy
+for build/test/lint chores that share a window's working directory and
+environment but shouldn't be baked into its long-running `command`:
+
+```yaml
+windows:
+  air-backend:
+    root: backend
+    command: ./start-server.sh
+    env:
+      APP_ENV: dev
+    commands:
+      rebuild: ./gradlew build
+      test: ./gradlew test
+```
+
+Run one with:
+
+```bash
+mxup air-dev air-backend:rebuild      # config name is optional if it resolves implicitly
+mxup air-backend:test
+```
+
+Unlike `mxup exec`, a named command does **not** run inside the live tmux
+pane. It executes in a *copy* of that window's environment — the same `root`,
+`setup` snippet, `live_env`, and `env` — as a local subprocess, streaming its
+output straight to the calling shell and exiting with the command's own return
+code. Because it never touches the running pane, it works whether or not the
+session is up, and won't disturb the long-running process. (The window's
+`wait_for` readiness gate is skipped; it guards the main command, not chores.)
+
 ## Reconciliation
 
 `mxup up` compares the declared config against the running tmux session:

data/examples/myapp-dev.yml

@@ -24,28 +24,59 @@
 
 session: myapp-dev
 
+# Base directory for the windows below. Relative values are resolved against
+# the directory containing this file, so dropping this config into
+# `.mxup/dev.yml` inside the repo would let you write `root: .` instead.
+root: ~/code/myapp
+
 setup: |
   # Runs in every window before its command. Replace with whatever your
   # project needs (direnv, nvm, asdf, sourcing a .env, etc.).
   eval "$(direnv export zsh)"
 
+# Env vars whose values come from a command and get rotated periodically.
+# Each value is a shell command (run in this file's directory) whose stdout
+# becomes the variable. mxup launches a background watcher; when a command's
+# output changes, every window that lists the var in its `live_env:` block is
+# auto-restarted.
+live_env:
+  GRAZIE_TOKEN: cat ~/.grazie-token
+
+# Env vars that must be filled in before `mxup up` will start anything.
+# On `up`, mxup checks `myapp-dev.env` (next to this file); if any of these
+# are unset it scaffolds that file with a blank line per var (the descriptions
+# below become comments), then aborts so you can fill them in. Every window
+# sources the file, so the values are available everywhere. Git-ignore *.env.
+required_env:
+  STRIPE_SECRET_KEY: Test-mode secret key from the Stripe dashboard
+  DATABASE_PASSWORD: Password for the local postgres role
+
 windows:
   docker:
-    root: ~/code/myapp-infra
+    root: ../myapp-infra              # = ~/code/myapp-infra
     command: docker compose --profile ${DOCKER_PROFILES:-core} up
 
   api:
-    root: ~/code/myapp/api
+    root: api                         # = ~/code/myapp/api
     wait_for:
       tcp: localhost:5432
       timeout: 120
+    live_env: [GRAZIE_TOKEN]          # re-exported via `cat ~/.grazie-token`; changed output restarts this window
     env:
       APP_ENV: development
       DATABASE_URL: postgres://localhost/myapp_dev
     command: ./gradlew run
+    # Named one-off chores that share this window's dir + env. Run them without
+    # disturbing the server: `mxup myapp-dev api:rebuild` (streams to your
+    # shell, exits with the command's own status; works even if the session is
+    # down). The window's wait_for gate is skipped for these.
+    commands:
+      rebuild: ./gradlew build
+      test: ./gradlew test
+      migrate: ./gradlew flywayMigrate
 
   worker:
-    root: ~/code/myapp/worker
+    root: worker
     wait_for: localhost:6379          # shorthand for a tcp check (redis)
     env:
       APP_ENV: development
@@ -54,7 +85,7 @@ windows:
     command: ./gradlew run
 
   scheduler:
-    root: ~/code/myapp/scheduler
+    root: scheduler
     wait_for: localhost:5432
     env:
       APP_ENV: development
@@ -62,7 +93,7 @@ windows:
     command: ./gradlew run
 
   frontend:
-    root: ~/code/myapp/frontend
+    root: frontend
     wait_for:
       http: http://localhost:8080/health
       timeout: 60
@@ -71,13 +102,13 @@ windows:
     command: pnpm run dev
 
   storybook:
-    root: ~/code/myapp/frontend
+    root: frontend
     command: pnpm run storybook
 
   scratch:
     # No `command` -> plain interactive shell, handy for ad-hoc work
     # (e.g. `mxup exec -t myapp-dev:scratch "./gradlew test"`).
-    root: ~/code/myapp
+    root: .                           # = ~/code/myapp
 
 layouts:
   full:

data/lib/mxup/cli.rb

@@ -6,11 +6,19 @@ 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
+    COMMANDS = %w[up status down restart layout target exec watch].freeze
 
     def run(argv)
       args, options = parse(argv.dup)
       command       = extract_command(args)
+
+      # `mxup [config] <window>:<command>` — run a window's named command.
+      # Only in the default (no explicit command keyword) path; `restart`/
+      # `target` etc. keep their own `session:windows` colon syntax.
+      if command == 'up' && (spec = window_command_spec(args))
+        return run_window_command(spec, options)
+      end
+
       dispatch(command, args, options)
     end
 
@@ -60,11 +68,31 @@ module Mxup
       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)
+      when 'watch'                      then run_watch(args, options)
       else
         abort "Unknown command: #{command}. Use: #{COMMANDS.join(', ')}"
       end
     end
 
+    # Detect the `mxup [config] WINDOW:COMMAND` form. Returns
+    # [config_name, window, command_name] or nil. The colon-bearing positional
+    # is the window:command; any other positional is the config name.
+    def window_command_spec(args)
+      idx = args.index { |a| a.include?(':') }
+      return nil unless idx
+
+      window, command_name = args[idx].split(':', 2)
+      return nil if window.empty? || command_name.nil? || command_name.empty?
+
+      config_name = args.each_index.reject { |i| i == idx }.map { |i| args[i] }.first
+      [config_name, window, command_name]
+    end
+
+    def run_window_command(spec, options)
+      config_name, window_name, command_name = spec
+      build_runner(options, config_name).run_command(window_name, command_name)
+    end
+
     def run_basic(command, args, options)
       name   = args.shift
       runner = build_runner(options, name)
@@ -93,6 +121,18 @@ module Mxup
       target_layout ? runner.switch_layout(target_layout) : runner.show_layouts
     end
 
+    # `mxup watch [name]` — runs the live_env command watcher in the foreground.
+    # Mostly used internally: `Runner#up` spawns this detached when the config
+    # 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])
+      if config.live_env.empty?
+        abort "Config has no live_env declared; nothing to watch."
+      end
+      exit Watcher.new(config).run
+    end
+
     def run_exec(args, options)
       target = options[:target] || args.shift
       abort 'Usage: mxup exec -t [name:]WINDOW "command"' if target.nil? || target.empty?
@@ -124,12 +164,17 @@ module Mxup
       end
 
       # Ambiguous: is `spec` a config name or a window name?
-      looks_like_config = File.exist?(File.join(CONFIG_DIR, "#{spec}.yml")) ||
+      looks_like_config = config_exists?(spec) ||
                           (options[:config] && spec !~ /,/)
       return [spec, args] if looks_like_config
       [nil, [spec] + args]
     end
 
+    def config_exists?(name)
+      File.exist?(File.join(local_config_dir, "#{name}.yml")) ||
+        File.exist?(File.join(CONFIG_DIR, "#{name}.yml"))
+    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])
@@ -137,7 +182,10 @@ module Mxup
 
     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
+      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)
     rescue ArgumentError => e
       abort e.message
@@ -145,26 +193,40 @@ module Mxup
 
     # Config resolution order:
     #   1. explicit -f path
-    #   2. ~/.config/mxup/<name>.yml
-    #   3. ./mxup.yml
-    #   4. sole *.yml in ~/.config/mxup/
+    #   2. ./.mxup/<name>.yml          (project-local, takes precedence)
+    #   3. ~/.config/mxup/<name>.yml
+    #   4. ./mxup.yml
+    #   5. sole *.yml in ./.mxup/
+    #   6. 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)
+        local_named = File.join(local_config_dir, "#{name}.yml")
+        return local_named if File.exist?(local_named)
+
+        global_named = File.join(CONFIG_DIR, "#{name}.yml")
+        return global_named if File.exist?(global_named)
       end
 
-      local = File.join(Dir.pwd, 'mxup.yml')
-      return local if File.exist?(local)
+      bare = File.join(Dir.pwd, 'mxup.yml')
+      return bare if File.exist?(bare)
 
-      if Dir.exist?(CONFIG_DIR)
-        configs = Dir.glob(File.join(CONFIG_DIR, '*.yml'))
-        return configs.first if configs.size == 1
-      end
+      sole = sole_config_in(local_config_dir) || sole_config_in(CONFIG_DIR)
+      return sole if sole
 
       nil
     end
+
+    def local_config_dir
+      File.join(Dir.pwd, LOCAL_CONFIG_DIR)
+    end
+
+    def sole_config_in(dir)
+      return nil unless Dir.exist?(dir)
+
+      configs = Dir.glob(File.join(dir, '*.yml'))
+      configs.size == 1 ? configs.first : nil
+    end
   end
 end