hostty 0.1.0.alpha-x86_64-darwin

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. checksums.yaml +7 -0
  2. data/.hostty.yml +18 -0
  3. data/.ruby-version +1 -0
  4. data/LICENSE.txt +21 -0
  5. data/README.md +65 -0
  6. data/Rakefile +70 -0
  7. data/THIRD_PARTY_NOTICES.txt +247 -0
  8. data/docs/assets/demo.svg +168 -0
  9. data/docs/assets/hostty-dark-static.svg +27 -0
  10. data/docs/assets/hostty-dark.svg +92 -0
  11. data/docs/assets/hostty-light-static.svg +27 -0
  12. data/docs/assets/hostty-light.svg +92 -0
  13. data/docs/development/README.md +120 -0
  14. data/docs/development/architecture.md +169 -0
  15. data/docs/features/README.md +45 -0
  16. data/docs/features/command-line.md +46 -0
  17. data/docs/features/configuration.md +131 -0
  18. data/docs/features/domains.md +81 -0
  19. data/docs/features/plain-output.md +56 -0
  20. data/docs/features/stopping.md +69 -0
  21. data/docs/features/tabs.md +120 -0
  22. data/docs/features/terminal-emulator.md +66 -0
  23. data/exe/hostty +6 -0
  24. data/lib/hostty/cli.rb +86 -0
  25. data/lib/hostty/config.rb +78 -0
  26. data/lib/hostty/domains.rb +22 -0
  27. data/lib/hostty/exceptions.rb +7 -0
  28. data/lib/hostty/ghostty/frame.rb +203 -0
  29. data/lib/hostty/ghostty/libghostty-vt.dylib +0 -0
  30. data/lib/hostty/ghostty/library.rb +148 -0
  31. data/lib/hostty/ghostty/mouse.rb +77 -0
  32. data/lib/hostty/ghostty/screen.rb +112 -0
  33. data/lib/hostty/manager/child.rb +36 -0
  34. data/lib/hostty/manager/events.rb +27 -0
  35. data/lib/hostty/manager/process_exited.rb +28 -0
  36. data/lib/hostty/manager/signal_received.rb +23 -0
  37. data/lib/hostty/manager.rb +102 -0
  38. data/lib/hostty/output.rb +37 -0
  39. data/lib/hostty/plain/app.rb +23 -0
  40. data/lib/hostty/plain/pipe.rb +55 -0
  41. data/lib/hostty/port_chooser.rb +62 -0
  42. data/lib/hostty/process_config.rb +80 -0
  43. data/lib/hostty/terminal/cell.rb +35 -0
  44. data/lib/hostty/terminal/style.rb +87 -0
  45. data/lib/hostty/tui/app.rb +277 -0
  46. data/lib/hostty/tui/desktop.rb +51 -0
  47. data/lib/hostty/tui/input.rb +69 -0
  48. data/lib/hostty/tui/layout.rb +68 -0
  49. data/lib/hostty/tui/mouse_event.rb +36 -0
  50. data/lib/hostty/tui/pane.rb +125 -0
  51. data/lib/hostty/tui/pty.rb +62 -0
  52. data/lib/hostty/tui/renderer.rb +85 -0
  53. data/lib/hostty/tui/selection.rb +47 -0
  54. data/lib/hostty/version.rb +5 -0
  55. data/lib/hostty.rb +35 -0
  56. data/sig/hostty.rbs +4 -0
  57. metadata +130 -0
@@ -0,0 +1,131 @@
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="../assets/hostty-dark.svg">
4
+ <img src="../assets/hostty-light.svg" alt="Hostty" width="300">
5
+ </picture>
6
+ </p>
7
+
8
+ # Configuration
9
+
10
+ ### Contents
11
+
12
+ - [The Config File](#the-config-file)
13
+ - [Top-Level Settings](#top-level-settings)
14
+ - [Process Settings](#process-settings)
15
+ - [Ports](#ports)
16
+ - [Environment Variables](#environment-variables)
17
+ - [Working Directory and Shell](#working-directory-and-shell)
18
+ - [Config Errors](#config-errors)
19
+
20
+ ## The Config File
21
+
22
+ Hostty reads `.hostty.yml` from the current directory. Use the `--file` option to read another file. The [command line](./command-line.md) page lists every option.
23
+
24
+ The file lists the processes under `processes`, with settings for all of them next to it:
25
+
26
+ ```yaml
27
+ skip_used_ports: true
28
+ processes:
29
+ web:
30
+ command: "bin/rails server -p $PORT"
31
+ domain: "shop.test"
32
+ ssl: true
33
+ docs:
34
+ command: "bundle exec jekyll serve --port $PORT"
35
+ port: "random"
36
+ jobs:
37
+ command: "bin/jobs"
38
+ env:
39
+ JOB_CONCURRENCY: "2"
40
+ ```
41
+
42
+ A process with only a command can be a plain string:
43
+
44
+ ```yaml
45
+ processes:
46
+ jobs: "bin/jobs"
47
+ ```
48
+
49
+ Hostty starts the processes in the order of the file. The tabs and the [ports](#ports) follow the same order.
50
+
51
+ ## Top-Level Settings
52
+
53
+ | Setting | Required | What it does |
54
+ | --- | --- | --- |
55
+ | `processes` | Yes | The processes to run, by name. |
56
+ | `skip_used_ports` | No | When `true`, hostty moves a process to the next free port when its port is in use. When `false`, a port in use stops hostty. Defaults to `false`. See [Ports](#ports). |
57
+
58
+ ## Process Settings
59
+
60
+ | Setting | Required | What it does |
61
+ | --- | --- | --- |
62
+ | `command` | Yes | The command to run. |
63
+ | `domain` | No | A local domain for the process, such as `shop.test`. See [Domains](./domains.md). |
64
+ | `ssl` | No | Serve the domain over HTTPS. Defaults to `false`. |
65
+ | `log` | No | Write NGINX access and error logs for the domain to `~/.ruby-nginx/logs`. Defaults to `false`. |
66
+ | `host` | No | The address that the domain points to and that NGINX sends requests to. Defaults to `127.0.0.1`. |
67
+ | `port` | No | A port number, or `"random"`. See [Ports](#ports). |
68
+ | `env` | No | More environment variables for the process. |
69
+
70
+ ## Ports
71
+
72
+ Hostty sets `PORT` for each process. The `port` setting of the process decides where the port comes from:
73
+
74
+ | `port` setting | Port | When the port is in use |
75
+ | --- | --- | --- |
76
+ | Not set | From the position of the process. The first process gets 5000, and each next process gets 100 more. | Follows `skip_used_ports`. |
77
+ | `"random"` | A random port from 10000 to 59999. | Follows `skip_used_ports`. |
78
+ | A number, such as `3000` | That port. | Always stops. Hostty never moves a port that you set. |
79
+
80
+ Before it adds a domain or starts a process, hostty checks that it can open each port:
81
+
82
+ - With `skip_used_ports: false`, a port in use stops hostty with an error.
83
+ - With `skip_used_ports: true`, hostty tries the next port up, as many as 100 ports, and prints the change:
84
+
85
+ ```text
86
+ 12:00:01 hostty | Port 5000 for web is in use. web uses 5001.
87
+ ```
88
+
89
+ Other details:
90
+
91
+ - The `--port` option changes the first position port. `hostty --port 3000` gives 3000, 3100, and 3200.
92
+ - Hostty gives the processes with a port number their ports first. A position port or a random port never takes a port that another process sets.
93
+ - A domain sends its requests to the port of its process, so the command must listen on `$PORT`.
94
+ - A [restart](./tabs.md#exited-processes-and-restarts) keeps the port that the process got at start.
95
+ - Another program can still take a port in the short gap after the check and before the process opens it.
96
+ - On macOS, AirPlay Receiver uses port 5000. Turn AirPlay Receiver off, start from another port with `--port`, or set `skip_used_ports: true`.
97
+
98
+ ## Environment Variables
99
+
100
+ Each process gets the environment of hostty, plus `PORT`, plus its `env` setting. Hostty turns every `env` value into a string.
101
+
102
+ An `env` setting cannot change `PORT`. Use the `port` setting for that.
103
+
104
+ ## Working Directory and Shell
105
+
106
+ - Each process runs in the directory of the config file, even when you start hostty from another directory.
107
+ - Hostty runs each command with `/bin/sh -c`, so shell syntax such as `$PORT`, `&&`, and pipes works.
108
+
109
+ ## Config Errors
110
+
111
+ Hostty stops before it adds a domain or starts a process when the config file has an error. It prints the error and exits with code 1:
112
+
113
+ | The config file has | Hostty prints |
114
+ | --- | --- |
115
+ | No file at the path | `No config file at <path>.` |
116
+ | A YAML syntax error | `The config file at <path> is not valid YAML: <details>` |
117
+ | No processes under `processes` | `The config file at <path> must list at least one process under processes.` |
118
+ | A top-level setting hostty does not know | `The config file at <path> has unknown settings: <settings>.` |
119
+ | A `skip_used_ports` that is not `true` or `false` | `skip_used_ports must be true or false.` |
120
+ | A process with no command | `<name> needs a command.` |
121
+ | A process setting hostty does not know | `<name> has unknown settings: <settings>.` |
122
+ | A port that is not a number from 1 to 65535, or `"random"` | `<name> needs a port from 1 to 65535, or "random".` |
123
+ | A port in use, with `skip_used_ports: false` | `Port <port> for <name> is in use. Free the port, or set skip_used_ports to true.` |
124
+ | A port number that is in use | `Port <port> for <name> is in use. Free the port, or change the port of <name>.` |
125
+ | Two processes on one port | `<name> and <name> both use port <port>.` |
126
+ | No free port within 100 ports, with `skip_used_ports: true` | `No free port for <name> from <first> to <last>.` |
127
+ | Two processes with one domain | `More than one process uses the domain <domain>.` |
128
+
129
+ ---
130
+
131
+ [← Return to Features](./README.md)
@@ -0,0 +1,81 @@
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="../assets/hostty-dark.svg">
4
+ <img src="../assets/hostty-light.svg" alt="Hostty" width="300">
5
+ </picture>
6
+ </p>
7
+
8
+ # Domains
9
+
10
+ ### Contents
11
+
12
+ - [What a Domain Does](#what-a-domain-does)
13
+ - [When Hostty Adds a Domain](#when-hostty-adds-a-domain)
14
+ - [Prompts](#prompts)
15
+ - [When a Domain Fails](#when-a-domain-fails)
16
+ - [Removing a Domain](#removing-a-domain)
17
+
18
+ ## What a Domain Does
19
+
20
+ A process with a `domain` setting gets a local address, such as `https://shop.test`, that points to its port:
21
+
22
+ ```yaml
23
+ processes:
24
+ web:
25
+ command: "bin/rails server -p $PORT"
26
+ domain: "shop.test"
27
+ ssl: true
28
+ ```
29
+
30
+ [ruby-nginx](https://github.com/bert-mccutchen/ruby-nginx) does the work for each domain:
31
+
32
+ - It writes an NGINX server config that sends requests for the domain to the port of the process.
33
+ - It adds the domain to `/etc/hosts`.
34
+ - It makes an SSL certificate with mkcert, when `ssl` is `true`.
35
+ - It restarts NGINX.
36
+
37
+ ```mermaid
38
+ flowchart LR
39
+ browser[Browser] -- "https://shop.test" --> hosts["/etc/hosts<br/>shop.test = 127.0.0.1"]
40
+ hosts --> nginx[NGINX]
41
+ nginx -- "localhost:5000" --> web[web process]
42
+ ```
43
+
44
+ The [settings](./configuration.md#settings) page lists `ssl`, `log`, and `host`.
45
+
46
+ ## When Hostty Adds a Domain
47
+
48
+ Hostty adds every domain before it starts any process. It prints one line per domain:
49
+
50
+ ```text
51
+ 12:00:01 hostty | Adding https://shop.test for web on port 5000.
52
+ ```
53
+
54
+ Hostty adds the domains in your real terminal, before the tabs open, so every prompt can ask you for input.
55
+
56
+ ## Prompts
57
+
58
+ Adding a domain can stop and ask you for input:
59
+
60
+ - ruby-nginx asks before it installs NGINX or mkcert, when either is missing. It needs both, even for a domain without `ssl`.
61
+ - `sudo` asks for your password, because editing `/etc/hosts` and restarting NGINX need root.
62
+
63
+ ruby-nginx updates `/etc/hosts` on every run, so the password prompt can come back on each start. Your `sudo` timeout decides how often it does.
64
+
65
+ ## When a Domain Fails
66
+
67
+ When a domain fails, or you decline a prompt, hostty prints the error, starts no process, and exits with code 1:
68
+
69
+ ```text
70
+ hostty: NGINX is required to continue. Please install NGINX.
71
+ ```
72
+
73
+ ruby-nginx removes the domain that failed. The domains that hostty added before it stay in place.
74
+
75
+ ## Removing a Domain
76
+
77
+ Hostty keeps every domain after it exits. To remove one, delete its line from `/etc/hosts` and its server config from `~/.ruby-nginx/servers`, then restart NGINX. The ruby-nginx command line can also remove a domain.
78
+
79
+ ---
80
+
81
+ [← Return to Features](./README.md)
@@ -0,0 +1,56 @@
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="../assets/hostty-dark.svg">
4
+ <img src="../assets/hostty-light.svg" alt="Hostty" width="300">
5
+ </picture>
6
+ </p>
7
+
8
+ # Plain Output
9
+
10
+ ### Contents
11
+
12
+ - [When Hostty Prints Plain Output](#when-hostty-prints-plain-output)
13
+ - [The Output](#the-output)
14
+ - [When a Process Exits](#when-a-process-exits)
15
+ - [Limits](#limits)
16
+
17
+ ## When Hostty Prints Plain Output
18
+
19
+ Hostty prints plain output in place of [tabs](./tabs.md) when either is true:
20
+
21
+ - You pass `--plain`.
22
+ - stdin or stdout is not a terminal, such as in CI or in `hostty | tee hostty.log`.
23
+
24
+ ## The Output
25
+
26
+ Hostty prints every line of every process in one stream, with the time and the process name:
27
+
28
+ ```text
29
+ 12:00:01 hostty | Adding https://shop.test for web on port 5000.
30
+ 12:00:02 web | => Booting Puma
31
+ 12:00:02 docs | Server address: http://127.0.0.1:5100/
32
+ 12:00:03 jobs | SolidQueue-1.1.0 Started Supervisor (12.1ms)
33
+ ```
34
+
35
+ - Lines from hostty itself use the name `hostty`.
36
+ - Each name gets its own color when stdout is a terminal.
37
+
38
+ ## When a Process Exits
39
+
40
+ The first process that exits stops all the others:
41
+
42
+ ```text
43
+ 12:05:00 hostty | jobs exited with code 1.
44
+ 12:05:00 hostty | Stopping all processes.
45
+ ```
46
+
47
+ Hostty then exits with the exit code of that process. See [Stopping](./stopping.md) and the [exit codes](./command-line.md#exit-codes).
48
+
49
+ ## Limits
50
+
51
+ - A process cannot read input. Hostty connects its stdin to `/dev/null`, so `binding.irb` and password prompts do not work. Use [tabs](./tabs.md) for those.
52
+ - A process writes to a pipe, not a terminal. Some programs hold back their output, or drop their colors, until a buffer fills. In Ruby, set `$stdout.sync = true` to print each line at once.
53
+
54
+ ---
55
+
56
+ [← Return to Features](./README.md)
@@ -0,0 +1,69 @@
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="../assets/hostty-dark.svg">
4
+ <img src="../assets/hostty-light.svg" alt="Hostty" width="300">
5
+ </picture>
6
+ </p>
7
+
8
+ # Stopping
9
+
10
+ ### Contents
11
+
12
+ - [What Stops Hostty](#what-stops-hostty)
13
+ - [How Hostty Stops the Processes](#how-hostty-stops-the-processes)
14
+ - [Child Processes](#child-processes)
15
+ - [Stopping Faster](#stopping-faster)
16
+
17
+ ## What Stops Hostty
18
+
19
+ | Mode | What stops hostty |
20
+ | --- | --- |
21
+ | [Tabs](./tabs.md) | Ctrl-C twice within half a second, or TERM or HUP from another terminal. |
22
+ | [Plain output](./plain-output.md) | Ctrl-C, TERM, HUP, or the first process that exits. |
23
+
24
+ In tabs, hostty first leaves the tab view and gives you back your terminal. The lines below then print in your terminal.
25
+
26
+ ## How Hostty Stops the Processes
27
+
28
+ ```mermaid
29
+ flowchart TD
30
+ begin([Stop]) --> term[Send TERM to every process]
31
+ term --> wait{"Did every process exit<br/>within the timeout?"}
32
+ wait -- yes --> done([Exit])
33
+ wait -- "no, or Ctrl-C again" --> kill[Send KILL to the processes<br/>that still run]
34
+ kill --> wait_kill{"Did they exit<br/>within 5 seconds?"}
35
+ wait_kill -- yes --> done
36
+ wait_kill -- "no, or Ctrl-C again" --> give_up[Print the processes that<br/>hostty stopped waiting for]
37
+ give_up --> done
38
+ ```
39
+
40
+ Hostty prints each step:
41
+
42
+ ```text
43
+ 12:10:00 hostty | Stopping all processes.
44
+ 12:10:00 hostty | web exited with code 143.
45
+ 12:10:00 hostty | jobs exited with code 143.
46
+ ```
47
+
48
+ When a process does not exit in time:
49
+
50
+ ```text
51
+ 12:10:10 hostty | Killing the processes that are still running.
52
+ ```
53
+
54
+ The `--timeout` option sets the first wait. It defaults to 10 seconds. Give a slow process, such as Solid Queue finishing its running jobs, more time with a higher value.
55
+
56
+ ## Child Processes
57
+
58
+ Hostty sends each signal to the whole process group of a process, so the processes that it started stop too. A Rails server with Puma workers, or a shell script with background jobs, stops in full.
59
+
60
+ A child process that starts its own session or process group leaves the group, so hostty cannot stop it.
61
+
62
+ ## Stopping Faster
63
+
64
+ - During the wait after TERM, press Ctrl-C again, or send TERM again, to send KILL right away.
65
+ - During the wait after KILL, press Ctrl-C again, or send TERM again, to stop waiting and exit.
66
+
67
+ ---
68
+
69
+ [← Return to Features](./README.md)
@@ -0,0 +1,120 @@
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="../assets/hostty-dark.svg">
4
+ <img src="../assets/hostty-light.svg" alt="Hostty" width="300">
5
+ </picture>
6
+ </p>
7
+
8
+ # Tabs
9
+
10
+ ### Contents
11
+
12
+ - [When Hostty Shows Tabs](#when-hostty-shows-tabs)
13
+ - [The Screen](#the-screen)
14
+ - [Keys and Mouse](#keys-and-mouse)
15
+ - [Typing Into a Process](#typing-into-a-process)
16
+ - [Scrolling](#scrolling)
17
+ - [Exited Processes and Restarts](#exited-processes-and-restarts)
18
+ - [Selecting Text](#selecting-text)
19
+
20
+ ## When Hostty Shows Tabs
21
+
22
+ Hostty shows tabs when both stdin and stdout are terminals. Otherwise, and with `--plain`, it prints [plain output](./plain-output.md).
23
+
24
+ The tabs need libghostty-vt. The [terminal emulator](./terminal-emulator.md) page covers what works inside a tab.
25
+
26
+ ## The Screen
27
+
28
+ ```text
29
+ ● web ● docs ● jobs https://shop.test
30
+ => Booting Puma
31
+ => Rails 8.0.0 application starting in development
32
+ * Listening on http://127.0.0.1:5000
33
+ Use Ctrl-C to stop
34
+
35
+
36
+
37
+ Switch: click or Shift+Tab | Scroll: history | [restart] | Quit: Ctrl-C twice
38
+ ```
39
+
40
+ - The top row shows a tab per process. The selected tab is blue.
41
+ - The dot in each tab is green while the process runs and red after it exits.
42
+ - When the selected process has a [domain](./domains.md), the right end of the top row shows its URL. Click the URL to open it in your browser.
43
+ - The middle rows show the selected process, as a terminal would show it.
44
+ - The bottom row is the help bar. `[restart]` is a button.
45
+
46
+ The screen fits the window, and it redraws when you resize the window. Each process also gets the new size.
47
+
48
+ ## Keys and Mouse
49
+
50
+ | Action | What it does |
51
+ | --- | --- |
52
+ | Click a tab | Shows that process. |
53
+ | Click the URL | Opens the domain of the selected process in your browser, with `open` on macOS or `xdg-open` on Linux. |
54
+ | Shift+Tab | Shows the next process. After the last tab, it goes back to the first. |
55
+ | Mouse wheel | Scrolls the selected process. See [Scrolling](#scrolling). |
56
+ | Drag across the output | Selects the text and copies it. See [Selecting Text](#selecting-text). |
57
+ | Click `[restart]` | Restarts the selected process. |
58
+ | Ctrl-C | Sends Ctrl-C to the selected process. |
59
+ | Ctrl-C twice within half a second | Quits hostty. See [Stopping](./stopping.md). |
60
+ | Any other key | Goes to the selected process. |
61
+
62
+ The first Ctrl-C of a double press also goes to the selected process.
63
+
64
+ Hostty keeps Shift+Tab for itself, so a process never gets it.
65
+
66
+ When a program turns on mouse reporting, as `btop`, `htop`, and `vim` do, the clicks, drags, and wheel steps inside its tab go to the program. Hold Shift while you drag to select text in that tab instead. Some terminals, such as Ghostty, keep a Shift drag for their own selection, so hostty never sees it. Clicks on the tab bar and the help bar always stay with hostty.
67
+
68
+ ## Typing Into a Process
69
+
70
+ Each process runs in its own terminal inside hostty. Programs that read from a terminal work in their tab:
71
+
72
+ - `binding.irb` and `debugger` in a Rails app.
73
+ - A `sudo` password prompt.
74
+ - irb, a shell, or any other interactive program.
75
+
76
+ Click the tab of the process, then type.
77
+
78
+ ## Scrolling
79
+
80
+ What a mouse wheel step does depends on the program in the tab:
81
+
82
+ | The program | A wheel step |
83
+ | --- | --- |
84
+ | Turned on mouse reporting, such as `btop`, `htop`, or `vim` | Goes to the program, which scrolls its own list or text. |
85
+ | Shows a full screen without mouse reporting, such as `less` or `man` | Sends 3 up or down arrow keys to the program. |
86
+ | Prints lines, such as a Rails server or a test runner | Scrolls 3 lines through the older output. The help bar shows how far up you are, such as `Scrolled up 30`. |
87
+
88
+ - Hostty keeps the last 5000 lines of each process.
89
+ - A key press goes back to the newest output.
90
+
91
+ ## Exited Processes and Restarts
92
+
93
+ When a process exits, the other processes keep running. Its tab turns red, and its screen shows the exit code:
94
+
95
+ ```text
96
+ [hostty] web exited with code 1.
97
+ ```
98
+
99
+ Click `[restart]` to start it again, with the same command and port. A process that still runs gets TERM first, then starts again after it exits.
100
+
101
+ ## Selecting Text
102
+
103
+ Drag across the output of a process to select its text. Hostty highlights the selection and copies the text when you let go of the mouse button. The selection stays inside the tab, so it never includes the tab bar or the help bar.
104
+
105
+ - Hostty drops the spaces at the end of each line.
106
+ - To select more than one screen, drag onto the tab bar or the help bar. The output scrolls while you hold the pointer there, and it scrolls faster the longer you hold. The mouse wheel also scrolls during a drag.
107
+ - The selection stays on its lines when the output scrolls.
108
+ - A key press, a resize, or a click elsewhere in the output clears the selection.
109
+ - In a program with mouse reporting, such as `btop`, a plain drag goes to the program. Hold Shift to select instead.
110
+
111
+ Hostty copies the text in two ways, so it works in most setups:
112
+
113
+ - An OSC 52 escape code, which your terminal turns into a clipboard write. Ghostty, kitty, WezTerm, and Alacritty accept it. iTerm2 accepts it after you turn on "Applications in terminal may access clipboard".
114
+ - The first clipboard command it finds: `pbcopy` on macOS, or `wl-copy`, `xclip`, or `xsel` on Linux.
115
+
116
+ Your terminal's own selection still works with a modifier key held while you drag. That key is Option in Terminal and iTerm2, and Shift in Ghostty and most Linux terminals.
117
+
118
+ ---
119
+
120
+ [← Return to Features](./README.md)
@@ -0,0 +1,66 @@
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="../assets/hostty-dark.svg">
4
+ <img src="../assets/hostty-light.svg" alt="Hostty" width="300">
5
+ </picture>
6
+ </p>
7
+
8
+ # Terminal Emulator
9
+
10
+ ### Contents
11
+
12
+ - [What It Does](#what-it-does)
13
+ - [What Works](#what-works)
14
+ - [What Hostty Does Not Pass On](#what-hostty-does-not-pass-on)
15
+ - [Speed](#speed)
16
+
17
+ ## What It Does
18
+
19
+ Each [tab](./tabs.md) shows its process the way a terminal would. Hostty writes the output of each process into [libghostty-vt](https://lib.ghostty.org/vt/), the terminal engine of [Ghostty](https://ghostty.org). libghostty-vt keeps a screen of characters and colors for each process, and Hostty draws the screen of the selected tab.
20
+
21
+ The [installation](../../README.md#installation) section says where Hostty gets libghostty-vt. Without it, Hostty stops before it shows the tabs:
22
+
23
+ ```text
24
+ hostty: Tabs need libghostty-vt, which did not load (<details>). Run with --plain to skip the tabs.
25
+ ```
26
+
27
+ ## What Works
28
+
29
+ libghostty-vt reads the escape codes that a program writes the same way Ghostty does. That covers:
30
+
31
+ - Rails, Puma, Jekyll, Solid Queue, test runners, and other logs.
32
+ - irb, `binding.irb`, debug, and a shell.
33
+ - Full-screen programs, such as `btop`, `htop`, `vim`, `less`, and `tig`.
34
+
35
+ Hostty draws these from the screen:
36
+
37
+ | Area | Drawn |
38
+ | --- | --- |
39
+ | Text | UTF-8, wide characters such as CJK and emoji, and characters made of more than one code point. |
40
+ | Colors | 16, 256, and 24-bit colors, for text and background. |
41
+ | Text styles | Bold, dim, italic, underline, blink, inverse, invisible, strikethrough, and overline. |
42
+ | Screens | The main screen with its scrollback, and the alternate screen. |
43
+ | Resize | Wrapped lines on the main screen reflow when the window changes width. |
44
+ | Replies | libghostty-vt answers queries such as the cursor position and the device attributes, and Hostty writes the answer back to the process. |
45
+
46
+ ## What Hostty Does Not Pass On
47
+
48
+ libghostty-vt tracks more than Hostty draws or forwards:
49
+
50
+ | Missing | What you see |
51
+ | --- | --- |
52
+ | Underline styles and underline colors | A plain underline, in the text color. |
53
+ | Images, such as Kitty graphics | Nothing in the place of the image. |
54
+ | Links | The link text, without a link. |
55
+ | Cursor shape | Your terminal's own cursor. |
56
+ | Window titles, the bell, and clipboard writes | Nothing. |
57
+ | Keyboard modes other than application cursor keys and bracketed paste | Keys arrive in the form your terminal sends them. |
58
+
59
+ ## Speed
60
+
61
+ - libghostty-vt reads about 450 to 1,800 MB of output a second on one CPU core, so a process that floods its output does not slow hostty down.
62
+ - Hostty reads the screen from libghostty-vt before each frame. A read takes about 1 ms at 80 by 24 and about 8 ms at 200 by 50. Hostty reads only the selected tab, at most about 60 times a second.
63
+
64
+ ---
65
+
66
+ [← Return to Features](./README.md)
data/exe/hostty ADDED
@@ -0,0 +1,6 @@
1
+ #!/usr/bin/env ruby
2
+ # frozen_string_literal: true
3
+
4
+ require "hostty"
5
+
6
+ exit Hostty::CLI.new(argv: ARGV).run
data/lib/hostty/cli.rb ADDED
@@ -0,0 +1,86 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Hostty
4
+ class CLI
5
+ def initialize(argv:, nginx: Ruby::Nginx, stdin: $stdin, stdout: $stdout, stderr: $stderr, desktop: nil)
6
+ @argv = argv
7
+ @nginx = nginx
8
+ @stdin = stdin
9
+ @stdout = stdout
10
+ @stderr = stderr
11
+ @desktop = desktop || Tui::Desktop.new(io: stdout)
12
+ end
13
+
14
+ def run
15
+ arguments = parser.parse(argv, into: options)
16
+ return print_and_succeed(parser.help) if options[:help]
17
+ return print_and_succeed(VERSION) if options[:version]
18
+ raise OptionParser::InvalidArgument, arguments.join(" ") unless arguments.empty? || arguments == ["start"]
19
+
20
+ start
21
+ rescue OptionParser::ParseError, Error, Ruby::Nginx::Error => e
22
+ stderr.puts("hostty: #{e.message}")
23
+ 1
24
+ rescue Interrupt
25
+ 130
26
+ end
27
+
28
+ private
29
+
30
+ attr_reader :argv, :nginx, :stdin, :stdout, :stderr, :desktop
31
+
32
+ def tui?
33
+ !options[:plain] && stdin.tty? && stdout.tty?
34
+ end
35
+
36
+ def options
37
+ @options ||= {
38
+ file: Config::FILE_NAME,
39
+ port: Config::BASE_PORT,
40
+ timeout: 10
41
+ }
42
+ end
43
+
44
+ def parser
45
+ @parser ||= OptionParser.new do |parser|
46
+ parser.banner = "Usage: hostty [start] [options]"
47
+ parser.on("-f", "--file FILE", "Read the processes from FILE. Defaults to #{Config::FILE_NAME}.")
48
+ parser.on("-p", "--port PORT", Integer, "Give the first process PORT. Defaults to #{Config::BASE_PORT}.")
49
+ parser.on("-t", "--timeout SECONDS", Float, "Wait SECONDS for the processes to stop before killing them.")
50
+ parser.on("--plain", "Print the output of all processes together instead of in tabs.")
51
+ parser.on("-v", "--version", "Print the version.")
52
+ parser.on("-h", "--help", "Print this help.")
53
+ end
54
+ end
55
+
56
+ def config
57
+ @config ||= Config.new(path: options[:file], base_port: options[:port])
58
+ end
59
+
60
+ def output
61
+ @output ||= Output.new(names: config.processes.map(&:name), io: stdout)
62
+ end
63
+
64
+ def front_end
65
+ tui? ? Tui::App.new(stdin:, stdout:, desktop:) : Plain::App.new(output:)
66
+ end
67
+
68
+ def load_ghostty
69
+ require_relative "ghostty/screen"
70
+ rescue LoadError => e
71
+ raise Error, "Tabs need libghostty-vt, which did not load (#{e.message}). Run with --plain to skip the tabs."
72
+ end
73
+
74
+ def start
75
+ load_ghostty if tui?
76
+ config.notices.each { |notice| output.notice(notice) }
77
+ Domains.new(processes: config.processes, nginx:, output:).add
78
+ Manager.new(processes: config.processes, front_end:, output:, stop_timeout: options[:timeout]).run
79
+ end
80
+
81
+ def print_and_succeed(text)
82
+ stdout.puts(text)
83
+ 0
84
+ end
85
+ end
86
+ end