foruiman 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0de0b215283d2c3dc89422aa9e6f6da235acf10f5ede3907afcf8e7c88dd9290
+  data.tar.gz: 81dfcdcfbc8d7ab445242fd5c07419192b6445e9caa3107fcdce5a2a027d914e
+SHA512:
+  metadata.gz: bb3cbdd6d6c38335bd5d6d4b467bbedec757cb2e534896b24d471c8b4275203d22cb22ec642fafe63410df21c1616322ae2e4616b0b26dce277959308f0092c5
+  data.tar.gz: 03db66ce62f3e21723aac3808791b2a027bb2ab497d415de11730661ff90b5150b82a0d7351ea2c156abc93be670e93a5b575933d06bf6a0fdcdcece35f7b517

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## Unreleased
+
+- Test Ruby 3.2, 3.3, 3.4, and 4.0 in a reusable CI workflow and keep the
+  development dependency set compatible with Ruby 3.2.
+- Add a tag-driven RubyGems trusted-publishing workflow gated by the full CI suite.
+- Make renderer row-width checks independent of the runner's terminal settings.
+
+## 0.1.2
+
+- Fix lowercase `r` on the `all` tab to restart every process; keep `R` available
+  from any tab and make the footer describe the selected restart scope.
+- Show the active Procfile in the header, including custom paths and working
+  directories, with filename priority in narrow terminals.
+- Follow the terminal's global theme through its ANSI palette and default
+  background. Use reverse-video selection for light, dark, and monochrome themes.
+- Verify group restarts with real keyboard input and process cleanup, and cover
+  Procfile titles, theme inheritance, and preserved child colors.
+
+## 0.1.1
+
+- Redesign the TUI with a forest palette, framed process navigation, selected-tab
+  backgrounds, status colors, aligned log columns, a scrollbar, and grouped help.
+- Support truecolor, 256 colors, and `NO_COLOR`; preserve child ANSI styles without
+  letting resets overwrite the interface background.
+- Adapt chrome and log metadata to terminal size, keep selected tabs visible,
+  and use the actual visible log height for scrolling and paging.
+- Include a static preview fixture and expand color, layout, and PTY coverage.
+
+## 0.1.0
+
+- Fork-derived MVP based on Foreman `f65ddba83932bd4670e014389d6e27ea1e20b469`.
+- Strict Procfiles, layered environments, and validated port allocation.
+- Independent process supervision, bounded log rings, and asynchronous restarts.
+- Terminal tabs, scrolling, Unicode-aware rows, and exception-safe restoration.
+- Automatic plain mode and process-group cleanup with TERM/KILL escalation.

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2012 David Dollar
+
+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,102 @@
+# Foruiman
+
+[![CI](https://github.com/Nuzair46/foruiman/actions/workflows/ci.yml/badge.svg)](https://github.com/Nuzair46/foruiman/actions/workflows/ci.yml)
+
+![Foruiman terminal interface](docs/terminal-preview.png)
+
+A modern Procfile runner with process tabs, bounded logs, scrolling, and isolated
+restarts. Foruiman is a fork of [Foreman](https://github.com/ddollar/foreman) and
+retains its MIT license.
+
+Requires Ruby 3.2+ and a POSIX system. CI covers Ruby 3.2, 3.3, 3.4, and 4.0 on Linux.
+
+## Install
+
+```sh
+gem install foruiman
+```
+
+## Run
+
+Create a `Procfile`:
+
+```procfile
+web: bundle exec rails server -p "$PORT"
+worker: bundle exec sidekiq
+css: yarn build:css --watch
+```
+
+Then start Foruiman:
+
+```sh
+foruiman
+```
+
+Useful commands:
+
+```sh
+foruiman start -f Procfile.dev  # use another Procfile
+foruiman start web              # run one process
+foruiman start --no-tui         # stream plain logs
+foruiman check                  # validate without starting
+foruiman --version
+```
+
+The TUI opens when stdin and stdout are terminals. Otherwise, Foruiman streams
+plain logs and exits when the processes finish. Processes run independently, and
+restarting one process does not interrupt the others.
+
+## Options
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `-f`, `--procfile FILE` | `Procfile` | Procfile to run |
+| `-d`, `--root DIR` | Current directory | Working directory |
+| `-e`, `--env FILE` | None | Additional environment file |
+| `--no-dotenv` | `.env` enabled | Skip `.env` |
+| `-p`, `--port PORT` | `5000` | Base port; entries increment by 100 |
+| `--log-lines N` | `10000` | Retained records per process and in `all` |
+| `--no-tui` | TUI when interactive | Force plain output |
+
+## Keyboard
+
+| Key | Action |
+| --- | --- |
+| Tab / Shift-Tab, Left / Right, `h` / `l` | Change tab |
+| `1`–`9`, `0` | Select a process or `all` |
+| Up / Down, `k` / `j` | Scroll |
+| PageUp / PageDown, Ctrl-U / Ctrl-D | Scroll a page |
+| Home / `g` | Jump to oldest retained log |
+| End / `G` / `f` | Follow new output |
+| Space | Pause or resume following |
+| `r` | Restart the selected process, or all from `all` |
+| `R` | Restart all processes |
+| `s` / `S` | Stop selected / stop all |
+| `?` / Escape | Toggle help / close help |
+| `q` / Ctrl-C | Stop processes and quit |
+
+## Documentation
+
+- [Rails usage](docs/RAILS.md)
+- [Architecture and supervisor API](docs/ARCHITECTURE.md)
+- [Differences from Foreman](docs/COMPATIBILITY.md)
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+bundle exec rubocop
+gem build foruiman.gemspec
+bundle exec ruby script/smoke_gem.rb
+```
+
+## Release
+
+Releases use RubyGems trusted publishing. Configure the publisher once with
+repository `Nuzair46/foruiman`, workflow `release.yml`, and environment `release`.
+
+To publish, update `lib/foruiman/version.rb` on `main`, open the
+[Release workflow](https://github.com/Nuzair46/foruiman/actions/workflows/release.yml),
+choose **Run workflow**, and select `main`. GitHub Actions runs the full CI suite,
+creates the version tag, and publishes the gem to RubyGems.org.

data/bin/foruiman

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "foruiman/cli"
+Foruiman::CLI.start(ARGV)

data/docs/ARCHITECTURE.md

@@ -0,0 +1,84 @@
+# Architecture and embedding
+
+`Procfile` retains Foreman's ordered parser/writer API with strict file validation.
+`Env` retains its quoting rules and adds a non-mutating precedence merge. `Process`
+wraps `/bin/sh -c` with a new process group, two output streams, and null stdin.
+`CLI < Thor` validates the full configuration before starting the engine.
+
+`Engine` owns registration, PID/group tracking, nonblocking pipes, child reaping,
+and lifecycle transitions. A single caller thread drives all mutations. Signal
+handlers only set a flag and wake a self-pipe. The loop reaps only its own direct
+children, services bounded reads in round-robin order, checks TERM deadlines, and
+starts pending replacements once old groups and pipes are finished. Group existence
+is tracked independently of leader status; Linux `/proc` distinguishes running
+members from orphan zombies awaiting the system reaper.
+
+```ruby
+require "foruiman"
+
+env = Foruiman::Env.load(root: Dir.pwd)
+engine = Foruiman::Engine.new(procfile: "Procfile", env: env, log_lines: 2_000)
+engine.on_event do |event|
+  # Types: output, started, restarting, stopping, exited, killed, failed.
+  # Fields: type, name, pid, status, record, message.
+  # Output records add sequence, stream, time, text, complete.
+end
+
+engine.run # install handlers, start all, loop, clean up, restore handlers; returns 0/1
+```
+
+For an embedded event loop:
+
+```ruby
+begin
+  engine.start_all                 # or engine.start("web")
+  engine.tick(timeout: 0.03)
+  engine.restart("web")            # asynchronous; peers keep running
+  engine.stop("worker")            # asynchronous
+  engine.shutdown                  # cancels replacements and requests group cleanup
+  engine.tick until engine.finished?
+ensure
+  engine.close                     # finishes cleanup, closes pipes; safe to repeat
+end
+```
+
+Call engine methods and event listeners on the driving thread; this is not a
+cross-thread messaging API. `run` handles INT/TERM/HUP and restores existing
+handlers. An embedding loop that drives `tick` directly owns its signal handling.
+`close` disconnects observers so a failed renderer/output consumer cannot prevent
+process cleanup. `term_timeout:` exists for deterministic embedded tests; CLI
+shutdown always uses five seconds. `state(name)` exposes lifecycle state for
+rendering; callers should not mutate it.
+
+`LogStore` uses per-process `Ring` instances and an aggregate `Ring`, each with O(1)
+append, eviction, record replacement, and identity lookup. Immutable `Data` records
+are shared. A partial record has one sequence identity; completing it replaces
+retained references without re-inserting an already evicted aggregate record.
+Sequence order represents first observation, not line completion time. Actual
+memory use depends on line length and ring capacity; retained text is bounded by
+approximately `(process_count + 1) * capacity * 16 KiB`, plus fixed per-stream and
+per-record overhead, with overlap shared between rings.
+
+`Output` bounds each stream, handles partial records, and takes style snapshots.
+`ANSI::Decoder` incrementally decodes UTF-8 and suppresses terminal controls;
+`ANSI::Styles` keeps bounded independent style properties across rows. A long line
+is split into completed records at the size limit.
+
+The TUI loads only in interactive mode. `Terminal` owns raw input and alternate
+screen restoration. `Keyboard` decodes fragmented key sequences. `State` stores
+selection/help/feedback, and each tab owns a `Viewport` anchored by record identity.
+`Renderer` composes framed process navigation, a log pane with a scrollbar, and a
+shortcut bar. Its shared log-height calculation keeps paging consistent with the
+responsive layout. `Text` measures graphemes through `unicode-display_width` and
+clips rows safely. `Theme` uses the terminal's ANSI palette, default foreground and
+background, and reverse-video selection, with a monochrome fallback. It does not
+read OS theme files or override palette entries; child SGR resets restore terminal
+defaults. The header uses the engine's `procfile_path` to identify the loaded file.
+`LogFormatter` aligns timestamps,
+process names, stream markers, and content. Complete frames reset styles at each row. `Application` connects input and lifecycle
+commands to the engine and limits drawing to 30 FPS. Resize handling reads current
+terminal dimensions each loop; it does not replace an application's WINCH handler.
+
+`Plain` prints completed records and runs to natural completion. `Diagnostics`
+keeps internal exceptions separate from process logs, using a private temporary
+file in interactive mode and stderr otherwise.

data/docs/ASSUMPTIONS.md

@@ -0,0 +1,23 @@
+# Inputs and implementation defaults
+
+The implementation workspace was empty. The RFC referenced by the supplied plan,
+its requested file list, and earlier preference selections were not present. The
+supplied Foreman-based MVP plan is the implementation contract available here.
+The missing RFC was requested during implementation; these choices fill the gaps:
+
+- Default command `start`; also `start PROCESS`, `check`, `version`, `help`.
+- Foreman's `-f`, `-d`, `-e`, `-p` aliases; `--log-lines`, `--no-tui`, `--no-dotenv`.
+- Default capacity 10,000 records per ring.
+- Process tabs in entry order, then `all`; select `all` initially.
+- `all` reserved as a process name to avoid an ambiguous aggregate tab.
+- Vim-style and arrow navigation, digits, `f`, Space, `r`/`R`, `s`/`S`, `?`, `q`.
+- Generated `PS=name.1`, as in Foreman; no other generated variables.
+- Relative file paths resolved against invocation directory or explicit `-d`.
+- Header whitespace after a Procfile colon is a separator; command-internal and
+  trailing whitespace is preserved.
+- 30 FPS maximum; 16 KiB records; 64 KiB total read budget per event-loop iteration.
+- No public repository URL is invented for the unpublished Foruiman project.
+
+See README for the actual public interface. These defaults can be reconciled with
+the original RFC when it becomes available; missing requirements are not claimed
+as verified.

data/docs/COMPATIBILITY.md

@@ -0,0 +1,27 @@
+# Intentional differences from Foreman
+
+Foruiman is a fork-derived MVP, not a drop-in replacement for every Foreman feature.
+
+| Area | Foruiman behavior |
+| --- | --- |
+| Identity | `foruiman` gem/executable, `Foruiman` namespace, version 0.1.2 |
+| Runtime | Ruby 3.2+, POSIX process groups; Linux CI |
+| CLI | Thor-based `start [PROCESS]`, `check`, `version`, and `help` |
+| Excluded features | No export, scaling/formation, `run`, `.foreman` YAML, custom shutdown timeout, forced color, or timestamp toggle |
+| Procfile validation | Reject malformed lines, duplicates, empty commands, and reserved `all`; report line numbers |
+| Working directory | Invocation directory unless `-d`; moving a Procfile does not change child cwd |
+| Environment | Optional `.env` then explicit env file; parent `ENV` stays untouched |
+| Ports | 5000 or `-p`, plus 100 per original entry; `PORT` in the environment is overridden |
+| Expansion | `/bin/sh -c` performs shell expansion; no Ruby string substitution |
+| Instances | Exactly one instance per entry; `PS=name.1` |
+| Failures | Independent process failures; peers keep running |
+| Restart | Stop only the affected group, wait for descendants and output, then replace |
+| Shutdown | TERM, five-second grace, KILL; track groups after leader exit; restore prior signal handlers |
+| Output | Separate stdout/stderr metadata; bounded logs and live partial records |
+| Terminal | Tabs, independent scroll/follow, restart and stop controls; no child stdin |
+| Plain exit | Wait for all processes; status 0/1; explicit orderly shutdown returns 0 |
+| Interactive exit | Remain open after all processes exit; quit explicitly |
+
+Commands needing a PTY, interactive child input, or background daemonization are
+outside this release. Remote process control, persistence across Foruiman sessions,
+search, horizontal scrolling, and log export are not provided.

data/docs/RAILS.md

@@ -0,0 +1,54 @@
+# Using Foruiman with Rails
+
+Install the locally built Foruiman gem as a development tool using the README's
+instructions. Keep it outside the Rails application's Gemfile when using a global
+development-tool installation. The Rails processes can still run under `bundle exec`.
+
+A typical `Procfile.dev`:
+
+```procfile
+web: bin/rails server -p "$PORT"
+worker: bundle exec sidekiq
+css: yarn build:css --watch
+```
+
+Include only entries used by your app. For a Vite application, replace the CSS entry
+with your project's foreground Vite command, for example `vite: bin/vite dev`.
+Use your app's existing port configuration for tools that do not read `PORT`.
+
+An optional `.env` in the Rails project root:
+
+```dotenv
+RAILS_ENV=development
+REDIS_URL=redis://localhost:6379/0
+```
+
+Keep secrets out of version control. Foruiman reads this file as assignments; it
+does not source it as a shell script.
+
+From the Rails root:
+
+```sh
+foruiman start -f Procfile.dev
+foruiman start -f Procfile.dev -p 3000
+```
+
+The second example assigns 3000 to `web`, 3100 to `worker`, and 3200 to `css`.
+Only programs that consume their generated `PORT` use those values. The base port
+is set with `-p`; a `PORT` assignment in `.env` does not set it.
+
+An optional `bin/dev`:
+
+```sh
+#!/bin/sh
+exec foruiman start -f Procfile.dev "$@"
+```
+
+Select the web tab and press `r` to restart Rails without interrupting the worker
+or asset watcher. On the `all` tab, `r` restarts all entries; `R` does so from any
+tab. The header shows the active Procfile. `q` or Ctrl-C stops all owned process
+groups, including grandchildren, before returning to the shell.
+
+Redirect output with `foruiman start -f Procfile.dev > development.log` to use plain
+mode. A failed worker will not stop Rails; plain mode finishes only after every
+entry exits or Foruiman receives a shutdown signal.

data/docs/UPSTREAM.md

@@ -0,0 +1,25 @@
+# Foreman provenance
+
+- Repository: https://github.com/ddollar/foreman
+- Revision: `f65ddba83932bd4670e014389d6e27ea1e20b469` (`update docs`)
+- Source archive: https://codeload.github.com/ddollar/foreman/tar.gz/f65ddba83932bd4670e014389d6e27ea1e20b469
+- License: MIT, Copyright (c) 2012 David Dollar; preserved verbatim in `LICENSE`.
+
+The initial local import copied `lib/foreman/{procfile,env,process,engine,cli}.rb`
+into the renamed namespace before applying the MVP changes. The Procfile
+reader/writer, environment assignment/quoting parser, process execution wrapper,
+ordered engine registration and lookup, pipe/signal approach, and Thor command
+foundation derive from that source. The supervisor loop and terminal components
+were refactored or written for Foruiman's independent process and log semantics.
+
+Relevant upstream test files are retained verbatim as review references in
+`docs/upstream/*_spec.rb.txt` (not part of the packaged gem). Active tests in
+`spec/foruiman/procfile_spec.rb`, `env_spec.rb`, and `process_spec.rb` adapt the
+applicable upstream examples to real temporary files and managed Ruby fixtures.
+The CLI and engine tests cover the new contract rather than upstream concurrency,
+export, command substitution, or stop-on-first-exit behavior.
+
+`docs/upstream/SHA256SUMS` records the original imported source/test checksums.
+Exporters, distribution code, scaling, and obsolete runtime compatibility code are
+not included in the distributed implementation. There is no runtime dependency
+on the Foreman gem and no claim of complete Foreman compatibility.

data/lib/foruiman/ansi.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Foruiman::ANSI
+  SGR = /\e\[[0-9;:]*m/
+  RESET = "\e[0m"
+
+  # A bounded style snapshot makes each retained row independently renderable.
+  class Styles
+    def initialize
+      @values = {}
+    end
+
+    def apply(sequence)
+      values = sequence.delete_prefix("\e[").delete_suffix("m").split(";")
+      values = ["0"] if values.empty?
+      until values.empty?
+        value = values.shift
+        code = value.to_i
+        case code
+        when 0 then @values.clear
+        when 1, 2 then @values[:intensity] = value
+        when 3 then @values[:italic] = value
+        when 4, 21 then @values[:underline] = value
+        when 5, 6 then @values[:blink] = value
+        when 7 then @values[:inverse] = value
+        when 8 then @values[:conceal] = value
+        when 9 then @values[:strike] = value
+        when 22 then @values.delete(:intensity)
+        when 23 then @values.delete(:italic)
+        when 24 then @values.delete(:underline)
+        when 25 then @values.delete(:blink)
+        when 27 then @values.delete(:inverse)
+        when 28 then @values.delete(:conceal)
+        when 29 then @values.delete(:strike)
+        when 30..37, 90..97 then @values[:foreground] = value
+        when 40..47, 100..107 then @values[:background] = value
+        when 38, 48 then color(code, value, values)
+        when 39 then @values.delete(:foreground)
+        when 49 then @values.delete(:background)
+        end
+      end
+    end
+
+    def prefix
+      @values.empty? ? "" : "\e[#{@values.values.join(';')}m"
+    end
+
+    private
+
+    def color(code, value, values)
+      if value.include?(":")
+        color = value
+      else
+        mode = values.shift
+        return unless %w[2 5].include?(mode)
+
+        count = mode == "2" ? 3 : 1
+        return if values.size < count
+
+        color = [value, mode, *values.shift(count)].join(";")
+      end
+      @values[code == 38 ? :foreground : :background] = color
+    end
+  end
+
+  # Incremental byte parser: only text, newlines, and SGR can leave this class.
+  # OSC (including clipboard), DCS, cursor controls, and other escapes are dropped.
+  class Decoder
+    def initialize
+      @state = :text
+      @escape = +""
+      @pending = +"".b
+    end
+
+    def feed(bytes, eof: false)
+      output = +"".b
+      bytes.each_byte { |byte| consume(byte, output) }
+      output = @pending + output
+      @pending = +"".b
+      unless eof
+        length = incomplete_suffix(output)
+        @pending = output.slice!(-length, length) if length.positive?
+      end
+      output.force_encoding(Encoding::UTF_8).scrub.delete("\u0080-\u009f")
+    end
+
+    private
+
+    def consume(byte, output)
+      case @state
+      when :text
+        case byte
+        when 27 then @state = :escape
+        when 9 then output << "    "
+        when 10, 32..126, 128..255 then output << byte
+        end
+      when :escape
+        @state = case byte
+                 when 91 then :csi
+                 when 93 then :osc
+                 when 80, 88, 94, 95 then :string
+                 when 32..47 then :intermediate
+                 else :text
+                 end
+        @escape.clear
+      when :intermediate
+        @state = :text if byte >= 48
+      when :csi
+        if byte.between?(64, 126)
+          output << "\e[#{@escape}m" if byte == 109 && @escape.match?(/\A[0-9;:]*\z/)
+          @state = :text
+        elsif @escape.bytesize < 96
+          @escape << byte
+        else
+          @state = :discard_csi
+        end
+      when :discard_csi
+        @state = :text if byte.between?(64, 126)
+      when :osc, :string
+        if byte == 27
+          @string_state = @state
+          @state = :string_escape
+        elsif byte == 7 && @state == :osc
+          @state = :text
+        end
+      when :string_escape
+        @state = byte == 92 ? :text : @string_state
+      end
+    end
+
+    def incomplete_suffix(bytes)
+      index = bytes.bytesize - 1
+      index -= 1 while index >= 0 && bytes.getbyte(index).between?(128, 191)
+      return 0 if index.negative?
+
+      lead = bytes.getbyte(index)
+      expected = case lead
+                 when 194..223 then 2
+                 when 224..239 then 3
+                 when 240..244 then 4
+                 else 1
+                 end
+      actual = bytes.bytesize - index
+      actual < expected ? actual : 0
+    end
+  end
+end

data/lib/foruiman/cli.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "thor"
+require "foruiman"
+require_relative "plain"
+require_relative "diagnostics"
+
+# Foreman's Thor command structure, reduced to the MVP surface.
+class Foruiman::CLI < Thor
+  map ["-v", "--version"] => :version
+  default_task :start
+  check_unknown_options!
+  remove_command :tree
+
+  class_option :procfile, type: :string, aliases: "-f", default: "Procfile", desc: "Procfile to read"
+  class_option :root, type: :string, aliases: "-d", desc: "Working directory (default: invocation directory)"
+  class_option :env, type: :string, aliases: "-e", desc: "Environment file layered after .env"
+  class_option :dotenv, type: :boolean, default: true, desc: "Load optional .env from working directory"
+  class_option :port, type: :string, aliases: "-p", default: "5000", desc: "Base port (increments by 100)"
+  class_option :log_lines, type: :string, default: "10000", desc: "Maximum records per process and in all"
+
+  def self.exit_on_failure?
+    true
+  end
+
+  desc "start [PROCESS]", "Run the Procfile with process tabs, or stream logs without a TTY"
+  method_option :tui, type: :boolean, default: true, desc: "Use the terminal interface when stdin and stdout are TTYs"
+  def start(process = nil)
+    engine = build_engine
+    engine.select(process) if process
+    interactive = options[:tui] && $stdin.tty? && $stdout.tty?
+    diagnostics = Foruiman::Diagnostics.new(interactive: interactive)
+    code = if interactive
+             require_relative "tui/application"
+             Foruiman::TUI::Application.new(engine).run
+           else
+             Foruiman::Plain.new(engine).run
+           end
+    exit(code)
+  rescue Foruiman::Error, SystemCallError => e
+    raise Thor::Error, e.message
+  rescue StandardError => e
+    diagnostics&.error(e)
+    warn "foruiman: #{e.message}#{" (details: #{diagnostics.path})" if diagnostics&.path}"
+    exit(1)
+  ensure
+    engine&.close
+    diagnostics&.close
+  end
+
+  desc "check", "Validate the Procfile, environment files, ports, and log capacity without starting processes"
+  def check
+    engine = build_engine
+    puts "valid Procfile (#{engine.process_names.join(', ')})"
+  rescue Foruiman::Error, SystemCallError => e
+    raise Thor::Error, e.message
+  ensure
+    engine&.close
+  end
+
+  desc "version", "Display Foruiman gem version"
+  def version
+    puts Foruiman::VERSION
+  end
+
+  private
+
+  def integer_option(name)
+    text = options.fetch(name).to_s
+    raise Foruiman::Error, "#{name.to_s.tr('_', '-')} must be a positive integer" unless text.match?(/\A[0-9]+\z/)
+
+    text.to_i
+  end
+
+  def build_engine
+    root = File.expand_path(options[:root] || Dir.pwd)
+    procfile = File.expand_path(options[:procfile], root)
+    file = File.expand_path(options[:env], root) if options[:env]
+    env = Foruiman::Env.load(root: root, file: file, dotenv: options[:dotenv])
+    Foruiman::Engine.new(procfile: procfile, root: root, env: env,
+                         port: integer_option(:port), log_lines: integer_option(:log_lines))
+  end
+end

data/lib/foruiman/diagnostics.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class Foruiman::Diagnostics
+  attr_reader :path
+
+  def initialize(interactive:, stderr: $stderr)
+    @interactive = interactive
+    @temporary = nil
+    @output = stderr
+  end
+
+  def error(exception)
+    if @interactive && !@temporary
+      require "tempfile"
+      @temporary = Tempfile.create(["foruiman-", ".log"])
+      @temporary.chmod(0o600)
+      @output = @temporary
+      @path = @temporary.path
+    end
+    @output.puts(exception.full_message(highlight: false))
+    @output.flush
+  end
+
+  def close
+    @temporary&.close
+  end
+end