muxr 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e431ecab7ea6e49cf31e2865c3c870603847e422c9c1e5dfc8b86ff413b95f5
+  data.tar.gz: e6db50aba85439befa78b6c89ec5dcd09f6d3cfa66195e0d552f403c229b7932
+SHA512:
+  metadata.gz: 2f0513da3cfba34c6efbc73c398934ada15ccb00b29958d4b5bf70b397cb7110819da8915acbbd13db4a8dd9d922551e3bf70d09c2dbf6247e2ebea598d2f9b5
+  data.tar.gz: 9f0dcefe6bd25d5173044d88b81fc4efac0872b5961f010ed33e370335f341f2ee2ec98b5d0ed1ee50036a3675ba96ad3b33b50d95397ef32c6726eaabe0a29a

data/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to muxr are documented here. The format roughly follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions
+follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-11
+
+Initial release.
+
+### Added
+- Client/server architecture over a Unix domain socket at
+  `~/.muxr/sockets/<name>.sock`. `Ctrl-a d` detaches the client; the
+  server (and every shell it owns) keeps running, so reattaching gives
+  back the exact same panes with full history.
+- Ctrl-a prefix keybindings: `c` (new pane), `n`/`p` (next/prev),
+  `a` (toggle last pane), `1`..`9` (jump to pane by label), `k` (close),
+  `Tab` (cycle layout), `Enter` (promote to master), `~` (toggle drawer),
+  `d` (detach), `q` (kill session with `y/n` confirm), `:` (command
+  prompt), `?` (help), `C-a` (send literal `C-a`).
+- Three layouts (`tall`, `grid`, `monocle`) implemented as pure functions
+  of pane count and screen area.
+- Quake-style drawer overlay with a persistent shell PTY that survives
+  hide/toggle; `drawer reset` is the only way to kill it.
+- Per-pane scrollback (bounded 5000-row ring) with `Ctrl-a [` copy-mode
+  and vi-style navigation (`j`/`k`/`d`/`u`/`f`/`b`/Space/`g`/`G`).
+- Visual selection inside scrollback: `v` for character, `C-v` for
+  block; `y`/Enter yanks into an internal buffer and pipes to `pbcopy`.
+  `Ctrl-a ]` pastes the yank buffer into the focused pane.
+- Command prompt (`Ctrl-a :`): `layout`, `drawer`, `save`, `restore`,
+  `sessions`/`ls`, `new`, `close`, `next`, `prev`, `master`, `detach`,
+  `quit`.
+- CLI flags: `--list`, `--version`, `--help`, `-s <name>`.
+- Session persistence to `~/.muxr/sessions/<name>.json` as cold-storage
+  fallback (the live session lives in the running server between
+  detaches).
+- Real VT100 emulator per pane: cursor movement, SGR (16-color,
+  256-color, truecolor, underline subparameters and underline color),
+  erase/insert/delete, autowrap, scroll regions, UTF-8 across PTY read
+  boundaries.
+- Renderer that composes one frame and diff-emits ANSI to STDOUT.
+
+[Unreleased]: https://github.com/roelbondoc/muxr/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/roelbondoc/muxr/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roel Bondoc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,211 @@
+# muxr
+
+A keyboard-driven terminal multiplexer in pure Ruby. `muxr` (Ruby + Unix)
+combines the familiar keybindings of **GNU Screen**, the automatic tiling
+of **xmonad**, and a **Quake-style drop-down drawer**. Panes are treated
+like tiling-window-manager clients — you never resize them by hand;
+the active layout decides geometry.
+
+```
+┌ #1 ★ (tall) ──────────────┬ #2 ──────────────────────────┐
+│ master pane               │ stacked slave pane           │
+│                           │                              │
+│                           ├──────────────────────────────┤
+│                           │ stacked slave pane           │
+│                           │                              │
+└───────────────────────────┴──────────────────────────────┘
+┌ Drawer ─────────────────────────────────────────────────┐
+│ persistent overlay shell, opens from the bottom         │
+└─────────────────────────────────────────────────────────┘
+ [default] panes:3 layout:tall focused:#1 drawer:shown     muxr ^a ?
+```
+
+## Install / run
+
+```bash
+git clone https://github.com/roelbondoc/muxr
+cd muxr
+bin/muxr                 # attach the "default" session (auto-spawn if needed)
+bin/muxr work            # attach (or start) a named session
+bin/muxr --list          # list saved sessions and exit
+bin/muxr --help
+```
+
+Requires **Ruby ≥ 3.4**. No runtime gems — just `PTY`, `IO.console`, `JSON`,
+`Socket`, and `FileUtils` from stdlib.
+
+`bin/muxr` is the client. The first invocation for a session daemonizes a
+server in the background; subsequent invocations attach to it over a Unix
+socket. `Ctrl-a d` detaches the client and leaves the server (and every
+shell it owns) running, so reattaching gives you back the exact same panes
+with their full history.
+
+## Keybindings (Ctrl-a prefix)
+
+| Keys           | Action                                                  |
+|----------------|---------------------------------------------------------|
+| `C-a c`        | new pane                                                |
+| `C-a n` / `p`  | focus next / previous pane                              |
+| `C-a a`        | toggle last (previously focused) pane                   |
+| `C-a 1` … `9`  | jump to pane by its label                               |
+| `C-a k`        | close focused pane (or hide drawer)                     |
+| `C-a Tab`      | cycle layout (`tall` → `grid` → `monocle`)              |
+| `C-a Enter`    | promote focused pane to master                          |
+| `C-a ~`        | toggle drawer                                           |
+| `C-a [`        | enter scrollback / copy-mode                            |
+| `C-a ]`        | paste internal yank buffer into focused pane            |
+| `C-a d`        | detach (server keeps running)                           |
+| `C-a q`        | kill session (asks `kill session? (y/n)`)               |
+| `C-a :`        | command prompt                                          |
+| `C-a ?`        | help                                                    |
+| `C-a C-a`      | send literal `C-a` to focused pane                      |
+
+### Scrollback and copy-mode
+
+Each pane keeps a bounded (5000-row) scrollback ring. `C-a [` enters
+scrollback with vi-style navigation; the status bar shows a key hint and
+the pane title gains `[scrollback N/M]`.
+
+| Keys                    | Action                              |
+|-------------------------|-------------------------------------|
+| `j` / `k`               | scroll one line                     |
+| `d` / `u` (or `C-d`/`C-u`) | half page                        |
+| `f` / `b` / Space (or `C-f`/`C-b`) | full page                |
+| `g` / `G`               | top / bottom                        |
+| `q` / `Esc` / `C-c`     | exit back to live view              |
+
+Press `v` inside scrollback to enter a movable-cursor selection mode
+(`h j k l`, `0`/`$`, `g`/`G`, `C-d`/`C-u`, `C-f`/`C-b`, Space). Press `v`
+again to anchor a character selection or `C-v` to anchor a block
+(rectangular) selection — toggling between the two preserves the anchor.
+`y` or Enter yanks the selection into an internal buffer and pipes it to
+`pbcopy` in the background (silent no-op when `pbcopy` is unavailable).
+`C-a ]` writes the yank buffer back into the focused pane.
+
+## Commands (typed after `C-a :`)
+
+```
+layout {tall|grid|monocle}     # also: layout (no arg) → cycle
+drawer {toggle|show|hide|reset}
+save                           # persist session to ~/.muxr/sessions/<name>.json
+restore                        # show path to saved session
+sessions | ls                  # list saved sessions
+new | close | next | prev | master
+detach | quit                  # quit asks for y/n confirmation
+```
+
+## Architecture
+
+muxr runs as **two processes** that talk over a Unix domain socket at
+`~/.muxr/sockets/<name>.sock`. The server owns the PTYs and all session
+state; the client is a thin TTY front-end that comes and goes across
+detach/reattach.
+
+```
+Client (foreground, owns the TTY)              Server (daemon, owns the PTYs)
+ ├─ STDIN in raw mode + alt screen              Application (event loop, lifecycle)
+ ├─ SIGWINCH → RESIZE frame                      ├─ Session ─ Window ─ Pane[ ] ─ Terminal + PTYProcess
+ │                                               │      └─ Drawer ─ Pane
+ └─ Protocol                                     ├─ Renderer        – diff-emits ANSI as OUTPUT frames
+     ◄── OUTPUT bytes ──── Renderer ◄────────────┤   InputHandler    – Ctrl-a state machine
+     ──── INPUT bytes ───► InputHandler          ├─ CommandDispatcher – parses ":"-prefixed commands
+     ──── HELLO/RESIZE ──► apply_size            ├─ LayoutManager    – pure (layout, count, area) → [Rect]
+     ◄── BYE ───────────── disconnect_client     └─ UNIXServer listener (one client at a time)
+```
+
+Frames are length-prefixed (`[1-byte type][4-byte BE length][payload]`):
+`H` hello, `I` input, `R` resize, `B` bye, `O` output.
+
+The server's event loop is single-threaded `IO.select` over the listening
+socket, the attached client (when present), every pane PTY, and the
+drawer PTY. Layouts are pure — `LayoutManager` has no mutable state, so
+the renderer recomputes geometry on every tick after a resize or
+pane add/remove without bookkeeping.
+
+`Ctrl-a d` detaches the client but leaves the server (and its shells)
+running; reattaching gives you back the same panes with their full
+history. `Ctrl-a q` and `:quit` flash `kill session? (y/n)` in the status
+bar and only tear the server down on `y` — there is no "kill without
+confirm" keybinding by design.
+
+The drawer's PTY is **never torn down** when the drawer is hidden — its
+shell process keeps running so the next toggle restores the previous
+session. Its initial working directory is inherited from whatever pane
+was focused when the drawer was first created; only `drawer reset` kills
+the PTY.
+
+The per-pane `Terminal` is a real VT100 emulator (cursor movement, SGR
+including 256-color/truecolor and underline subparameters, erase/insert/
+delete, autowrap, scroll regions). Scrollback is composited into the
+visible grid through a view-offset that auto-tracks new rows while
+scrolled back, so reviewed content stays frozen.
+
+## Session persistence
+
+Sessions live in `~/.muxr/sessions/<name>.json`:
+
+```json
+{
+  "name": "default",
+  "layout": "tall",
+  "focused_index": 0,
+  "master_index": 0,
+  "panes":  [{"cwd": "/home/me/code"}, {"cwd": "/tmp"}],
+  "drawer": {"visible": true, "cwd": "/home/me/code"}
+}
+```
+
+The JSON file is mainly a **cold-storage fallback**. Between detaches the
+live session lives inside the running server process, so `Ctrl-a d` then
+`bin/muxr <name>` reattaches to the exact same shells with their full
+history. The JSON only matters once the server is gone (after `Ctrl-a q`
+or a reboot): re-launching `muxr <name>` rebuilds pane and drawer shells
+using the saved working directories. Shell command history within those
+panes is **not** persisted — that's the job of your shell's own history
+file. Run `:save` from inside muxr to write the snapshot.
+
+## Development
+
+```bash
+bundle install      # only minitest and rake
+rake test           # full suite (100+ unit tests)
+
+# Run a single file or test
+ruby -Ilib -Itest test/test_layout_manager.rb
+ruby -Ilib -Itest test/test_terminal.rb -n test_csi_cursor_position
+```
+
+Tests cover the layout algorithms, drawer state machine, window pane
+ordering, session JSON round-trip, the client/server framing protocol,
+the input-handler state machine (including scrollback and selection
+modes), the renderer's diff-emit, and the VT100 emulator's cursor
+movement, SGR (including colon-subparameter and underline-color forms),
+erase, scroll-region, and autowrap handling. PTY-dependent code paths
+are exercised via dependency injection so tests don't spawn shells.
+
+On-disk layout:
+
+```
+~/.muxr/
+ ├─ sessions/<name>.json   structural snapshot written by `:save`
+ ├─ sockets/<name>.sock    server's Unix listener (auto-managed)
+ └─ logs/<name>.log        server stdout/stderr
+```
+
+## Contributing
+
+Contributions are welcome from anyone, with one requirement: **the code
+must be generated by a frontier LLM** (e.g. Claude, GPT, Gemini at their
+current top-tier model). Hand-written patches will not be accepted.
+
+When you open a PR, please:
+
+- State which model produced the change in the PR description.
+- Include the prompt(s) you used, or a short summary of the conversation
+  that produced the diff.
+- Drive the model yourself — review, push back, iterate. You are
+  responsible for the patch: it should pass `rake test`, follow the
+  conventions in `CLAUDE.md`, and not regress existing behavior.
+
+Bug reports, feature requests, and design discussion in issues are
+welcome regardless of how they're written.

data/bin/muxr

@@ -0,0 +1,137 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "muxr"
+require "fileutils"
+require "rbconfig"
+require "socket"
+
+if ARGV.include?("-v") || ARGV.include?("--version")
+  puts "muxr #{Muxr::VERSION}"
+  exit 0
+end
+
+if ARGV.include?("-l") || ARGV.include?("--list")
+  names = Muxr::Session.list
+  puts names.join("\n") unless names.empty?
+  exit 0
+end
+
+if ARGV.include?("-h") || ARGV.include?("--help")
+  puts <<~USAGE
+    muxr #{Muxr::VERSION} — a tiling terminal multiplexer
+
+    Usage:
+      muxr                 attach the default session (auto-spawn if needed)
+      muxr <name>          attach (or start) the named session
+      muxr -s <name>       same as above
+      muxr --list          list saved session files and exit
+      muxr --version       print version and exit
+      muxr --help          this help
+
+    Keybindings (Ctrl-a prefix):
+      C-a c   new pane            C-a n / p   next / prev pane
+      C-a a   toggle last pane    C-a 1..9    jump to pane by number
+      C-a k   close pane          C-a Tab     cycle layout
+      C-a ~   toggle drawer       C-a Enter   promote to master
+      C-a :   command prompt      C-a ?       toggle help
+      C-a d   detach (server stays running)
+      C-a q   kill session (with y/n confirmation)
+      C-a C-a send literal C-a
+  USAGE
+  exit 0
+end
+
+# Internal: run as the server process. bin/muxr fork-execs itself with this
+# flag when no server is alive for the requested session.
+if ARGV.include?("--server")
+  args = ARGV.reject { |a| a == "--server" }
+  # Detach from the controlling terminal so the server survives the parent's
+  # shell closing. nochdir=true preserves cwd (the first pane inherits it);
+  # noclose=true keeps the stdin/out/err redirections Process.spawn set up.
+  begin
+    Process.daemon(true, true)
+  rescue NotImplementedError
+    # Platforms without Process.daemon (rare on POSIX) just run inline.
+  end
+  begin
+    Muxr::Application.new(args).run
+  rescue => e
+    $stderr.puts "muxr server: #{e.class}: #{e.message}"
+    $stderr.puts e.backtrace.first(20).join("\n")
+    exit 1
+  end
+  exit 0
+end
+
+# ---- client mode (the default) ----
+
+def session_name_from(argv)
+  idx = argv.index("-s") || argv.index("--session")
+  return argv[idx + 1] if idx && argv[idx + 1]
+  argv.find { |a| !a.start_with?("-") } || "default"
+end
+
+def probe_socket(path)
+  return :missing unless File.exist?(path)
+  begin
+    UNIXSocket.new(path).close
+    :alive
+  rescue Errno::ECONNREFUSED, Errno::ENOENT
+    File.unlink(path) rescue nil
+    :stale
+  rescue Errno::EACCES
+    :forbidden
+  end
+end
+
+def spawn_server(name, log_path)
+  FileUtils.mkdir_p(File.dirname(log_path))
+  log = File.open(log_path, "a")
+  pid = Process.spawn(
+    RbConfig.ruby, __FILE__, "--server", name,
+    in:  "/dev/null",
+    out: log,
+    err: log,
+    pgroup: true
+  )
+  log.close
+  Process.detach(pid)
+  pid
+end
+
+def wait_for_socket(path, deadline)
+  until File.exist?(path)
+    return false if Time.now >= deadline
+    sleep 0.05
+  end
+  true
+end
+
+name = session_name_from(ARGV)
+socket_path = Muxr::Application.socket_path_for(name)
+
+case probe_socket(socket_path)
+when :forbidden
+  $stderr.puts "muxr: cannot access #{socket_path} (permission denied)"
+  exit 1
+when :alive
+  # great — attach.
+when :missing, :stale
+  log_path = File.join(Dir.home, ".muxr", "logs", "#{name}.log")
+  spawn_server(name, log_path)
+  unless wait_for_socket(socket_path, Time.now + 3.0)
+    $stderr.puts "muxr: server did not start within 3s (see #{log_path})"
+    exit 1
+  end
+end
+
+client = Muxr::Client.new(name)
+begin
+  client.connect
+rescue Errno::ECONNREFUSED, Errno::ENOENT => e
+  $stderr.puts "muxr: cannot connect to server at #{socket_path}: #{e.message}"
+  exit 1
+end
+exit(client.run || 0)