diff options
Diffstat (limited to 'tmuxrdr/README.md')
| -rw-r--r-- | tmuxrdr/README.md | 125 |
1 files changed, 83 insertions, 42 deletions
diff --git a/tmuxrdr/README.md b/tmuxrdr/README.md index b152b39e..4eb46d06 100644 --- a/tmuxrdr/README.md +++ b/tmuxrdr/README.md @@ -7,47 +7,78 @@ agents: tmux's model -- a server owning panes, clients attaching -- plus an agent-aware sidebar. Its keys are its own. tmuxrdr is herdr with tmux's keys and tmux's behaviour wherever herdr can be made to have them: tmux 3.7c's default prefix table, with this machine's `dot/config/tmux.conf` and -`~/.tmux.conf.local` on top. +`~/.tmux.conf.local` on top. It is a separate binary, `tmuxrdr`, with its own +config, sessions and plugins, so it runs beside stock herdr without touching +it. -Everything tmuxrdr adds is in this directory. The rest of the checkout is -herdr, untouched, on a herdr release tag. +Everything tmuxrdr adds is in this directory, plus one small patch to herdr's +code. The rest of the checkout is herdr, on a herdr release tag. | Path | What | |---|---| -| `config/config.toml` | herdr config: tmux's bindings on herdr's actions, each commented with the tmux line it mirrors | -| `plugin/` | the tmux-mode herdr plugin: the bindings herdr has no action for -- break-pane, swap/rotate by pane order, marks, last session, select/move-window, paste-buffer, display-message, select-layout -E, kill with y/n, the `:` prompt, clock, messages, automatic-rename | -| `scripts/install` | puts this machine on the config and plugin | -| `scripts/test-e2e` | presses every binding in a real herdr client and checks the result | +| `config/config.toml` | tmuxrdr's config: tmux's bindings on herdr's actions, each commented with the tmux line it mirrors | +| `plugin/` | the tmux-mode plugin: the bindings herdr has no action for -- break-pane, swap/rotate by pane order, marks, last session, select/move-window, paste-buffer, display-message, select-layout -E, kill with y/n, the `:` prompt, clock, messages, automatic-rename | +| `scripts/build` | builds the checkout and installs it as `~/.local/bin/tmuxrdr` | +| `scripts/install` | points tmuxrdr at the config and plugin | +| `scripts/test-e2e` | presses every binding in a real tmuxrdr client and checks the result | | `scripts/sync-upstream` | rebases tmuxrdr onto a newer herdr release | -| `ROADMAP.md` | what only a patch to herdr's code can do, with the patch for each | +| `ROADMAP.md` | what only further patches to herdr's code can do, with the patch for each | ## Status - Based on herdr **v0.9.3**, the release Homebrew ships. +- One code patch: tmuxrdr's own directories (`src/config/io.rs`, below). - Of tmux's 88 default prefix bindings, **67 work** (some approximately -- ROADMAP.md, "Coverage"), **5 are moot** in herdr, **16 need code**. - `scripts/test-e2e`: 66 checks, all passing on v0.9.3. -- **No herdr code is patched yet.** The config and plugin run on stock herdr; - the first code patches are in ROADMAP.md, smallest first. + `scripts/test-e2e`: 67 checks, all passing. + +## tmuxrdr and herdr side by side + +| | `herdr` (Homebrew) | `tmuxrdr` (this checkout) | +|---|---|---| +| Binary | `/opt/homebrew/bin/herdr` | `~/.local/bin/tmuxrdr` | +| Config | `~/.config/herdr/config.toml`, herdr's own | `~/.config/tmuxrdr/config.toml` -> `config/config.toml` | +| Plugins | its own registry (none here) | its own registry: `tmuxrdr.tmux-mode` | +| Sessions, sockets, logs | `~/.config/herdr/` | `~/.config/tmuxrdr/` | +| State | `~/.local/state/herdr/` | `~/.local/state/tmuxrdr/` | + +The patch: herdr derives every one of those directories from +`app_dir_name()` in `src/config/io.rs`, and tmuxrdr's returns `tmuxrdr` +instead of `herdr`. Debug builds keep `herdr-dev`, which herdr's tests expect. +The binary is cargo's `herdr`, installed under the name `tmuxrdr`; it starts +its server from its own path, so nothing else needs renaming. + +Run either, in any terminal: `herdr`, `tmuxrdr`, `tmuxrdr --session work`. + +What they still share: the environment variable names (`HERDR_ENV`, +`HERDR_SOCKET_PATH`, ...). Inside a tmuxrdr pane, `herdr` CLI commands -- and +the agent integrations, which use them -- reach that tmuxrdr server, which is +what they should do. Starting one's interface inside the other's pane is +refused as a nested launch; `env -u HERDR_ENV -u HERDR_SOCKET_PATH herdr` +gets past that when wanted. ## Install ```sh +tmuxrdr/scripts/build # Building, below, for the toolchains tmuxrdr/scripts/install # dry run: what it would do tmuxrdr/scripts/install yes ``` -It links `~/.config/herdr/config.toml` to `config/config.toml`, keeping a real -file already there as `config.toml.pre-tmuxrdr`, and +`install` links `~/.config/tmuxrdr/config.toml` to `config/config.toml`, +keeping a real file already there as `config.toml.pre-tmuxrdr`, and `~/.local/share/tmuxrdr/plugin` to `plugin/`, which it registers with -`herdr plugin link`. herdr saves its settings in place, so changes made from -its settings screen land in `config/config.toml` too -- `git diff` shows them. -Then, in a running herdr: `prefix+r`. +`tmuxrdr plugin link`. It refuses any binary that does not read +`~/.config/tmuxrdr/config.toml`, so stock herdr cannot pick tmuxrdr's setup up +by mistake. herdr saves its settings in place, so changes made from +tmuxrdr's settings screen land in `config/config.toml` -- `git diff` shows +them. In a running tmuxrdr: `prefix+r`. Needs `jq`. Run it again after moving the checkout. -To leave: `herdr plugin unlink tmuxrdr.tmux-mode`, remove the two links, and -move `config.toml.pre-tmuxrdr` back if you want herdr's old config. +To leave: `tmuxrdr plugin unlink tmuxrdr.tmux-mode`, then remove +`~/.local/bin/tmuxrdr`, `~/.config/tmuxrdr`, `~/.local/state/tmuxrdr` and +`~/.local/share/tmuxrdr`. Stock herdr is unaffected either way. ## Test @@ -55,11 +86,11 @@ move `config.toml.pre-tmuxrdr` back if you want herdr's old config. tmuxrdr/scripts/test-e2e ``` -About a minute. It runs a herdr client inside a throwaway tmux server (its own -socket, its prefix off), on a throwaway herdr session and a copy of the -config, presses each binding, checks the effect through the herdr CLI, and -removes everything after. Your sessions and config are not touched. `HERDR=` -tests another binary -- a tmuxrdr build, once there is one. +About a minute. It checks the config, runs a tmuxrdr client inside a +throwaway tmux server (its own socket, its prefix off) on a throwaway session +and a copy of the config, presses each binding, checks the effect through the +CLI, and removes everything after. Your sessions and config are not touched. +`HERDR=target/release/herdr` tests a build before installing it. ## Maintaining @@ -69,11 +100,11 @@ possible. What keeps it that way: - **One branch, `tmuxrdr`:** a herdr release tag with tmuxrdr's commits on top. Remote `upstream` is herdr, fetch-only -- its push URL is disabled. - **Fork content stays in `tmuxrdr/`.** Upstream never touches this - directory, so these commits never conflict. Do not edit upstream files for + directory, so those commits never conflict. Do not edit upstream files for anything that can live here -- not even the top-level README. -- **Code patches are one commit each, and small.** Put the logic in new - files; keep the lines changed in upstream's files to the hooks that call - it. ROADMAP.md says where each patch touches. +- **Code patches are one commit each, and small.** The directory patch is a + single line. Put larger logic in new files and keep the lines changed in + upstream's to the hooks that call it; ROADMAP.md says where each touches. - **rerere is on** in this checkout (`git config rerere.enabled true`), so a conflict resolved once is resolved by itself next time. @@ -81,28 +112,38 @@ To move to a new herdr release: ```sh tmuxrdr/scripts/sync-upstream # or: sync-upstream v0.9.4 +tmuxrdr/scripts/build tmuxrdr/scripts/test-e2e ``` `sync-upstream` keeps the branch as it was under `tmuxrdr-on-<old tag>`; if something is wrong, `git switch -C tmuxrdr tmuxrdr-on-<old tag>` puts it back. -Test against the new release: upgrade the herdr on PATH (`brew upgrade -herdr`) while there are no code patches, or build this checkout once there -are. +`brew upgrade herdr` moves stock herdr to the same release. ## Building -Not needed until the first code patch: until then, tmuxrdr runs on stock -herdr. When it is: - -- herdr pins Rust 1.96.1 in `rust-toolchain.toml`. Install rustup with - `--no-modify-path` -- dot's shell profiles are links into a repo -- and put - `. "$HOME/.cargo/env"` in `~/.localenv`. -- Fetch crates through Socket Firewall: `sfw cargo build --release`. -- Client and server are one binary and check each other's protocol version. - Stop the server (`herdr server stop`) before switching, then install the - build as `~/.local/bin/herdr`, which comes before Homebrew's on PATH here. - Keep it named `herdr`: agent integrations call that name. -- Never `herdr update` a tmuxrdr build -- it installs stock herdr over it. +`scripts/build` finds its toolchains without PATH or shell-profile changes -- +dot's shell profiles are links into a repo: + +- **Rust**, the version `rust-toolchain.toml` pins (1.96.1), through rustup: + Homebrew's keg-only `rustup` (`brew install rustup`), used from + `/opt/homebrew/opt/rustup/bin` when no cargo is on PATH. +- **Zig, exactly 0.16.0**, which herdr's vendored libghostty-vt requires; + Homebrew's is newer. `$ZIG`, else `~/.local/opt/zig-0.16.0/zig`: the + ziglang.org tarball, checked against its minisign signature (key + `RWSGOq2NVecA2UPNdBUZykf1CCb147pkmdtYxgb3Ti+JO/wCYvhbAb/U`, as published on + ziglang.org/download). +- **sfw** (Socket Firewall): crates are fetched through it. Zig's packages are + fetched first, by Zig itself, each checked against the hash in + `build.zig.zon` -- sfw's proxy breaks Zig's downloads. + +It installs `target/release/herdr` as `~/.local/bin/tmuxrdr` by a rename, so a +running tmuxrdr server keeps the old binary until it restarts +(`tmuxrdr server stop` ends it and its panes). `[update] version_check` is off +in the config: herdr's update would download stock herdr over tmuxrdr. Never +run `tmuxrdr update`; new releases come through `sync-upstream`. + +The build prints herdr's notice for external contributors; tmuxrdr does not +contribute upstream, so it does not apply. License: Apache-2.0, like herdr (`LICENSE` at the top of the checkout). |