hostty 0.1.0.alpha-arm64-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,92 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="432" height="198" viewBox="40 163 432 198" role="img" aria-label="Hostty: three little ghosts in a line, each with a terminal prompt for a face">
2
+ <defs>
3
+ <!-- One ghost, 120 wide, with a ">_" face. The bottom has two ripples and rounded corners. -->
4
+ <path id="body" d="M0 60 C0 27 27 0 60 0 C93 0 120 27 120 60 L120 122 C120 134 112 142 104 142 C96 142 90 132 82 132 S68 142 60 142 S46 132 38 132 S24 142 16 142 C8 142 0 134 0 122 Z"/>
5
+ <!-- The "_" of the face. Each ghost draws its own ">" so it can blink at its own time. -->
6
+ <line id="cursor" x1="62" y1="76" x2="88" y2="76"/>
7
+ <!-- Each ghost floats up and down, one after the other. The body stretches while it rises and shrinks while it falls, so the bottom trails the head. -->
8
+ <style>
9
+ .face {
10
+ fill: none;
11
+ stroke: #1a1b26;
12
+ stroke-width: 10;
13
+ stroke-linecap: round;
14
+ stroke-linejoin: round;
15
+ }
16
+ .bob, .stretch, .shift {
17
+ animation-duration: 1.6s;
18
+ animation-iteration-count: infinite;
19
+ animation-timing-function: ease-in-out;
20
+ }
21
+ .bob {
22
+ animation-name: bob;
23
+ animation-delay: var(--delay);
24
+ }
25
+ /* The stretch runs a quarter cycle behind the bob, so it is tallest while the ghost rises fastest. */
26
+ .stretch {
27
+ animation-name: stretch;
28
+ animation-delay: calc(var(--delay) - 1.2s);
29
+ transform-box: fill-box;
30
+ transform-origin: 50% 0;
31
+ }
32
+ /* The face keeps its shape. It moves with the stretch at its own height, about 58px below the top of the head. */
33
+ .shift {
34
+ animation-name: shift;
35
+ animation-delay: calc(var(--delay) - 1.2s);
36
+ }
37
+ @keyframes bob {
38
+ 0%, 100% { transform: translateY(0); }
39
+ 50% { transform: translateY(-6px); }
40
+ }
41
+ @keyframes stretch {
42
+ 0%, 100% { transform: scaleY(1.04); }
43
+ 50% { transform: scaleY(0.96); }
44
+ }
45
+ @keyframes shift {
46
+ 0%, 100% { transform: translateY(2.3px); }
47
+ 50% { transform: translateY(-2.3px); }
48
+ }
49
+ @media (prefers-reduced-motion: reduce) {
50
+ .bob, .stretch, .shift { animation: none; }
51
+ }
52
+ </style>
53
+ </defs>
54
+
55
+ <!-- Ghosts. To blink, the ">" flattens into a "-" and opens again. Each ghost blinks on a different loop length, so the blinks do not line up. -->
56
+ <g transform="translate(60 183)" style="--delay: 0s">
57
+ <g class="bob">
58
+ <use class="stretch" href="#body" fill="#9ece6a"/>
59
+ <g class="shift face">
60
+ <polyline points="32,42 52,58 32,74">
61
+ <animate attributeName="points" dur="4s" repeatCount="indefinite" keyTimes="0;0.97;0.985;1" values="32,42 52,58 32,74;32,42 52,58 32,74;32,58 52,58 32,58;32,42 52,58 32,74"/>
62
+ </polyline>
63
+ <use href="#cursor"/>
64
+ </g>
65
+ </g>
66
+ </g>
67
+ <g transform="translate(196 183)" style="--delay: -0.2s">
68
+ <g class="bob">
69
+ <use class="stretch" href="#body" fill="#7aa2f7"/>
70
+ <g class="shift face">
71
+ <polyline points="32,42 52,58 32,74">
72
+ <animate attributeName="points" dur="5.2s" repeatCount="indefinite" keyTimes="0;0.977;0.9885;1" values="32,42 52,58 32,74;32,42 52,58 32,74;32,58 52,58 32,58;32,42 52,58 32,74"/>
73
+ </polyline>
74
+ <use href="#cursor"/>
75
+ </g>
76
+ </g>
77
+ </g>
78
+ <g transform="translate(332 183)" style="--delay: -0.4s">
79
+ <g class="bob">
80
+ <use class="stretch" href="#body" fill="#bb9af7"/>
81
+ <g class="shift face">
82
+ <polyline points="32,42 52,58 32,74">
83
+ <animate attributeName="points" dur="4.6s" repeatCount="indefinite" keyTimes="0;0.974;0.987;1" values="32,42 52,58 32,74;32,42 52,58 32,74;32,58 52,58 32,58;32,42 52,58 32,74"/>
84
+ </polyline>
85
+ <use href="#cursor"/>
86
+ </g>
87
+ </g>
88
+ </g>
89
+
90
+ <!-- Line under the ghosts -->
91
+ <line x1="60" y1="341" x2="452" y2="341" stroke="#a9b1d6" stroke-width="10" stroke-linecap="round"/>
92
+ </svg>
@@ -0,0 +1,27 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="432" height="198" viewBox="40 163 432 198" role="img" aria-label="Hostty: three little ghosts in a line, each with a terminal prompt for a face">
2
+ <defs>
3
+ <!-- One ghost, 120 wide, with a ">_" face. The bottom has two ripples and rounded corners. -->
4
+ <path id="body" d="M0 60 C0 27 27 0 60 0 C93 0 120 27 120 60 L120 122 C120 134 112 142 104 142 C96 142 90 132 82 132 S68 142 60 142 S46 132 38 132 S24 142 16 142 C8 142 0 134 0 122 Z"/>
5
+ <g id="face" fill="none" stroke="#1a1b26" stroke-width="10" stroke-linecap="round" stroke-linejoin="round">
6
+ <polyline points="32,42 52,58 32,74"/>
7
+ <line x1="62" y1="76" x2="88" y2="76"/>
8
+ </g>
9
+ </defs>
10
+
11
+ <!-- Ghosts -->
12
+ <g transform="translate(60 183)">
13
+ <use href="#body" fill="#7fb24a"/>
14
+ <use href="#face"/>
15
+ </g>
16
+ <g transform="translate(196 183)">
17
+ <use href="#body" fill="#5a8ef0"/>
18
+ <use href="#face"/>
19
+ </g>
20
+ <g transform="translate(332 183)">
21
+ <use href="#body" fill="#a07ef0"/>
22
+ <use href="#face"/>
23
+ </g>
24
+
25
+ <!-- Line under the ghosts -->
26
+ <line x1="60" y1="341" x2="452" y2="341" stroke="#565f89" stroke-width="10" stroke-linecap="round"/>
27
+ </svg>
@@ -0,0 +1,92 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="432" height="198" viewBox="40 163 432 198" role="img" aria-label="Hostty: three little ghosts in a line, each with a terminal prompt for a face">
2
+ <defs>
3
+ <!-- One ghost, 120 wide, with a ">_" face. The bottom has two ripples and rounded corners. -->
4
+ <path id="body" d="M0 60 C0 27 27 0 60 0 C93 0 120 27 120 60 L120 122 C120 134 112 142 104 142 C96 142 90 132 82 132 S68 142 60 142 S46 132 38 132 S24 142 16 142 C8 142 0 134 0 122 Z"/>
5
+ <!-- The "_" of the face. Each ghost draws its own ">" so it can blink at its own time. -->
6
+ <line id="cursor" x1="62" y1="76" x2="88" y2="76"/>
7
+ <!-- Each ghost floats up and down, one after the other. The body stretches while it rises and shrinks while it falls, so the bottom trails the head. -->
8
+ <style>
9
+ .face {
10
+ fill: none;
11
+ stroke: #1a1b26;
12
+ stroke-width: 10;
13
+ stroke-linecap: round;
14
+ stroke-linejoin: round;
15
+ }
16
+ .bob, .stretch, .shift {
17
+ animation-duration: 1.6s;
18
+ animation-iteration-count: infinite;
19
+ animation-timing-function: ease-in-out;
20
+ }
21
+ .bob {
22
+ animation-name: bob;
23
+ animation-delay: var(--delay);
24
+ }
25
+ /* The stretch runs a quarter cycle behind the bob, so it is tallest while the ghost rises fastest. */
26
+ .stretch {
27
+ animation-name: stretch;
28
+ animation-delay: calc(var(--delay) - 1.2s);
29
+ transform-box: fill-box;
30
+ transform-origin: 50% 0;
31
+ }
32
+ /* The face keeps its shape. It moves with the stretch at its own height, about 58px below the top of the head. */
33
+ .shift {
34
+ animation-name: shift;
35
+ animation-delay: calc(var(--delay) - 1.2s);
36
+ }
37
+ @keyframes bob {
38
+ 0%, 100% { transform: translateY(0); }
39
+ 50% { transform: translateY(-6px); }
40
+ }
41
+ @keyframes stretch {
42
+ 0%, 100% { transform: scaleY(1.04); }
43
+ 50% { transform: scaleY(0.96); }
44
+ }
45
+ @keyframes shift {
46
+ 0%, 100% { transform: translateY(2.3px); }
47
+ 50% { transform: translateY(-2.3px); }
48
+ }
49
+ @media (prefers-reduced-motion: reduce) {
50
+ .bob, .stretch, .shift { animation: none; }
51
+ }
52
+ </style>
53
+ </defs>
54
+
55
+ <!-- Ghosts. To blink, the ">" flattens into a "-" and opens again. Each ghost blinks on a different loop length, so the blinks do not line up. -->
56
+ <g transform="translate(60 183)" style="--delay: 0s">
57
+ <g class="bob">
58
+ <use class="stretch" href="#body" fill="#7fb24a"/>
59
+ <g class="shift face">
60
+ <polyline points="32,42 52,58 32,74">
61
+ <animate attributeName="points" dur="4s" repeatCount="indefinite" keyTimes="0;0.97;0.985;1" values="32,42 52,58 32,74;32,42 52,58 32,74;32,58 52,58 32,58;32,42 52,58 32,74"/>
62
+ </polyline>
63
+ <use href="#cursor"/>
64
+ </g>
65
+ </g>
66
+ </g>
67
+ <g transform="translate(196 183)" style="--delay: -0.2s">
68
+ <g class="bob">
69
+ <use class="stretch" href="#body" fill="#5a8ef0"/>
70
+ <g class="shift face">
71
+ <polyline points="32,42 52,58 32,74">
72
+ <animate attributeName="points" dur="5.2s" repeatCount="indefinite" keyTimes="0;0.977;0.9885;1" values="32,42 52,58 32,74;32,42 52,58 32,74;32,58 52,58 32,58;32,42 52,58 32,74"/>
73
+ </polyline>
74
+ <use href="#cursor"/>
75
+ </g>
76
+ </g>
77
+ </g>
78
+ <g transform="translate(332 183)" style="--delay: -0.4s">
79
+ <g class="bob">
80
+ <use class="stretch" href="#body" fill="#a07ef0"/>
81
+ <g class="shift face">
82
+ <polyline points="32,42 52,58 32,74">
83
+ <animate attributeName="points" dur="4.6s" repeatCount="indefinite" keyTimes="0;0.974;0.987;1" values="32,42 52,58 32,74;32,42 52,58 32,74;32,58 52,58 32,58;32,42 52,58 32,74"/>
84
+ </polyline>
85
+ <use href="#cursor"/>
86
+ </g>
87
+ </g>
88
+ </g>
89
+
90
+ <!-- Line under the ghosts -->
91
+ <line x1="60" y1="341" x2="452" y2="341" stroke="#565f89" stroke-width="10" stroke-linecap="round"/>
92
+ </svg>
@@ -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
+ # Development
9
+
10
+ ### Contents
11
+
12
+ - [Setup](#setup)
13
+ - [Platform Gems](#platform-gems)
14
+ - [Releasing](#releasing)
15
+ - [Running Hostty](#running-hostty)
16
+ - [Tests](#tests)
17
+ - [Linting](#linting)
18
+ - [Benchmark](#benchmark)
19
+ - [Pages](#pages)
20
+
21
+ ## Setup
22
+
23
+ 1. Install Zig 0.17. On macOS, run `brew install zig`.
24
+ 2. Run the setup script:
25
+
26
+ ```shell
27
+ bin/setup
28
+ ```
29
+
30
+ The setup script checks out libghostty-vt into `vendor/ghostty`, installs the gems, and builds the library into `vendor/libghostty`. Hostty loads the library from there when you run it from the repository.
31
+
32
+ Hostty needs Ruby 3.2 or later. Its runtime dependencies are ruby-nginx and ffi.
33
+
34
+ - After you change the libghostty-vt version in `vendor/ghostty`, run `bundle exec rake libghostty` to build it again.
35
+ - libghostty-vt 1.0 needs Zig 0.17. The build stops with an error on any other minor version.
36
+
37
+ ## Platform Gems
38
+
39
+ `bundle exec rake native:all` builds a gem with libghostty-vt inside for each platform: `arm64-darwin`, `x86_64-darwin`, `x86_64-linux-gnu`, and `aarch64-linux-gnu`. Zig builds the library for every platform from one machine. Use `native:<platform>` to build one, such as `bundle exec rake native:x86_64-linux-gnu`. The gems go into `pkg/`.
40
+
41
+ `bundle exec rake build` builds the gem without the library. That gem uses a libghostty-vt from the package manager of the system.
42
+
43
+ CI builds every platform gem on each push and keeps them as build artifacts, so a broken build shows before a release.
44
+
45
+ ## Releasing
46
+
47
+ 1. Change `Hostty::VERSION` in `lib/hostty/version.rb`.
48
+ 2. Merge the change into `main`.
49
+ 3. Publish a GitHub release from `main`, with a tag for the version.
50
+
51
+ The release starts the "Ruby Gem" workflow. It builds the four platform gems and the gem without the library, then pushes all of them to RubyGems and to GitHub Packages.
52
+
53
+ ## Running Hostty
54
+
55
+ Run hostty from the repository with your own config file:
56
+
57
+ ```shell
58
+ bundle exec exe/hostty --file path/to/.hostty.yml
59
+ ```
60
+
61
+ A config file of shell loops makes a quick sample, because it needs no server:
62
+
63
+ ```yaml
64
+ processes:
65
+ web: "i=0; while true; do i=$((i+1)); echo \"port $PORT, line $i\"; sleep 1; done"
66
+ jobs: "i=0; while true; do i=$((i+1)); echo \"port $PORT, line $i\"; sleep 3; done"
67
+ irb: "irb"
68
+ ```
69
+
70
+ ## Tests
71
+
72
+ ```shell
73
+ bundle exec rake test
74
+ ```
75
+
76
+ The tests use Minitest and run hostty through `Hostty::CLI`, the same entry point as `exe/hostty`:
77
+
78
+ | Directory | What it tests |
79
+ | --- | --- |
80
+ | `test/cli/` | Hostty end to end: the config, the domains, plain output, the tabs, and stopping. |
81
+ | `test/ghostty/` | The screen of each tab, which Hostty reads from libghostty-vt. |
82
+ | `test/support/` | Helpers for the tests above. |
83
+
84
+ - A fake stands in for ruby-nginx, so the tests never touch NGINX or `/etc/hosts`.
85
+ - The tab tests open a real pseudo-terminal and pass it to hostty as stdin and stdout. The test reads the output of hostty into libghostty-vt, the same library that hostty uses, so it checks the screen a user would see. It sends clicks and keys through the same pseudo-terminal.
86
+ - The tab tests wait for text on the screen, with a 5-second limit, instead of sleeping.
87
+
88
+ ## Linting
89
+
90
+ ```shell
91
+ bundle exec rake standard
92
+ ```
93
+
94
+ `bundle exec rake` runs the tests and Standard together.
95
+
96
+ ## Benchmark
97
+
98
+ ```shell
99
+ bin/bench 20
100
+ ```
101
+
102
+ The benchmark feeds 20 MB of each kind of generated log output through the screen of a tab, and prints the MB and lines read per second of CPU time. It then times one frame read at 80 by 24 and at 200 by 50. Run it before and after a change to `lib/hostty/ghostty/` to compare.
103
+
104
+ | Measure | Result |
105
+ | --- | --- |
106
+ | Plain log lines | About 1,900 MB/s, or 28.7 million lines a second |
107
+ | Colored Rails log lines | About 520 MB/s, or 6.2 million lines a second |
108
+ | Progress bar with carriage returns | About 920 MB/s, or 15 million lines a second |
109
+ | Frame read at 80 by 24 | 1.2 ms |
110
+ | Frame read at 200 by 50 | 7.4 ms |
111
+
112
+ The frame reads add a new line before each read, so every row of the screen changes. That is the slowest case for a frame read.
113
+
114
+ ## Pages
115
+
116
+ - [Architecture](./architecture.md): how hostty works inside.
117
+
118
+ ---
119
+
120
+ [← Return to Hostty](../../README.md)
@@ -0,0 +1,169 @@
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
+ # Architecture
9
+
10
+ ### Contents
11
+
12
+ - [Components](#components)
13
+ - [Startup](#startup)
14
+ - [Front Ends](#front-ends)
15
+ - [Process Lifecycle](#process-lifecycle)
16
+ - [The Tab Event Loop](#the-tab-event-loop)
17
+ - [The Terminal Emulator](#the-terminal-emulator)
18
+ - [Signals](#signals)
19
+
20
+ ## Components
21
+
22
+ ```mermaid
23
+ flowchart TD
24
+ cli["Hostty::CLI"] --> config["Hostty::Config"]
25
+ cli --> domains["Hostty::Domains"]
26
+ cli --> manager["Hostty::Manager"]
27
+ domains --> nginx[("ruby-nginx")]
28
+ manager --> front{"Front end"}
29
+ front --> plain["Hostty::Plain"]
30
+ front --> tui["Hostty::Tui"]
31
+ tui --> ghostty["Hostty::Ghostty"]
32
+ ghostty --> libghostty[("libghostty-vt")]
33
+ ```
34
+
35
+ | Namespace | Job |
36
+ | --- | --- |
37
+ | `Hostty::CLI` | Parses the options, picks the front end, and runs the steps in order. |
38
+ | `Hostty::Config` | Reads `.hostty.yml`, checks every setting, and gives each process its environment. |
39
+ | `Hostty::PortChooser` | Picks the port of each process, checks that it can open the port, and stops or moves on a clash. |
40
+ | `Hostty::Domains` | Adds each domain through ruby-nginx. |
41
+ | `Hostty::Manager` | Starts the processes, waits for exit events, and runs the [stop sequence](../features/stopping.md). |
42
+ | `Hostty::Plain` | The front end for [plain output](../features/plain-output.md). It runs each process on a pipe and prints its lines. |
43
+ | `Hostty::Tui` | The front end for [tabs](../features/tabs.md). It runs each process in a pseudo-terminal and draws the tabs. |
44
+ | `Hostty::Ghostty` | The [terminal emulator](../features/terminal-emulator.md) for each tab, through libghostty-vt. |
45
+ | `Hostty::Terminal` | The cells and styles that the tab renderer draws. |
46
+
47
+ ## Startup
48
+
49
+ ```mermaid
50
+ sequenceDiagram
51
+ actor Dev as Developer
52
+ participant CLI as Hostty::CLI
53
+ participant Domains as Hostty::Domains
54
+ participant Nginx as ruby-nginx
55
+ participant Manager as Hostty::Manager
56
+ participant Front as Front end
57
+
58
+ Dev->>CLI: hostty
59
+ CLI->>CLI: Read and check .hostty.yml
60
+ CLI->>Domains: add
61
+ loop Each process with a domain
62
+ Domains->>Nginx: add!(domain, port, ssl, ...)
63
+ Nginx-->>Dev: Install and sudo prompts, in the real terminal
64
+ end
65
+ CLI->>Manager: run
66
+ Manager->>Front: launch_for(process), once per process
67
+ Manager->>Manager: Start every process
68
+ Manager->>Front: wait
69
+ Front-->>Manager: Exit code, after a quit or a signal
70
+ Manager->>Manager: Stop every process
71
+ Manager-->>CLI: Exit code
72
+ ```
73
+
74
+ Hostty adds the domains before the manager starts, so a prompt from ruby-nginx always shows in the real terminal, before the tabs take it over.
75
+
76
+ ## Front Ends
77
+
78
+ `Hostty::Manager` does not know how a process shows its output. It asks the front end for two things:
79
+
80
+ - A launcher for each process. The launcher starts the process and returns its process ID.
81
+ - A wait, which returns when hostty should stop, with the exit code.
82
+
83
+ | Front end | Launcher | Wait |
84
+ | --- | --- | --- |
85
+ | `Hostty::Plain` | Runs the process on a pipe, in its own process group, with stdin from `/dev/null`. A thread reads each line and prints it with the process name. | Returns at the first exit event or signal. |
86
+ | `Hostty::Tui` | Runs the process in a pseudo-terminal, as the leader of its own session. | Runs the [tab event loop](#the-tab-event-loop) until you quit or a signal comes in. |
87
+
88
+ Both launchers make the process the leader of its own process group, so a signal to the group also reaches its children.
89
+
90
+ ## Process Lifecycle
91
+
92
+ ```mermaid
93
+ stateDiagram-v2
94
+ [*] --> Running: Manager starts the process
95
+ Running --> Exited: The process exits
96
+ Running --> Restarting: Click restart in a tab
97
+ Restarting --> Exited: TERM, then the process exits
98
+ Exited --> Running: Hostty restarts it
99
+ Exited --> Running: Click restart in a tab
100
+ Running --> Stopping: Hostty stops
101
+ Stopping --> [*]: TERM, then KILL after the timeout
102
+ Exited --> [*]: Hostty stops
103
+ ```
104
+
105
+ - A thread per process waits for its exit and puts an exit event on a queue.
106
+ - The same queue gets an event for each INT, TERM, and HUP signal.
107
+ - The queue also writes a byte to a pipe for each event, so the tab event loop can wait on the queue with `IO.select`.
108
+ - The manager tracks which processes still run from the exit events, so the stop sequence knows what to wait for.
109
+
110
+ ## The Tab Event Loop
111
+
112
+ ```mermaid
113
+ flowchart TD
114
+ select["IO.select on stdin, the event pipe,<br/>and every pseudo-terminal"] --> which{Which one is ready?}
115
+ which -- stdin --> input[Split the bytes into clicks, drags, wheel steps,<br/>Shift+Tab, Ctrl-C, and keys]
116
+ input --> act[Switch tabs, scroll, select and copy, restart, quit,<br/>or write the keys to the selected process]
117
+ which -- event pipe --> events[Mark exited processes,<br/>restart the ones that asked for it]
118
+ which -- pseudo-terminal --> output[Feed the output into<br/>the emulator of that tab]
119
+ act --> size[Check the window size]
120
+ events --> size
121
+ output --> size
122
+ size --> render{Did the screen change, and<br/>did 16 ms pass since the last frame?}
123
+ render -- yes --> draw[Draw the rows that changed]
124
+ render -- no --> select
125
+ draw --> select
126
+ ```
127
+
128
+ - One thread runs the loop. Only the exit waiters run on other threads.
129
+ - The loop redraws at most about 60 times a second. A redraw writes only the rows that changed since the last frame, in one write.
130
+ - On start, the loop switches your terminal to raw mode, the alternate screen, and mouse reporting with drags. On exit, it restores all three, even after an error.
131
+ - `Tui::Input` turns each mouse report into a `Tui::MouseEvent`. When the program in the selected tab turned on mouse reporting, events inside the tab go to the program. `Ghostty::Mouse` encodes them with the libghostty-vt mouse encoder, which follows the mouse mode and format that the program asked for. Without mouse reporting, a wheel step on the alternate screen becomes arrow keys, and on the main screen it scrolls the history.
132
+ - A drag in the output makes a `Tui::Selection` on the selected pane. On release, `Tui::Desktop` copies the text. A click on the URL in the tab bar also goes to `Tui::Desktop`, which opens the URL in the browser. The CLI takes the desktop as an argument, so the tests pass a fake one.
133
+ - The loop copies the application cursor keys mode and the bracketed paste mode of the selected tab to your terminal, so keys reach the process in the form it expects.
134
+ - The loop checks the window size on each pass, at least 4 times a second. On a change, it resizes every emulator and every pseudo-terminal, and each process gets SIGWINCH.
135
+
136
+ ## The Terminal Emulator
137
+
138
+ ```mermaid
139
+ flowchart LR
140
+ bytes["Process output bytes"] --> screen["Ghostty::Screen"]
141
+ screen --> lib[("libghostty-vt terminal")]
142
+ lib -- "replies such as the cursor position" --> pty["Pseudo-terminal"]
143
+ lib --> frame["Ghostty::Frame"]
144
+ frame --> cells["Rows of Terminal::Cell"]
145
+ cells --> renderer["Tui::Renderer"]
146
+ ```
147
+
148
+ | Part | Job |
149
+ | --- | --- |
150
+ | `Ghostty::Library` | The `ffi` bindings for the libghostty-vt functions that hostty calls. It loads the library from the gem first, then from `vendor/libghostty`, then from the system. |
151
+ | `Ghostty::Screen` | Owns one libghostty-vt terminal per tab. It writes the process output into the terminal, and reads the cursor, the modes, and the scrollback size. It scrolls the terminal to the offset that the tab asks for. |
152
+ | `Ghostty::Frame` | Reads the visible rows from a libghostty-vt render state into rows of `Terminal::Cell`. It skips a frame when nothing changed. |
153
+ | `Terminal::Cell` and `Terminal::Style` | A character with its width and its style. A style is a value that compares by its colors and attributes. |
154
+
155
+ - libghostty-vt has no drawing and no pseudo-terminal. Hostty owns both.
156
+ - `Ghostty::Frame` keeps one `Style` object for each set of colors and attributes, so `Tui::Renderer` writes a new SGR code only where the style changes.
157
+ - Reading a frame costs about 1 ms at 80 by 24 and about 8 ms at 200 by 50, when every row changed. Hostty reads a frame only for the selected tab, at most about 60 times a second.
158
+
159
+ The [terminal emulator](../features/terminal-emulator.md) page lists what works inside a tab.
160
+
161
+ ## Signals
162
+
163
+ - `Hostty::Manager` traps INT, TERM, and HUP while the processes run, and restores the previous handlers before it returns.
164
+ - In tabs, your terminal is in raw mode, so Ctrl-C arrives as a byte on stdin, not as INT. The tab event loop decides whether it goes to the process or quits hostty.
165
+ - Each process runs in its own process group, or its own session in tabs, so a Ctrl-C in your terminal never reaches the processes directly. Hostty stops them only through the [stop sequence](../features/stopping.md).
166
+
167
+ ---
168
+
169
+ [← Return to Development](./README.md)
@@ -0,0 +1,45 @@
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
+ # Features
9
+
10
+ ### Contents
11
+
12
+ - [Pages](#pages)
13
+ - [How a Run Goes](#how-a-run-goes)
14
+
15
+ ## Pages
16
+
17
+ - [Configuration](./configuration.md): the `.hostty.yml` file, ports, and environment variables.
18
+ - [Command Line](./command-line.md): the options and the exit codes.
19
+ - [Domains](./domains.md): local domains with NGINX and SSL.
20
+ - [Tabs](./tabs.md): the tab view, the keys, and the mouse.
21
+ - [Plain Output](./plain-output.md): the output of all processes together, for CI and pipes.
22
+ - [Stopping](./stopping.md): how hostty stops the processes.
23
+ - [Terminal Emulator](./terminal-emulator.md): which terminal features work inside a tab.
24
+
25
+ ## How a Run Goes
26
+
27
+ ```mermaid
28
+ flowchart TD
29
+ start([hostty]) --> config[Read .hostty.yml]
30
+ config --> domains[Add each domain]
31
+ domains --> mode{Are stdin and stdout<br/>both terminals?}
32
+ mode -- yes --> tabs[Show the processes in tabs]
33
+ mode -- "no, or the plain option" --> plain[Print the output of all processes together]
34
+ tabs --> quit[Ctrl-C twice, or TERM or HUP]
35
+ plain --> first[Ctrl-C, TERM, HUP,<br/>or the first process exit]
36
+ quit --> stop[Stop every process]
37
+ first --> stop
38
+ stop --> done([Exit])
39
+ ```
40
+
41
+ Hostty keeps the domains after it exits.
42
+
43
+ ---
44
+
45
+ [← Return to Hostty](../../README.md)
@@ -0,0 +1,46 @@
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
+ # Command Line
9
+
10
+ ### Contents
11
+
12
+ - [Usage](#usage)
13
+ - [Options](#options)
14
+ - [Exit Codes](#exit-codes)
15
+
16
+ ## Usage
17
+
18
+ ```shell
19
+ hostty [start] [options]
20
+ ```
21
+
22
+ `hostty` and `hostty start` do the same thing.
23
+
24
+ ## Options
25
+
26
+ | Option | What it does |
27
+ | --- | --- |
28
+ | `-f`, `--file FILE` | Read the processes from `FILE`. Defaults to `.hostty.yml`. |
29
+ | `-p`, `--port PORT` | Give the first process `PORT`. Defaults to 5000. See [Ports](./configuration.md#ports). |
30
+ | `-t`, `--timeout SECONDS` | Wait `SECONDS` for the processes to stop before hostty kills them. Defaults to 10. See [Stopping](./stopping.md). |
31
+ | `--plain` | Print the output of all processes together instead of in tabs. See [Plain Output](./plain-output.md). |
32
+ | `-v`, `--version` | Print the version. |
33
+ | `-h`, `--help` | Print the options. |
34
+
35
+ ## Exit Codes
36
+
37
+ | Code | When |
38
+ | --- | --- |
39
+ | 0 | You quit hostty, or hostty got TERM or HUP. |
40
+ | The exit code of the first process that exited | In [plain output](./plain-output.md), a process exited on its own. A process that a signal killed gives 128 plus the signal number, such as 143 for TERM. |
41
+ | 1 | The options, the config file, or a domain had an error, or the tabs could not load [libghostty-vt](./terminal-emulator.md#what-it-does). Hostty prints the error. |
42
+ | 130 | You pressed Ctrl-C while hostty added the domains. |
43
+
44
+ ---
45
+
46
+ [← Return to Features](./README.md)