foruiman 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 726795acd4c4991d3a924364ec484ca7ec1e7051b8c9a660a53e6b8ecd1759f8
-  data.tar.gz: 0c24bdd2fded37d051b8bb0e771991b0284893888a89b3a461662d2cc483dee4
+  metadata.gz: 5c7f857660af7989aab5c7175e501361ca523780f6eb14f65f7c1620da4040c9
+  data.tar.gz: ad726e87ac32a31a1eb07c3a6b9dc4e7eea5f34374e5395153b0c7a73f7831ad
 SHA512:
-  metadata.gz: 68b7fa94a095c09fc3ed636165ee88db37640d24aa2ede0b4d2c417680cf2655910b881ad2180116babc701949c91cc9f751f2e0b67f222d081f71ca9153a178
-  data.tar.gz: 22ec4c35cd32fd23d897ca2de19d72d5c219b53d0b86019f3fc3f562b3436371bd353ca5119aac2d4e1c559c68ddca37984c53b68e5e036cc12538e04f71321e
+  metadata.gz: 2256d813401208d3c672a391cc7ef8670f81cb4cd6ac9d84a22dc510fb612edc52863612d3d9310d84d9a4de05e239339c2a03b8a6ff87469257e81bc016e0c7
+  data.tar.gz: 4074ebafd99da6d35bdb99b2fa3aad0ce24eac452ff763e13180bb554db8135a23efdfb2cdf436da8fe001838f1db861445efa43a7e1be42a1f85ba95745c715

data/CHANGELOG.md

@@ -1,6 +1,24 @@
 # Changelog
 
-## Unreleased
+## 0.4.0
+
+- Forward USR1/USR2 to child process groups in both TUI and plain mode, preserving
+  application handlers and the supervisor's independent-process policy.
+- Fix inherited terminal stdin in plain mode while retaining descendant cleanup.
+- Validate ports after process selection, preserving each entry's original offset.
+- Allow a Procfile process named `all` with its own logs and controls, separate
+  from the aggregate tab.
+
+## 0.3.0
+
+- Add `.foreman` YAML defaults with explicit CLI overrides and validated options.
+- Add `run` for one-off commands and named Procfile entries, preserving terminal
+  input, argument boundaries, signals, and exit status.
+- Match Foreman's explicit environment-file replacement, comma-separated loading,
+  environment `PORT` fallback, and Procfile/root path handling. See the migration
+  notes for changes from 0.2.
+- Add `-t` / `--timeout` and `--exit-on all|any|failure`. Automatic group shutdown
+  preserves the triggering exit code and cleans up descendants and pending restarts.
 
 ## 0.2.0
 

data/README.md

@@ -38,6 +38,8 @@ Useful commands:
 foruiman start -f Procfile.dev  # use another Procfile
 foruiman start web              # run one process
 foruiman start --no-tui         # stream plain logs
+foruiman run bin/rails console  # one-off command with the app environment
+foruiman start --exit-on any    # stop the group when a process exits
 foruiman check                  # validate without starting
 foruiman --version
 ```
@@ -54,18 +56,31 @@ interrupts the selected process. Debugger tab completion is not forwarded.
 Press `s` to stop the selected process, or all processes from `all`; on a stopped
 process tab, `s` starts it again.
 
+The aggregate `all` tab uses shortcut `0`. A process named `all` has its own
+numbered tab and independent controls. USR1 and USR2 sent to Foruiman are forwarded
+to every child process group for application-defined handling.
+
+In plain mode, children inherit stdin, including terminal input. Multiple children
+reading stdin share that stream; use TUI input controls to target one process.
+
 ## 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 |
+| `-d`, `--root DIR` | Procfile directory | Working directory |
+| `-e`, `--env FILES` | `.env` | Comma-separated files, loaded in order instead of `.env` |
 | `--no-dotenv` | `.env` enabled | Skip `.env` |
-| `-p`, `--port PORT` | `5000` | Base port; entries increment by 100 |
+| `-p`, `--port PORT` | Environment `PORT`, then `5000` | Base port; entries increment by 100 |
+| `-t`, `--timeout SECONDS` | `5` | Grace period before forced shutdown |
+| `--exit-on all\|any\|failure` | `all` | Keep peers running, stop on any exit, or stop on failure |
 | `--log-lines N` | `10000` | Retained records per process and in `all` |
 | `--no-tui` | TUI when interactive | Force plain output |
 
+Set defaults in a `.foreman` YAML file in the invocation directory; CLI flags
+override them. See [compatibility and migration notes](docs/COMPATIBILITY.md) for
+path rules, supported settings, and changes from 0.2.
+
 ## Keyboard
 
 | Key | Action |
@@ -105,7 +120,9 @@ bundle exec ruby script/smoke_gem.rb
 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
+To publish, update `lib/foruiman/version.rb` and `CHANGELOG.md`, then run
+`bundle install` to update the version in `Gemfile.lock`. Commit all three files
+to `main`; CI requires the lockfile to match the gem version. 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/docs/ARCHITECTURE.md

@@ -3,11 +3,20 @@
 `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 configurable stdin.
-`CLI < Thor` validates the full configuration before starting the engine.
+The shell catches USR1/USR2 while waiting so group forwarding does not kill the
+wrapper ahead of a signal-aware application. Executed programs receive normal
+signal dispositions and can install their own handlers.
+`CLI < Thor` validates configuration and selected port allocations before opening
+the TUI or starting children. `check` validates every allocation. Original Procfile
+offsets survive selection; embedded `start` validates its entire batch before
+launching any child, and `restart` validates before changing process state.
+`Configuration` safely loads `.foreman` defaults, merges explicit CLI values,
+resolves Foreman-compatible paths and environments, and validates numeric options.
+`run` uses `exec` for one-off commands with direct terminal IO and exact exit status.
 
 `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
+handlers only queue the signal 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
@@ -44,15 +53,25 @@ 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.
+cross-thread messaging API. `run` handles INT/TERM/HUP shutdown, forwards USR1/USR2
+to owned groups, 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
+process cleanup. `term_timeout:` controls the shutdown grace period (CLI `-t`,
+default five seconds). `exit_on: :all` retains independent processes; `:any` or
+`:failure` requests group shutdown after a qualifying natural exit and preserves
+its exit code. Intentional stops/restarts do not trigger the policy. `state(name)` exposes lifecycle state for
 rendering; callers should not mutate it.
 
-Children inherit the configured input stream in plain and embedded use. Before
-startup, `manage_input!` gives each child a dedicated pseudo-terminal while the
+Children inherit the configured input stream in plain and embedded use. For a
+terminal input stream, `Process` forks, calls `setsid`, and execs the shell so reads
+do not stop with SIGTTIN in a background group of the supervisor's session. The
+child keeps its inherited terminal descriptor and its own process group; a pipe
+reports exec failures synchronously. This does not give the child a controlling
+terminal for `/dev/tty` or shell job control. Multiple inherited readers compete
+for the same input. Nonterminal input keeps the ordinary `spawn` path.
+
+Before startup, `manage_input!` gives each child a dedicated pseudo-terminal while the
 caller retains the real terminal; `write_input(name, bytes)` forwards input,
 `interrupt_process(name)` sends SIGINT to that process group, and `resize_inputs` keeps
 the pseudo-terminals sized with the UI. The TUI uses this mode so watch commands
@@ -65,7 +84,10 @@ line erasure before recording child output; screen controls remain suppressed.
 
 `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
+are shared. `logs.all` or `logs[:all]` accesses the aggregate; `logs["all"]` accesses
+a process actually named `all`. The TUI uses symbol `:all` for aggregate state and
+string names for processes, with `State#aggregate?` defining control scope.
+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

data/docs/ASSUMPTIONS.md

@@ -9,7 +9,8 @@ The missing RFC was requested during implementation; these choices fill the gaps
 - 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.
+- The aggregate tab has a separate internal identity, so `all` is also a valid
+  process name. This replaces the original reserved-name assumption.
 - 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`.

data/docs/COMPATIBILITY.md

@@ -1,26 +1,85 @@
 # Intentional differences from Foreman
 
-Foruiman is a fork-derived MVP, not a drop-in replacement for every Foreman feature.
+Foruiman supports common Foreman development workflows. It is not a drop-in
+replacement for every Foreman feature.
+
+See the [2026-09-27 compatibility audit](FOREMAN_AUDIT.md) for issue-backed gaps,
+direct comparisons with Foreman 0.90.0, and the implementation scope for compatible
+development workflows in this TUI. Exporters, the Foreman Ruby API, older
+runtimes, and exact legacy presentation are excluded from that work. Its
+modernization assessment recommends retaining consistent app-root execution,
+strict configuration/env-file validation, and meaningful TUI options. The four
+selected improvements are implemented in the unreleased changes below; the audit
+preserves the original findings separately from their implementation status.
 
 | Area | Foruiman behavior |
 | --- | --- |
-| Identity | `foruiman` gem/executable, `Foruiman` namespace, version 0.2.0 |
+| Identity | `foruiman` gem/executable, `Foruiman` namespace, version 0.3.0 |
 | 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 |
+| CLI | Thor-based `start [PROCESS]`, `run COMMAND [ARGS...]`, `check`, `version`, and `help` |
+| Excluded features | No export, scaling/formation, forced color, or timestamp toggle |
+| Procfile validation | Reject malformed lines, duplicates, and empty commands; report line numbers. A process named `all` is valid |
+| Working directory | Procfile directory unless `-d`; explicit `-f` and `-e` paths resolve from invocation |
+| Environment | Explicit `-e file1,file2` replaces default `.env` loading; later files win; parent `ENV` stays untouched |
+| Ports | `-p` or `.foreman` port, then loaded `PORT`, then 5000; plus 100 per original entry. `start PROCESS` validates only that allocation; `check` validates all |
 | 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 |
+| Failures | Independent by default; `--exit-on any` stops on any natural exit, `failure` only on an unsuccessful exit |
 | 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 |
+| Shutdown | TERM, configurable `-t` grace (default five seconds), KILL; track groups after leader exit; restore prior signal handlers |
+| Signals | USR1/USR2 reach every owned process group; applications choose how to handle them. INT/TERM/HUP request orderly shutdown |
 | Output | Separate stdout/stderr metadata; bounded logs and live partial records |
-| Terminal | Tabs, independent scroll/follow, restart, start/stop, and selected-process input controls |
-| Plain exit | Wait for all processes; status 0/1; explicit orderly shutdown returns 0 |
-| Interactive exit | Remain open after all processes exit; quit explicitly |
+| Terminal | Tabs, independent scroll/follow, restart, start/stop, and selected-process input controls; aggregate `0: all` is separate from a process named `all` |
+| Plain stdin | Inherited stdin supports pipes, terminal line input, raw reads, and EOF; concurrent readers share the stream |
+| Plain exit | Default status 0/1; automatic group shutdown preserves its triggering exit code (128 + signal for a signal exit); explicit orderly shutdown returns 0 |
+| Interactive exit | Remain open after all processes exit by default; automatic shutdown policies close the TUI after cleanup |
+
+## Configuration and paths
+
+Like Foreman, `.foreman` is read from the invocation directory. Use long option
+names; CLI flags override YAML values. Supported keys are `procfile`, `root`, `env`,
+`port`, `timeout`, `dotenv`, `tui`, `log-lines`, and `exit-on` (underscores also work).
+Unsupported keys, including `formation`, produce an error instead of being ignored.
+YAML object tags and aliases are not supported.
+
+```yaml
+procfile: Procfile.dev
+port: 3000
+timeout: 10
+exit-on: any
+```
+
+An explicit `-f` path is relative to invocation, even when `-d` is supplied. Without
+`-f`, the Procfile is `<root>/Procfile`. Without `-d`, child commands run in the
+Procfile's directory. Default `.env` loading follows Foreman's CLI: use the explicit
+`-d` directory when supplied, otherwise the invocation directory. An inferred root
+from `-f` does not move the default `.env` lookup. Explicit `-e` paths always resolve
+from invocation. `--no-dotenv` disables only default `.env` loading.
+
+## One-off commands
+
+`foruiman run bin/rails console` uses the same environment-file rules and passes
+stdin, stdout, and stderr directly to the command. No Procfile is required. A
+single argument matching a Procfile entry runs that entry's shell command.
+Other commands retain their exact argument boundaries. For shell operators, use
+`foruiman run sh -c 'command1 && command2'`. Put Foruiman options before the command;
+options after the command belong to that command.
+
+`run` replaces Foruiman with the command, preserving signals and exit status. It
+does not generate per-process `PORT` or `PS` values or open the TUI.
+
+## Migrating from 0.2
+
+- `-e custom.env` now replaces `.env`. Use `-e .env,custom.env` to retain layering.
+- Environment `PORT` now selects the base port. Use `-p 5000` to retain the old default.
+- A nested `-f` changes the default child working directory. Add `-d .` to keep
+  invocation as the working directory. With `-d app`, an old `-f config/Procfile.dev`
+  becomes `-f app/config/Procfile.dev` when that file lives inside `app`.
+- A `.foreman` file now supplies defaults. Remove unsupported keys before using it.
+
+Use `--exit-on any` for Foreman's stop-on-first-exit behavior. Intentional TUI
+stops and restarts do not trigger that policy. Exact Foreman log formatting and
+its Ruby embedding API remain outside compatibility.
 
 Full-screen child terminal applications and background daemonization are outside
 this release. Remote process control, persistence across Foruiman sessions,

data/docs/FOREMAN_AUDIT.md

@@ -0,0 +1,297 @@
+# Foreman compatibility audit — 2026-09-27
+
+**Scope: Foreman development workflows in a TUI Procfile runner.** The target
+is to reuse Procfiles, environment files, applicable `.foreman` settings, and
+`start` / `run` commands on Foruiman's supported Ruby/POSIX platforms. The TUI's
+independent processes, restarts, input controls, bounded logs, and presentation
+remain intentional behavior.
+
+**Original modernization recommendation:** drop three of the nine proposed ports in
+full, simplify two others, and treat formation as an optional product feature.
+Prioritize signal forwarding, working terminal stdin, and selected-process port
+validation; removing the process-name collision with `all` is a useful follow-up.
+The table below assesses all nine items individually.
+
+## Implementation status
+
+The selected work is implemented in the unreleased changes:
+
+- **1 — USR1/USR2:** forward to owned process groups in TUI and plain mode, including
+  descendants. Signal-aware applications and their waiting shell wrappers stay
+  alive; applications without a handler retain the default signal behavior.
+- **2 — Plain terminal stdin:** children can read lines, raw bytes, and EOF from
+  inherited terminal stdin. Isolated child sessions preserve process-group cleanup.
+  This supplies terminal IO, not a new controlling terminal or shell job control.
+- **6 — Process named `all`:** process logs, input, and controls are separate from
+  the aggregate tab, which keeps shortcut `0`.
+- **8 — Selected ports:** validate only the selected process at startup without
+  changing its original +100 offset. Whole-app startup and `check` still reject
+  invalid allocations before launching children. Positive base ports remain required.
+
+Regression coverage is in [terminal integration](../spec/integration/terminal_spec.rb),
+[supervisor integration](../spec/integration/supervisor_spec.rb),
+[CLI](../spec/foruiman/cli_spec.rb), and [TUI](../spec/foruiman/tui_spec.rb) specs.
+The remaining recommendations retain existing behavior or defer formation.
+
+The baseline measurements and original assessment below describe the pre-fix
+version. They are preserved as audit evidence, not claims of current failures.
+
+## Baseline and evidence
+
+- Foruiman: commit `a2f8ebb3a81e4f026284f78c5a1bd615f3f3068e`, version 0.3.0.
+- Foreman: installed gem 0.90.0, also the latest version returned by the
+  [RubyGems API](https://rubygems.org/api/v1/versions/foreman/latest.json) at audit time.
+- Upstream `main`: [`f65ddba83932bd4670e014389d6e27ea1e20b469`](https://github.com/ddollar/foreman/tree/f65ddba83932bd4670e014389d6e27ea1e20b469),
+  matching our [recorded import](UPSTREAM.md).
+- Execution environment: Linux, MRI Ruby 3.4.5. The existing RSpec suite passed:
+  **149 examples, 0 failures**, seed 59308.
+- Ran **56 paired CLI probes**, plus **one paired controlling-terminal input
+  reproduction**. Each runner used a fresh temporary directory. Probes captured
+  stdout, stderr, exit status, termination signal, and timeouts. Some probes
+  deliberately used invalid input; this is not a compatibility percentage.
+- Retrieved all **442 upstream issues: 53 open, 389 closed**, excluding PRs.
+  Screened titles, read all open issue bodies and relevant closed reports, and
+  followed selected resolution comments. This is not a claim to have reproduced
+  every historical report or read every comment.
+- The [Foruiman tracker](https://github.com/Nuzair46/foruiman/issues) contained no
+  standalone issues and five closed PRs. [PR #5](https://github.com/Nuzair46/foruiman/pull/5)
+  explicitly excluded formation, export, exact log formatting, and USR forwarding.
+
+The [Foreman manual](https://ddollar.github.io/foreman/), pinned implementation,
+actual 0.90.0 behavior, and issue history were compared. An open issue is evidence
+of a reported problem or requested feature, not proof that it still exists in
+0.90.0. Historical Foreman releases also differ from each other.
+
+The runtime comparison uses the [upstream CI matrix](https://github.com/ddollar/foreman/blob/f65ddba83932bd4670e014389d6e27ea1e20b469/.github/workflows/ci.yml)
+and [Foreman CLI/engine source](https://github.com/ddollar/foreman/tree/f65ddba83932bd4670e014389d6e27ea1e20b469/lib/foreman),
+not an assumption that an unrestricted gemspec proves every Ruby version works.
+
+## Original modernization assessment of the nine items
+
+The goal is a predictable development supervisor with a TUI. Existing useful
+workflows matter; reproducing incidental parsing and CLI behavior is optional.
+Dropping a port means retaining a documented difference, not claiming parity.
+
+| Original item | Recommendation | Reason and intended contract |
+| --- | --- | --- |
+| 1. USR1/USR2 forwarding | **Keep the fix.** | These signals currently terminate the shared supervisor instead of reaching children. The TUI does not replace application-defined signal handling. Forward the signals without closing the supervisor; do not reinterpret them as TUI restart shortcuts. [Engine](../lib/foruiman/engine.rb), upstream [#673](https://github.com/ddollar/foreman/issues/673). |
+| 2. Terminal stdin in `--no-tui` | **Keep the fix.** | A supported execution mode should allow children to read its controlling terminal. Correct the process-group/input interaction while preserving descendant cleanup. This is a correctness problem, not a legacy UI preference. [Process spawning](../lib/foruiman/process.rb). |
+| 3. Formation, scaling and exclusions | **Defer full formation unless it is a product requirement.** | Multiple instances and startup exclusions remain useful capabilities; they are not obsolete just because the interface has tabs. They add instance identity, controls and port allocation work. Existing `start PROCESS` covers a single selected process. TUI stop buttons are not a substitute for excluding a process before it starts. If `-m` is implemented, preserve its counts/exclusions and default-zero semantics rather than silently changing the meaning of an existing flag. Upstream [#398](https://github.com/ddollar/foreman/issues/398). |
+| 4. Reusing `.foreman` defaults | **Keep supported settings; drop the proposed permissiveness.** | Continue honoring supported env/root/port/timeout defaults and CLI overrides. There is no need to silently accept export-only `app`, `user`, `log`, `run`, or `template` keys, or treat mistyped/null values as absent. Retain clear validation and document removing unsupported keys during migration. This avoids suggesting a setting has an effect when it does not. [Configuration](../lib/foruiman/configuration.rb). |
+| 5. Arbitrary `run` working directory | **Do not port Foreman's special case.** | Keep the current consistent application-root cwd for named and arbitrary commands. `-d` has one meaning, and relative commands work relative to the configured app. Foreman's arbitrary-command invocation-cwd behavior is a migration difference, not a correctness requirement for this product. Use `run -d . ...` when invocation cwd is wanted; this also selects invocation-root default `.env` lookup. An explicit `-e` can preserve a different env-file choice. [CLI](../lib/foruiman/cli.rb). |
+| 6. Valid process name `all` | **Keep as a useful design improvement, after correctness fixes.** | An aggregate tab need not prevent a real process from being named `all`. Use a separate internal identity for the aggregate view. This removes an unnecessary UI/name collision without adopting permissive parsing for malformed or duplicate entries. The current explicit reserved-name error remains an acceptable documented migration restriction until changed. [Procfile](../lib/foruiman/procfile.rb). |
+| 7. Legacy presentation-option acceptance | **Do not add acceptance-only compatibility flags.** | Do not add `-c`, `--color`, or `--timestamp` switches solely to accept and ignore them. The TUI owns presentation. Keep a clear unsupported-option error; if color/timestamp control is later useful in the plain fallback, implement it as a real feature with documented behavior. |
+| 8. Port allocation for selected processes | **Fix selection validation; defer port-zero support.** | `start web -p 65500` should not fail because an unselected worker would receive 65600. Validate selected instances and preserve original offsets. Do not port arbitrary `to_i` coercion. Base port zero is a separate allocation policy: the +100 rule would give the second type 100, so accepting zero is not an automatic-port policy for the whole app. Keep positive-port validation until zero has an explicit use case and defined semantics. [Engine](../lib/foruiman/engine.rb). |
+| 9. Environment-file option edge cases | **Do not port permissive list parsing.** | Keep rejecting `-e ''` and `-e custom.env,`. Use the existing `--no-dotenv` to disable default loading, and `-e custom.env` for a nonempty list. `--no-dotenv` still permits explicit `-e` files, including a configured `.foreman` env setting; remove that explicit setting too if the intent is to load no file. Preserve precedence and valid multiple-file support. [Configuration](../lib/foruiman/configuration.rb). |
+
+This leaves **three correctness fixes**, **one process-name improvement**, and
+**formation as a separate optional feature**. The other recommendations preserve
+current behavior and require clear migration documentation, not porting code.
+
+## Differences excluded from this version's compatibility work
+
+The wider exclusions below remain in addition to the recommendations above.
+They do not imply that missing features exist or that an observed difference was
+incorrect.
+
+| Exclude | Treatment |
+| --- | --- |
+| Exporters and custom export templates | No systemd, upstart, launchd, runit, inittab, bluepill, daemon or supervisord export work. Keep clear errors for unsupported config keys and document removing them during migration. |
+| Ruby embedding/extension API and old executable identity | Keep the `Foruiman` namespace and `foruiman` gem/executable. No `Foreman::*` adapter, replacement gem identity, or requirement to satisfy existing `gem list -i foreman` checks. Changing `bin/dev` to invoke Foruiman is part of migration. |
+| Older Ruby and native Windows support | Keep the existing Ruby 3.2+ and POSIX scope. Platform expansion is separate work. Linux tests do not establish macOS correctness; verify any platform-specific claim separately. |
+| Exact log format, raw-log transport and cross-stream ordering | Tabs, timestamps, stream labels, lifecycle text, colors and separate stdout/stderr metadata can differ. TUI control-sequence interpretation, bounded records and long-line splitting are intentional. Byte-identical plain output, raw JSON transport and exact merged ordering are not compatibility goals for this version. |
+| Default stop-on-first-exit and aggregate exit status | Keep independent processes, isolated restarts, remaining open after children exit, aggregate 0/1 completion status, and explicit user quit returning 0. Retain the existing `--exit-on any` option and verify its documented triggering-code behavior. There is no unique Foreman-style triggering process under the independent default. |
+| No-argument help, `tree`, and exact diagnostics | Keep default `start`, full-screen interaction, shortcuts, and current help/error wording and streams. Do not restore `tree` solely for Thor parity. |
+| Permissive parsing and `check` behavior | Keep clear validation of malformed/duplicate/empty entries and the broader environment/port checks documented for `check`. The `all` name collision is resolved without relaxing those checks. |
+| Upstream expansion and signal-status quirks | Keep shell quoting/variable boundaries and direct `run` exec. Do not copy substring replacement that expands single-quoted variables or corrupts `$FOOBAR`, return success for a signaled command just because upstream does, or reject arbitrary `run` solely because an unrelated Procfile is empty. |
+| Production init, escaped daemons and unrelated feature requests | No PID 1 init guarantee, daemon management, remote sessions, automatic reload/sequencing, or features belonging to Puppet Foreman/node-foreman. Keep cleanup of owned development process groups. |
+
+## Important details from the reproductions
+
+**Terminal input is a real regression, independent of the TUI.** The stdin
+reproduction used a controlling terminal created by `PTY.spawn`, not just a PTY
+file descriptor. The child wrote `READY`, then called `STDIN.gets`. Foreman
+printed `GOT:hello` and exited normally. Foruiman's background process group
+stopped on terminal input; after two seconds the harness requested shutdown and
+the configured timeout escalated to KILL. Existing terminal specs mostly use
+`PTY.open` plus `Process.spawn`, which does not establish that slave as the
+child's controlling terminal. Add a controlling-terminal regression test before
+changing process group or input handling.
+
+**Excluded evidence: exact signal exit parity.** For a direct
+`ruby child.rb` that sends itself TERM, Foreman returned 0. Foruiman's extra shell
+reported 143 internally and the default policy returned 1. For `run ruby
+child.rb`, Foreman returned 0 while Foruiman itself was terminated by TERM
+(`Process::Status#termsig == 15`). A shell may display 143 for a signaled command,
+but wait-status consumers can distinguish it from an ordinary exit 143. Foreman
+0.90.0's treatment of a directly signaled child is an upstream quirk, not a
+recommendation to hide failures.
+
+**Excluded evidence: upstream command-expansion quirks.** With
+`.env` containing `FOO=hello` and `FOOBAR=world`:
+
+| Procfile command | Foreman child output | Foruiman child output |
+| --- | --- | --- |
+| `printf '%s\n' '$FOO'` | `hello` | `$FOO` |
+| `printf '%s\n' "$FOOBAR"` | `helloBAR` | `world` |
+
+With `FOO=$(printf expanded)` and `printf '%s\n' "$FOO"`, Foreman printed
+`expanded`; Foruiman printed the literal `$(printf expanded)`. Foruiman's normal
+shell semantics are retained for this TUI scope; this difference is documented
+and is not an implementation task.
+
+**Port limits can reject an otherwise usable selected process.** This is not
+only about invalid port strings: 65500 is valid for `web`, but validation of an
+unselected second entry rejects the entire command. Formation implementation
+would need to allocate selected instances without renumbering their original
+Procfile positions. The selection-validation bug can be fixed independently of
+formation support.
+
+**No signal orphan was observed in the dedicated USR1 cleanup probe.** The
+supervisor still terminated instead of forwarding. Report that confirmed
+failure without assuming every such termination leaves a live child behind.
+
+## Minimal reproductions
+
+Use a fresh directory for each fixture. Run the listed arguments with Foreman
+0.90.0 and then Foruiman 0.3.0. Use `--no-tui` on Foruiman when inspecting a short-lived command without
+the persistent TUI. Compare process behavior, cwd, environment and argument
+acceptance. These reproduce the original findings, including differences now
+recommended for retention; they are not all failing acceptance criteria. Exact
+log text and aggregate status under independent supervision are outside the
+scoped comparison.
+
+| Fixture | Command arguments | Observed difference |
+| --- | --- | --- |
+| `Procfile`: `web: echo hello` | `start -m web=2` | Two instances versus unknown switch. |
+| Same Procfile; `.foreman`: `app: demo` | `start` | Runs versus unsupported config key. |
+| Create empty `app/` directory; no Procfile | `run -d app ruby -e 'puts Dir.pwd'` | Invocation directory versus `app/`. |
+| `Procfile`: `all: echo hello` | `start` | Runs versus reserved-name error. |
+| `Procfile`: `web: echo hello` | `start -c` or `start --no-timestamp` | Accepted versus unknown switch. |
+| `Procfile`: `web: echo hello`, then `worker: echo worker` on the next line | `start web -p 65500` | Runs web versus rejecting an unselected worker's port. |
+| `.env`: `FOO=file`, with inherited `FOO=parent` | `run -e '' ruby -e 'puts ENV["FOO"]'` | Prints parent versus rejecting empty env option. |
+
+For terminal input, create `reader.rb`:
+
+```ruby
+STDOUT.sync = true
+puts "READY"
+puts "GOT:#{STDIN.gets}"
+```
+
+Use `web: ruby reader.rb` as the Procfile. In a real foreground terminal, run
+`foreman start -t 0.1`, type `hello` and Enter after READY. Repeat with
+`foruiman start --no-tui -t 0.1`. The first prints `GOT:hello`; the second stops
+the reader. Ctrl-C requests shutdown. A pipe-fed stdin test will not reproduce
+this controlling-terminal problem.
+
+For signal forwarding, create `signals.rb`:
+
+```ruby
+STDOUT.sync = true
+Signal.trap(:USR1) { puts "RECEIVED USR1" }
+Signal.trap(:USR2) { puts "RECEIVED USR2" }
+puts "READY"
+sleep
+```
+
+Use `web: ruby signals.rb` as the Procfile. After READY, send `kill -USR1 PID`
+from another terminal to the **supervisor's** PID. Foreman prints the forwarded
+message and remains running; Foruiman terminates. Repeat in a fresh invocation
+for USR2. Terminate a surviving Foreman supervisor normally after observing it.
+
+## Behaviors already supported
+
+The paired probes confirmed common environment precedence: inherited variables
+are available, `.env` overrides them, explicit `-e first,last` replaces the
+default `.env`, and later explicit files win. CLI port overrides `.foreman`,
+loaded `PORT` and inherited `PORT`. Selecting the second process retains its
+original +100 port offset and `PS=worker.1`.
+
+Nested `-f` moves the supervised/named-command working directory while default
+`.env` still comes from invocation unless `-d` is supplied. Named `run` uses the
+Procfile root. Arbitrary `run` works without a Procfile, preserves argument
+boundaries and child switches, and preserves ordinary nonzero exit codes.
+
+The existing passing suite additionally covers quoted/escaped environment
+values, CRLF, missing explicit environment files, stdin pipes, shutdown timeout
+escalation, bounded log retention, cleanup of descendants in managed groups,
+isolated restarts, and TUI terminal restoration. These are useful tests, but
+they assert Foruiman's own contract; passing them is not a Foreman conformance
+certificate.
+
+## Issue-history conclusions
+
+The most useful closed reports are [#673](https://github.com/ddollar/foreman/issues/673)
+(USR forwarding), [#676](https://github.com/ddollar/foreman/issues/676)
+(context for our intentional lifetime difference), [#398](https://github.com/ddollar/foreman/issues/398)
+(formation defaults), [#274](https://github.com/ddollar/foreman/issues/274) and
+[#275](https://github.com/ddollar/foreman/issues/275) (one-off argument handling),
+[#271](https://github.com/ddollar/foreman/issues/271) (run without a Procfile),
+[#230](https://github.com/ddollar/foreman/issues/230) (named run), and
+[#489](https://github.com/ddollar/foreman/issues/489) (interactive run signals).
+They identify relevant command/process regressions and intentional differences;
+the modernization assessment above determines which observations warrant work.
+
+Do not restore historical failures as features. Unknown process selection
+([#565](https://github.com/ddollar/foreman/issues/565),
+[#568](https://github.com/ddollar/foreman/issues/568)) hung in the 0.90.0 probe
+until the harness sent TERM; Foruiman's immediate error is an improvement.
+Foreman's environment interpolation changed between historical versions
+([#561](https://github.com/ddollar/foreman/issues/561)), so compatibility with
+every Foreman release cannot be inferred from matching 0.90.0.
+
+The following accounts for all 53 currently open issues. Grouping describes
+their relevance; it does not claim each reported application failure is fixed.
+
+| Open upstream issues | Assessment for Foruiman |
+| --- | --- |
+| [#779](https://github.com/ddollar/foreman/issues/779), [#775](https://github.com/ddollar/foreman/issues/775), [#768](https://github.com/ddollar/foreman/issues/768), [#708](https://github.com/ddollar/foreman/issues/708) | Child/descendant cleanup. Managed process-group cleanup is tested; escaped sessions, Spring daemons and exact reported applications remain unverified. Closed [#810](https://github.com/ddollar/foreman/issues/810) is a related npx case whose reporter used an exec wrapper. |
+| [#681](https://github.com/ddollar/foreman/issues/681) | Excluded: successful child exit stopping peers is Foreman behavior. Preserve Foruiman's independent default. |
+| [#703](https://github.com/ddollar/foreman/issues/703) | Debugger echo/input: Foruiman offers selected-process TUI input, but the plain-mode controlling-terminal failure remains. |
+| [#808](https://github.com/ddollar/foreman/issues/808), [#750](https://github.com/ddollar/foreman/issues/750), [#754](https://github.com/ddollar/foreman/issues/754) | Logging requests. Exact presentation/raw logging is excluded. Acceptance-only color/timestamp aliases are also not recommended. Real display controls can be added independently if useful. |
+| [#702](https://github.com/ddollar/foreman/issues/702), [#755](https://github.com/ddollar/foreman/issues/755) | Environment precedence and physical multiline `.env` values. Current parsers share Foreman's limitations. Dotenv compatibility is a different target; do not silently reverse precedence or assume full dotenv syntax. Escaped `\n` in double quotes is supported. |
+| [#784](https://github.com/ddollar/foreman/issues/784), [#751](https://github.com/ddollar/foreman/issues/751), [#715](https://github.com/ddollar/foreman/issues/715), [#714](https://github.com/ddollar/foreman/issues/714) | PORT defaults, `.foreman` configuration and offsets. Common semantics match; fix selected-process validation and treat scaling as an optional feature. Do not change the default 5000 to resolve an OS-specific port conflict while claiming identical defaults. |
+| [#705](https://github.com/ddollar/foreman/issues/705) | Optional product feature: multiple worker instances require formation or an equivalent explicit design. Historical `-c` concurrency syntax in the report is not the 0.90.0 contract; use `-m` if Foreman formation is implemented. |
+| [#794](https://github.com/ddollar/foreman/issues/794), [#709](https://github.com/ddollar/foreman/issues/709), [#704](https://github.com/ddollar/foreman/issues/704), [#668](https://github.com/ddollar/foreman/issues/668), [#695](https://github.com/ddollar/foreman/issues/695) | Excluded: exporters and deployment templates. Their absence is not a blocker for this TUI scope. The old `File.exists?` failure in #794 was already fixed in the baseline source despite the issue remaining open. |
+| [#797](https://github.com/ddollar/foreman/issues/797), [#793](https://github.com/ddollar/foreman/issues/793), [#789](https://github.com/ddollar/foreman/issues/789), [#733](https://github.com/ddollar/foreman/issues/733) | Excluded: native Windows. Foruiman remains POSIX-only; no Windows compatibility or fix is claimed. |
+| [#759](https://github.com/ddollar/foreman/issues/759) | Windows DSC export is an upstream feature request, not a supported Foreman format that must be copied. |
+| [#766](https://github.com/ddollar/foreman/issues/766), [#764](https://github.com/ddollar/foreman/issues/764), [#748](https://github.com/ddollar/foreman/issues/748) | Default-start UX is intentional and excluded from parity. Normal `start -f` path/option handling remains applicable and covered. |
+| [#762](https://github.com/ddollar/foreman/issues/762), [#707](https://github.com/ddollar/foreman/issues/707) | Environment usage questions. Parent env is inherited; explicit files and their overriding precedence must stay consistent. |
+| [#679](https://github.com/ddollar/foreman/issues/679), [#684](https://github.com/ddollar/foreman/issues/684), [#746](https://github.com/ddollar/foreman/issues/746), [#699](https://github.com/ddollar/foreman/issues/699), [#713](https://github.com/ddollar/foreman/issues/713) | Requests/questions about reload, code watching, sequencing, conditional Procfiles and remote log views. They are not existing Foreman requirements. HUP means shutdown in both implementations. Foruiman's manual restarts do not imply automatic reload support. |
+| [#796](https://github.com/ddollar/foreman/issues/796), [#786](https://github.com/ddollar/foreman/issues/786), [#782](https://github.com/ddollar/foreman/issues/782), [#693](https://github.com/ddollar/foreman/issues/693), [#731](https://github.com/ddollar/foreman/issues/731), [#645](https://github.com/ddollar/foreman/issues/645), [#700](https://github.com/ddollar/foreman/issues/700) | App-specific failures, startup/output/shutdown reports, or insufficient reproductions. No verified Foreman conformance change can be concluded from their titles alone. Real Rails/Yarn/Redis/Sidekiq fixtures remain useful validation work. |
+| [#752](https://github.com/ddollar/foreman/issues/752), [#688](https://github.com/ddollar/foreman/issues/688) | Historical Thor dependency failures. Foreman 0.90.0 now depends on Thor ~>1.4; Foruiman allows >=1.3,<2. Exact Thor behavior should be pinned in differential tests. |
+| [#811](https://github.com/ddollar/foreman/issues/811), [#806](https://github.com/ddollar/foreman/issues/806), [#783](https://github.com/ddollar/foreman/issues/783), [#778](https://github.com/ddollar/foreman/issues/778), [#776](https://github.com/ddollar/foreman/issues/776), [#767](https://github.com/ddollar/foreman/issues/767) | Project links, another fork, release naming and style tooling. No runtime compatibility requirement. |
+| [#736](https://github.com/ddollar/foreman/issues/736), [#718](https://github.com/ddollar/foreman/issues/718) | Reports concern Puppet's Foreman or node-foreman, not this Ruby CLI. |
+
+## Recommended implementation order
+
+1. **Fix process-control correctness.** Forward USR1/USR2 and fix real
+   controlling-terminal stdin in `--no-tui`. Preserve isolated restarts,
+   process-group cleanup, user quit, and optional shutdown policies.
+2. **Fix selected-process port validation.** Check allocations for selected
+   processes without renumbering original entry offsets. This does not require
+   formation or port-zero support.
+3. **Remove the process-name/UI collision if desired.** Give the aggregate tab
+   its own identity so a process called `all` can work. Keep strict validation
+   of malformed and duplicate entries.
+4. **Consider formation independently.** Add multi-instance processes and
+   exclusions only as an explicit capability. If exposing Foreman's `-m`, retain
+   its semantics and test per-instance ports, `PS`, logs and controls. Until
+   then, keep a clear unsupported-option error.
+5. **Document retained differences.** Keep consistent app-root `run`, supported
+   `.foreman` defaults with strict validation, explicit env-file syntax,
+   positive base ports and the TUI's presentation contract. Give migration
+   examples instead of adding silent no-op flags or copying parser quirks.
+
+Test the correctness fixes with real controlling terminals, signal handlers,
+cleanup checks and selected-process fixtures. Compare with pinned Foreman where
+behavior is deliberately shared; test retained differences against Foruiman's
+own documented contract. No default-lifetime reversal, exporter, API shim or
+legacy rendering layer is needed.
+
+With these modernization choices, describe the product as **a modern alternative
+to Foreman for Procfile development workflows**. List the supported shared
+workflows and migration differences. An unqualified drop-in claim would conflict
+with the intentionally retained command/configuration differences. See
+[COMPATIBILITY.md](COMPATIBILITY.md) for current implemented behavior.

data/docs/RAILS.md

@@ -35,7 +35,18 @@ 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.
+comes from `-p` or `.foreman`, then `PORT` in the loaded environment, then 5000.
+
+Run a Rails command using the same environment without starting the Procfile:
+
+```sh
+foruiman run bin/rails console
+foruiman run -e .env,.env.local bin/rails db:migrate
+```
+
+Explicit `-e` files replace default `.env` loading, so include `.env` in the list
+when layering local overrides. For Foreman-style group shutdown and a longer grace
+period, use `foruiman start -f Procfile.dev --exit-on any -t 10`.
 
 An optional `bin/dev`:
 

data/lib/foruiman/cli.rb

@@ -4,31 +4,39 @@ require "thor"
 require "foruiman"
 require_relative "plain"
 require_relative "diagnostics"
+require_relative "configuration"
 
-# Foreman's Thor command structure, reduced to the MVP surface.
+# Foreman's Thor command structure with an interactive supervisor.
 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"
+  class_option :procfile, type: :string, aliases: "-f", desc: "Procfile to read (default: Procfile)"
+  class_option :root, type: :string, aliases: "-d", desc: "Working directory (default: Procfile directory)"
+  class_option :env, type: :string, aliases: "-e", desc: "Comma-separated environment files instead of .env"
+  class_option :dotenv, type: :boolean, desc: "Load default .env when -e is absent (default: true)"
+  class_option :port, type: :string, aliases: "-p", desc: "Base port (default: PORT or 5000)"
+  class_option :log_lines, type: :string, desc: "Maximum records per process and in all (default: 10000)"
+  class_option :timeout, type: :string, aliases: "-t", desc: "Seconds before escalating TERM to KILL (default: 5)"
+  class_option :exit_on, type: :string, desc: "Shutdown policy: all, any, failure (default: all)"
+
+  def self.is_thor_reserved_word?(word, type) # rubocop:disable Naming/PredicatePrefix -- Thor's extension API
+    word == "run" ? false : super
+  end
 
   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"
+  method_option :tui, type: :boolean, desc: "Use the terminal interface when stdin and stdout are TTYs (default: true)"
   def start(process = nil)
     engine = build_engine
     engine.select(process) if process
-    interactive = options[:tui] && $stdin.tty? && $stdout.tty?
+    engine.validate_ports!
+    interactive = configuration.tui? && $stdin.tty? && $stdout.tty?
     diagnostics = Foruiman::Diagnostics.new(interactive: interactive)
     code = if interactive
              require_relative "tui/application"
@@ -48,9 +56,28 @@ class Foruiman::CLI < Thor
     diagnostics&.close
   end
 
+  desc "run COMMAND [ARGS...]", "Run a command or Procfile entry with the application's environment"
+  stop_on_unknown_option! :run
+  def run(*args)
+    raise Foruiman::Error, "run requires a command" if args.empty?
+
+    config = configuration
+    env = config.environment
+    command = Foruiman::Procfile.new(config.procfile)[args.first] if args.size == 1 && File.file?(config.procfile)
+    if command
+      exec(env, "/bin/sh", "-c", command, chdir: config.root, unsetenv_others: true)
+    else
+      # Preserve argv, terminal input, signals and the command's exact exit code.
+      exec(env, [args.first, args.first], *args.drop(1), chdir: config.root, unsetenv_others: true)
+    end
+  rescue Foruiman::Error, SystemCallError => e
+    raise Thor::Error, e.message
+  end
+
   desc "check", "Validate the Procfile, environment files, ports, and log capacity without starting processes"
   def check
     engine = build_engine
+    engine.validate_ports!
     puts "valid Procfile (#{engine.process_names.join(', ')})"
   rescue Foruiman::Error, SystemCallError => e
     raise Thor::Error, e.message
@@ -65,19 +92,15 @@ class Foruiman::CLI < Thor
 
   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
+  def configuration
+    @configuration ||= Foruiman::Configuration.new(options)
   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))
+    config = configuration
+    env = config.environment
+    Foruiman::Engine.new(procfile: config.procfile, root: config.root, env: env,
+                         port: config.port(env), log_lines: config.log_lines,
+                         term_timeout: config.timeout, exit_on: config.exit_on)
   end
 end

data/lib/foruiman/configuration.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+class Foruiman::Configuration
+  OPTIONS = %w[procfile root env dotenv port log_lines timeout exit_on tui].freeze
+  BOOLEAN_OPTIONS = %w[dotenv tui].freeze
+  PATH_OPTIONS = %w[procfile root env].freeze
+
+  def initialize(options, directory: Dir.pwd)
+    @directory = directory
+    @options = defaults.merge(options.to_h.transform_keys { |key| key.to_s.tr("-", "_") })
+    BOOLEAN_OPTIONS.each do |key|
+      next unless @options.key?(key)
+      next if [true, false].include?(@options[key])
+
+      raise Foruiman::Error, "#{key}: expected true or false"
+    end
+    PATH_OPTIONS.each do |key|
+      next unless @options.key?(key)
+      next if @options[key].is_a?(String) && !@options[key].empty?
+
+      raise Foruiman::Error, "#{key}: expected a nonempty path"
+    end
+  end
+
+  def procfile
+    # Foreman's explicit -f is relative to invocation, independently of -d.
+    File.expand_path(@options.fetch("procfile", File.join(@options.fetch("root", "."), "Procfile")), @directory)
+  end
+
+  def root
+    File.expand_path(@options.fetch("root", File.dirname(procfile)), @directory)
+  end
+
+  def environment
+    # Foreman loads the default environment before inferring a root from -f.
+    env_root = File.expand_path(@options.fetch("root", "."), @directory)
+    files = @options["env"]&.split(",", -1)&.map do |file|
+      raise Foruiman::Error, "env: expected comma-separated file paths" if file.empty?
+
+      File.expand_path(file, @directory)
+    end
+    Foruiman::Env.load(root: env_root, file: files, dotenv: @options.fetch("dotenv", true))
+  end
+
+  def port(env)
+    integer("port", @options.fetch("port") { env.fetch("PORT", "5000") })
+  end
+
+  def log_lines
+    integer("log_lines", @options.fetch("log_lines", "10000"))
+  end
+
+  def timeout
+    value = Float(@options.fetch("timeout", 5), exception: false)
+    return value if value&.finite? && value >= 0
+
+    raise Foruiman::Error, "timeout must be a finite nonnegative number"
+  end
+
+  def exit_on
+    value = @options.fetch("exit_on", "all")
+    return value.to_sym if %w[all any failure].include?(value)
+
+    raise Foruiman::Error, "exit-on must be all, any, or failure"
+  end
+
+  def tui?
+    @options.fetch("tui", true)
+  end
+
+  private
+
+  def integer(name, value)
+    text = value.to_s
+    unless text.match?(/\A[0-9]+\z/) && text.to_i.positive?
+      raise Foruiman::Error, "#{name.tr('_', '-')} must be a positive integer"
+    end
+
+    text.to_i
+  end
+
+  def defaults
+    path = File.join(@directory, ".foreman")
+    return {} unless File.file?(path)
+
+    values = YAML.safe_load_file(path, permitted_classes: [], permitted_symbols: [], aliases: false)
+    return {} if values.nil?
+    raise Foruiman::Error, "#{path}: expected a YAML mapping of option names to values" unless values.is_a?(Hash)
+
+    values.each_with_object({}) do |(key, value), result|
+      name = key.to_s.tr("-", "_")
+      raise Foruiman::Error, "#{path}: unsupported option #{key.inspect}" unless OPTIONS.include?(name)
+
+      result[name] = value
+    end
+  rescue Psych::Exception => e
+    raise Foruiman::Error, "#{path}: #{e.message}"
+  end
+end

data/lib/foruiman/engine.rb

@@ -7,7 +7,8 @@ require_relative "output"
 # Derived from Foreman's registration, process lookup, pipes and self-pipe signal
 # handling. All process state and output now belong to the caller's event loop.
 class Foruiman::Engine
-  HANDLED_SIGNALS = %i[INT TERM HUP].freeze
+  FORWARDED_SIGNALS = %i[USR1 USR2].freeze
+  HANDLED_SIGNALS = %i[INT TERM HUP USR1 USR2].freeze
   TERM_TIMEOUT = 5.0
   READ_CHUNK = 4096
   READ_BUDGET = 64 * 1024
@@ -18,12 +19,16 @@ class Foruiman::Engine
                      keyword_init: true)
   Event = Data.define(:type, :name, :pid, :status, :record, :message)
 
-  attr_reader :logs, :env, :processes, :root, :procfile_path
+  attr_reader :logs, :env, :processes, :root, :procfile_path, :term_timeout, :exit_on
 
   def initialize(procfile: nil, root: Dir.pwd, env: ENV.to_h, input: $stdin, port: 5000, log_lines: 10_000,
-                 term_timeout: TERM_TIMEOUT)
+                 term_timeout: TERM_TIMEOUT, exit_on: :all)
     raise Foruiman::Error, "port must be an integer in 1..65535" unless port.is_a?(Integer) && (1..65_535).cover?(port)
     raise Foruiman::Error, "log-lines must be a positive integer" unless log_lines.is_a?(Integer) && log_lines.positive?
+    unless term_timeout.is_a?(Numeric) && term_timeout.real? && term_timeout.finite? && term_timeout >= 0
+      raise Foruiman::Error, "timeout must be a finite nonnegative number"
+    end
+    raise Foruiman::Error, "exit-on must be all, any, or failure" unless %i[all any failure].include?(exit_on)
 
     @root = File.expand_path(root)
     raise Foruiman::Error, "working directory does not exist: #{@root}" unless File.directory?(@root)
@@ -34,6 +39,7 @@ class Foruiman::Engine
     @base_port = port
     @log_lines = log_lines
     @term_timeout = term_timeout
+    @exit_on = exit_on
     @processes = []
     @names = {}
     @running = {}
@@ -45,7 +51,7 @@ class Foruiman::Engine
     @failed = false
     @closed = false
     @started = false
-    @signal_requested = false
+    @pending_signals = []
     @self_reader, @self_writer = create_pipe
     load_procfile(procfile) if procfile
   rescue StandardError
@@ -57,7 +63,6 @@ class Foruiman::Engine
   def register(name, command)
     raise Foruiman::Error, "cannot register after startup" if @started
     raise Foruiman::Error, "duplicate process: #{name}" if @names.key?(name)
-    raise Foruiman::Error, "allocated port exceeds 65535 for #{name}" if @base_port + (processes.size * 100) > 65_535
 
     Foruiman::Procfile.new[name] = command
     process = Foruiman::Process.new(command, cwd: root, env: env)
@@ -72,9 +77,6 @@ class Foruiman::Engine
   def load_procfile(filename)
     parsed = Foruiman::Procfile.new(filename)
     entries = parsed.entries.to_a
-    last_port = @base_port + ((processes.size + entries.size - 1) * 100)
-    raise Foruiman::Error, "allocated port #{last_port} exceeds 65535" if last_port > 65_535
-
     entries.each { |name, command| register(name, command) }
     @procfile_path = File.expand_path(filename).freeze
     self
@@ -84,6 +86,15 @@ class Foruiman::Engine
     @names.keys
   end
 
+  def validate_ports!(entries = processes)
+    entries.each do |entry|
+      next if entry.port <= 65_535
+
+      raise Foruiman::Error, "allocated port #{entry.port} exceeds 65535 for #{entry.name}"
+    end
+    self
+  end
+
   def process(name)
     @names[name]&.process
   end
@@ -121,6 +132,7 @@ class Foruiman::Engine
     return if @shutdown
 
     targets = name ? [state(name)] : processes
+    validate_ports!(targets)
     unless @started
       @logs = Foruiman::LogStore.new(process_names, capacity: @log_lines) do |record|
         emit(:output, state(record.name), record: record)
@@ -141,6 +153,7 @@ class Foruiman::Engine
     entry = state(name)
     return if entry.restart_pending
 
+    validate_ports!([entry])
     entry.restart_pending = true
     entry.status = :restarting
     lifecycle(entry, :restarting, "restarting")
@@ -208,7 +221,9 @@ class Foruiman::Engine
   end
 
   def exit_code
-    @explicit_shutdown || !@failed ? 0 : 1
+    return 0 if @explicit_shutdown
+
+    @policy_exit_code || (@failed ? 1 : 0)
   end
 
   def run(keep_open: false)
@@ -229,13 +244,13 @@ class Foruiman::Engine
   def tick(timeout: 0.03)
     return if @closed
 
-    shutdown if @signal_requested
+    handle_signals
     reap_children
     advance_groups
     writable = processes.filter_map { |entry| entry.input unless entry.input_buffer.empty? }
     ready, writable = IO.select([@self_reader, *@readers.keys], writable, nil, timeout) || [[], []]
     drain_signal_pipe if ready.delete(@self_reader)
-    shutdown if @signal_requested
+    handle_signals
     writable.each { |input| flush_input(@inputs.fetch(input)) if @inputs.key?(input) }
     read_output(ready)
     reap_children
@@ -273,6 +288,7 @@ class Foruiman::Engine
     begin
       pid = entry.process.run(output: stdout_writer, error: stderr_writer,
                               input: input_slave || @input,
+                              new_session: !@managed_input && @input.respond_to?(:tty?) && @input.tty?,
                               env: { "PORT" => entry.port.to_s, "PS" => "#{entry.name}.1" })
     rescue SystemCallError => e
       stdout_reader.close
@@ -282,6 +298,7 @@ class Foruiman::Engine
       entry.restart_pending = false
       @failed = true
       lifecycle(entry, :failed, "failed to start: #{e.message}")
+      apply_exit_policy(1)
       return
     end
     entry.pid = entry.pgid = pid
@@ -337,10 +354,18 @@ class Foruiman::Engine
       @failed ||= !success && !transitioning
       entry.status = success ? :exited : :failed unless transitioning
       lifecycle(entry, :exited, termination_message_for(entry.exit_status))
+      apply_exit_policy(entry.exit_status.exitstatus || (128 + entry.exit_status.termsig)) unless transitioning
       terminate(entry)
     end
   end
 
+  def apply_exit_policy(code)
+    return if @shutdown || exit_on == :all || (exit_on == :failure && code.zero?)
+
+    @policy_exit_code = code
+    shutdown(explicit: false)
+  end
+
   def advance_groups
     processes.each do |entry|
       next unless entry.pgid
@@ -474,12 +499,24 @@ class Foruiman::Engine
     @old_handlers = {}
     HANDLED_SIGNALS.each do |signal|
       @old_handlers[signal] = Signal.trap(signal) do
-        @signal_requested = true
+        @pending_signals << signal
         notice_signal
       end
     end
   end
 
+  def handle_signals
+    pending = @pending_signals
+    @pending_signals = []
+    pending.each do |signal|
+      if FORWARDED_SIGNALS.include?(signal)
+        processes.each { |entry| signal_group(entry, signal) }
+      else
+        shutdown
+      end
+    end
+  end
+
   def restore_signal_handlers
     @old_handlers&.each { |signal, handler| Signal.trap(signal, handler) }
     @old_handlers = nil

data/lib/foruiman/env.rb

@@ -28,8 +28,11 @@ class Foruiman::Env
   def self.load(root: Dir.pwd, file: nil, dotenv: true, inherited: ENV.to_h)
     env = inherited.dup
     default = File.join(root, ".env")
-    env.merge!(new(default).to_h) if dotenv && File.file?(default)
-    env.merge!(new(file).to_h) if file
+    if file
+      Array(file).each { |filename| env.merge!(new(filename).to_h) }
+    elsif dotenv && File.file?(default)
+      env.merge!(new(default).to_h)
+    end
     env.transform_values { |value| value.dup.freeze }.freeze
   end
 end

data/lib/foruiman/log_store.rb

@@ -14,7 +14,7 @@ class Foruiman::LogStore
   end
 
   def [](name)
-    name == "all" ? all : @buffers.fetch(name)
+    name == :all ? all : @buffers.fetch(name)
   end
 
   def write(name:, stream:, pid:, text:, complete:, previous: nil)

data/lib/foruiman/process.rb

@@ -11,9 +11,49 @@ class Foruiman::Process
   end
 
   def run(options = {})
-    ::Process.spawn(env.merge(options.fetch(:env, {})), "/bin/sh", "-c", command,
-                    chdir: cwd, in: options.fetch(:input, $stdin), out: options.fetch(:output, $stdout),
-                    err: options.fetch(:error, $stderr), pgroup: true, unsetenv_others: true,
-                    close_others: true)
+    environment = env.merge(options.fetch(:env, {}))
+    redirects = { chdir: cwd, in: options.fetch(:input, $stdin), out: options.fetch(:output, $stdout),
+                  err: options.fetch(:error, $stderr), unsetenv_others: true, close_others: true }
+    return spawn_session(environment, redirects) if options[:new_session]
+
+    ::Process.spawn(environment, "/bin/sh", "-c", shell_command, **redirects, pgroup: true)
+  end
+
+  private
+
+  def shell_command
+    # Group forwarding also reaches the shell waiting for the application.
+    # Catch (rather than ignore) these signals so exec resets the dispositions
+    # and the application can decide whether to handle them or terminate.
+    "trap ':' USR1 USR2\n#{command}"
+  end
+
+  def spawn_session(environment, redirects)
+    # A background group in the supervisor's session cannot read its controlling
+    # terminal. A new session keeps inherited stdin usable and still gives us a
+    # group whose ID is the child PID, without taking the terminal's foreground.
+    reader, writer = IO.pipe
+    writer.close_on_exec = true
+    pid = ::Process.fork do
+      reader.close
+      ::Process.setsid
+      exec(environment, "/bin/sh", "-c", shell_command, **redirects)
+    rescue Exception => e # rubocop:disable Lint/RescueException -- never unwind the fork into supervisor cleanup
+      writer.write("#{e.is_a?(SystemCallError) ? e.errno : 0}\n#{e.message}")
+    ensure
+      ::Process.exit!(127)
+    end
+    writer.close
+    failure = reader.read
+    unless failure.empty?
+      ::Process.waitpid(pid)
+      errno, message = failure.split("\n", 2)
+      raise ArgumentError, message if errno.to_i.zero?
+
+      raise SystemCallError.new(message, errno.to_i)
+    end
+    pid
+  ensure
+    [reader, writer].compact.each { |io| io.close unless io.closed? }
   end
 end

data/lib/foruiman/procfile.rb

@@ -52,10 +52,9 @@ class Foruiman::Procfile
   private
 
   def validate_entry!(name, command, location)
-    unless name.match?(/\A[A-Za-z0-9_-]+\z/) && !command.strip.empty? && !command.include?("\0")
-      raise ParseError, "#{location}: expected NAME: command"
-    end
-    raise ParseError, "#{location}: 'all' is reserved for the aggregate tab" if name == "all"
+    return if name.match?(/\A[A-Za-z0-9_-]+\z/) && !command.strip.empty? && !command.include?("\0")
+
+    raise ParseError, "#{location}: expected NAME: command"
   end
 
   def parse(filename)

data/lib/foruiman/tui/application.rb

@@ -92,7 +92,7 @@ module Foruiman::TUI
     end
 
     def begin_input
-      if state.name == "all"
+      if state.aggregate?
         feedback("Select a process before entering input mode")
       elsif @engine.state(state.name).status != :running
         feedback("#{state.name} is not running")
@@ -135,7 +135,7 @@ module Foruiman::TUI
     end
 
     def toggle_process
-      if state.name == "all"
+      if state.aggregate?
         control_all(:stop)
         return
       end
@@ -151,7 +151,7 @@ module Foruiman::TUI
     end
 
     def control(action)
-      if state.name == "all"
+      if state.aggregate?
         if action == :restart
           control_all(action)
         else

data/lib/foruiman/tui/renderer.rb

@@ -126,15 +126,15 @@ module Foruiman::TUI
 
     def tab(name, index, state, engine, width)
       selected = index == state.selected
-      entry = name == "all" ? nil : engine.processes.find { |process| process.name == name }
-      mark = name == "all" ? "≡" : Theme::STATUS_MARKS.fetch(entry&.status, "○")
-      number = if name == "all"
+      entry = name == :all ? nil : engine.processes.find { |process| process.name == name }
+      mark = name == :all ? "≡" : Theme::STATUS_MARKS.fetch(entry&.status, "○")
+      number = if name == :all
                  "0"
                else
                  (index < 9 ? (index + 1).to_s : "·")
                end
-      name = Text.clip(name, [width - 12, 6].max.clamp(6, 22), ellipsis: true)
-      color = name == "all" ? :accent : @theme.process(index)
+      color = name == :all ? :accent : @theme.process(index)
+      name = Text.clip(name.to_s, [width - 12, 6].max.clamp(6, 22), ellipsis: true)
       mark_color = entry ? Theme::STATUS_COLORS.fetch(entry.status, :muted) : :muted
       @theme.paint(" #{number} ", selected ? :muted : :faint, selected: selected) +
         @theme.paint("#{mark} ", mark_color, selected: selected) +
@@ -147,14 +147,14 @@ module Foruiman::TUI
                       @theme.paint(" ? / Escape close help ", :muted))
       end
 
-      title = state.name == "all" ? " ≡ all logs " : " › #{state.name} "
-      detail = if state.name == "all"
+      title = state.aggregate? ? " ≡ all logs " : " › #{state.name} "
+      detail = if state.aggregate?
                  "#{engine.processes.size} processes"
                else
                  entry = engine.state(state.name)
                  process_detail(entry)
                end
-      active = if state.name == "all"
+      active = if state.aggregate?
                  engine.processes.any? { |entry| entry.status == :running }
                else
                  engine.state(state.name).status == :running
@@ -171,7 +171,7 @@ module Foruiman::TUI
       title = @theme.paint(title, :text, bold: true)
       if @inside >= 45
         title += @theme.paint(" #{detail} ", :muted)
-      elsif state.name != "all" && @inside >= 28
+      elsif !state.aggregate? && @inside >= 28
         entry = engine.state(state.name)
         title += @theme.paint(" #{entry.status} ", Theme::STATUS_COLORS.fetch(entry.status, :muted))
       end
@@ -200,7 +200,7 @@ module Foruiman::TUI
       thumb_start = buffer.size <= @height ? 0 : (first * travel / (buffer.size - @height))
       Array.new(@height) do |index|
         content = if records[index]
-                    @formatter.row(records[index], aggregate: state.name == "all", width: @inside - 2)
+                    @formatter.row(records[index], aggregate: state.aggregate?, width: @inside - 2)
                   elsif records.empty? && index == @height / 2
                     @theme.paint("Waiting for output…", :faint)
                   else
@@ -226,7 +226,7 @@ module Foruiman::TUI
                  else
                    " f resume "
                  end
-      location = " PID #{engine.state(state.name).pid || '-'} " if state.name != "all" && @inside < 45
+      location = " PID #{engine.state(state.name).pid || '-'} " if !state.aggregate? && @inside < 45
       border(@theme.paint(count, :faint), @theme.paint(location, state.viewport.following ? :faint : :amber),
              bottom: true)
     end
@@ -256,7 +256,8 @@ module Foruiman::TUI
 
       quit = @theme.paint(" q ", :accent, bold: true) + @theme.paint(" × quit ", :muted)
       left = if engine.shutting_down?
-               @theme.paint(" ◌ Stopping process groups · TERM → KILL after 5s", :amber)
+               seconds = format("%g", engine.term_timeout)
+               @theme.paint(" ◌ Stopping process groups · TERM → KILL after #{seconds}s", :amber)
              elsif state.feedback
                @theme.paint(" #{state.feedback}", :amber)
              elsif state.help
@@ -268,8 +269,8 @@ module Foruiman::TUI
     end
 
     def shortcuts(state, engine)
-      restart = ["r", state.name == "all" ? "↻ restart all" : "↻ restart"]
-      toggle = if state.name == "all"
+      restart = ["r", state.aggregate? ? "↻ restart all" : "↻ restart"]
+      toggle = if state.aggregate?
                  ["s", "■ stop all"]
                elsif process_active?(engine.state(state.name))
                  ["s", "■ stop"]

data/lib/foruiman/tui/state.rb

@@ -9,7 +9,7 @@ module Foruiman::TUI
     attr_accessor :help, :feedback, :input_target
 
     def initialize(names)
-      @tabs = [*names, "all"].freeze
+      @tabs = [*names, :all].freeze
       @selected = tabs.size - 1
       @viewports = tabs.to_h { |name| [name, Viewport.new] }
       @help = false
@@ -22,6 +22,10 @@ module Foruiman::TUI
       tabs[selected]
     end
 
+    def aggregate?
+      name == :all
+    end
+
     def viewport
       viewports.fetch(name)
     end

data/lib/foruiman/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Foruiman
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: foruiman
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Foruiman contributors
@@ -64,12 +64,14 @@ files:
 - docs/ARCHITECTURE.md
 - docs/ASSUMPTIONS.md
 - docs/COMPATIBILITY.md
+- docs/FOREMAN_AUDIT.md
 - docs/RAILS.md
 - docs/UPSTREAM.md
 - docs/terminal-preview.png
 - lib/foruiman.rb
 - lib/foruiman/ansi.rb
 - lib/foruiman/cli.rb
+- lib/foruiman/configuration.rb
 - lib/foruiman/diagnostics.rb
 - lib/foruiman/engine.rb
 - lib/foruiman/env.rb
@@ -112,7 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: A Procfile supervisor with process tabs, bounded logs, and isolated restarts
 test_files: []