rush-shell 0.0.2

data/lib/rush/io_table.rb

@@ -0,0 +1,94 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Maps file descriptors to fd entries for a single command. Redirections fold
+  # over a base table to produce a new one (`with`), so the shell's own streams
+  # are never mutated and a command's redirections are scoped to that command.
+  class IoTable
+    extend T::Sig
+
+    sig { params(entries: T::Hash[Integer, T.untyped]).void }
+    def initialize(entries)
+      @entries = entries.transform_values { |entry| fd_entry(entry) }
+    end
+
+    sig { params(system: SystemCalls).returns(IoTable) }
+    def self.standard(system)
+      new(0 => FdEntry.borrowed(system.stdin),
+          1 => FdEntry.borrowed(system.stdout),
+          2 => FdEntry.borrowed(system.stderr))
+    end
+
+    sig { params(fd: Integer).returns(T.untyped) }
+    def get(fd)
+      entry(fd)&.stream
+    end
+
+    sig { params(fd: Integer).returns(T.nilable(FdEntry)) }
+    def entry(fd)
+      @entries.fetch(fd, nil)
+    end
+
+    sig { params(fd: Integer, io: T.untyped).returns(IoTable) }
+    def with(fd, io)
+      with_entry(fd, FdEntry.borrowed(io))
+    end
+
+    sig { params(fd: Integer, io: T.untyped).returns(IoTable) }
+    def with_owned(fd, io)
+      with_entry(fd, FdEntry.owned(io))
+    end
+
+    sig { params(fd: Integer).returns(IoTable) }
+    def with_closed(fd)
+      with_entry(fd, FdEntry.closed)
+    end
+
+    sig { params(fd: Integer, entry: FdEntry).returns(IoTable) }
+    def with_entry(fd, entry)
+      self.class.new(@entries.merge(fd => entry))
+    end
+
+    # The bound entries, for diffing which redirections freshly opened owned
+    # streams over the base table. Borrowed entries (stdio, pipes and inherited
+    # fds) are intentionally not closed by redirect cleanup.
+    sig { returns(T::Array[FdEntry]) }
+    def entries
+      @entries.values
+    end
+
+    # Owned entries that appeared while moving from `base` to this table. This
+    # includes newly opened redirect files/heredocs, but not borrowed stdio,
+    # pipes, inherited fds or dup aliases of entries already present in `base`.
+    sig { params(base: IoTable).returns(T::Array[FdEntry]) }
+    def opened_over(base)
+      (entries - base.entries).select(&:owned?)
+    end
+
+    # Flush+close the streams this table opened over `base` (the ones a command's
+    # redirects added), leaving inherited streams and pipe ends untouched.
+    sig { params(base: IoTable, system: SystemCalls).void }
+    def close_opened_over(base, system)
+      self.class.close_entries(opened_over(base), system)
+    end
+
+    sig { params(entries: T::Array[FdEntry], system: SystemCalls).void }
+    def self.close_entries(entries, system)
+      entries.uniq.each { |entry| entry.close_redirect(system) }
+    end
+
+    # A closed fd becomes :close so a spawned child closes it.
+    sig { returns(T::Hash[Integer, T.untyped]) }
+    def to_spawn_options
+      @entries.transform_values(&:to_spawn_option)
+    end
+
+    private
+
+    sig { params(entry: T.untyped).returns(FdEntry) }
+    def fd_entry(entry)
+      entry.is_a?(FdEntry) ? entry : FdEntry.borrowed(entry)
+    end
+  end
+end

data/lib/rush/job_control.rb

@@ -0,0 +1,197 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # The monitor-mode (`set -m`) policy: whether job control is active here,
+  # and the side effects of flipping the flag. Stateless — Executor builds one
+  # on demand; the durable bits (root shell, acquired terminal) live on the
+  # JobTable's Control. dash 0.5.13 is the oracle throughout (probed on and
+  # off a tty, journal): enabling monitor ignores SIGTSTP in the shell — as a
+  # base disposition, so a user trap overrides it and `trap -` restores it —
+  # and puts every forked job (background list, pipeline, subshell, external
+  # command) into its own process group, first process as leader; command
+  # substitution stays in the shell's group. Whenever the controlling
+  # terminal is reachable — interactive or not — the shell additionally does
+  # dash's setjobctl dance: wait until it is in the foreground, remember the
+  # terminal's owner, make itself a process-group leader, take the terminal,
+  # and ignore SIGTTOU too; foreground jobs then own the tty for the length
+  # of their run. Only an interactive shell treats a missing tty as an error
+  # (warn, flag off). The machinery is root-shell-only: a forked child keeps
+  # `m` in $- but re-enabling there is flag-only, exactly like dash's
+  # rootshell guard. Its raw Options#set(:monitor, ...) calls are deliberate:
+  # this policy is the sole live-executor owner of both that flag and its side
+  # effects; all ordinary option writes route through ShellState#set_option.
+  class JobControl
+    extend T::Sig
+
+    IGNORE = T.let(proc {}, Proc)
+
+    sig { params(executor: Executor).void }
+    def initialize(executor)
+      @executor = executor
+    end
+
+    # `set -m` (and -o monitor, and invocation-time -m via #startup). Can
+    # refuse — no platform support, or an interactive shell without a tty —
+    # in which case the flag stays off and the failure is only a warning, as
+    # dash's setjobctl does. Re-enabling while on is a no-op (dash: on ==
+    # jobctl), preserving the remembered terminal owner.
+    sig { params(stderr: T.untyped).void }
+    def enable(stderr)
+      return refuse(stderr, 'job control not supported') unless @executor.system.job_control_supported?
+      return if options.on?(:monitor)
+      return options.set(:monitor, true) unless control.root
+
+      enable_root(stderr)
+    end
+
+    # `set +m`: the flag drops, SIGTSTP and SIGTTOU return to the OS default
+    # (dash setjobctl(0) runs both setsignals unconditionally), and the
+    # terminal goes back to whoever owned it at acquisition.
+    sig { void }
+    def disable
+      options.set(:monitor, false)
+      drop_monitor if control.root
+    end
+
+    # Invocation-time -m (explicit, or defaulted on for an interactive
+    # shell like dash's mflag = iflag): the flag was set while building the
+    # shell state, before any executor existed to carry the side effects.
+    # Re-run it through #enable so an interactive shell without a tty drops
+    # the flag (dash: "can't access tty" at startup), and a permitted one
+    # acquires the terminal and its base dispositions.
+    sig { void }
+    def startup
+      return unless options.on?(:monitor)
+
+      options.set(:monitor, false)
+      enable(@executor.system.stderr)
+    end
+
+    # Process grouping is active: monitor is on and this is the root shell.
+    # Forked children inherit `m` in $- but none of the machinery (dash's
+    # rootshell guard, probed via nested groups and subshell `set -m`).
+    sig { returns(T::Boolean) }
+    def monitored?
+      control.monitor?
+    end
+
+    # Fork one member of a foreground job, into `leader`'s process group
+    # (its own when none) under job control; a group leader also takes the
+    # terminal, child-side, when the shell holds one. Grouping is decided
+    # before the fork, so a child entering its subshell environment cannot
+    # flip it.
+    sig { params(leader: T.nilable(Integer), child_main: T.proc.returns(T.untyped)).returns(Integer) }
+    def launch(leader: nil, &child_main)
+      return @executor.system.fork(&child_main) || 0 unless monitored?
+
+      group = leader&.positive? ? leader : 0
+      @executor.system.fork_grouped(group, handover_tty(group), &child_main) || 0
+    end
+
+    # An asynchronous (&) job: its own group under job control, but never
+    # the terminal — probed: the tty stays with the shell.
+    sig { params(child_main: T.proc.returns(T.untyped)).returns(Integer) }
+    def launch_background(&child_main)
+      return @executor.system.fork(&child_main) || 0 unless monitored?
+
+      @executor.system.fork_grouped(0, &child_main) || 0
+    end
+
+    # Wait for a foreground job with the terminal handed to its process
+    # group, taking it back once the job settles, however the wait ends
+    # (dash's waitforjob). The give here is the parent-side settle — it also
+    # covers the spawn path, which has no child-side hook — and without a
+    # held terminal the wait runs bare. A wait that answers "stopped" (^Z
+    # under the WUNTRACED waits) parks the whole job in the table on the
+    # way out, where jobs/wait/kill find it.
+    sig { params(pids: T::Array[Integer], text: T.nilable(String), blk: T.proc.returns(Status)).returns(Status) }
+    def foreground(pids, text: nil, &blk)
+      status = Terminal.while_held(control.terminal, pids.fetch(0), &blk)
+      @executor.jobs.adopt_stopped(pids, T.must(status.stopsig), text) if status.stopped?
+      status
+    end
+
+    # The command text a job-table entry keeps: rendered only under job
+    # control — dash stores cmdtext for jobctl jobs alone, and that absence
+    # is fg/bg's refusal bit.
+    sig { params(node: AST::Node).returns(T.nilable(String)) }
+    def job_text(node)
+      CommandText.render(node) if control.monitor?
+    end
+
+    private
+
+    # The root-shell side of `set -m`: with a reachable tty, the full dash
+    # setjobctl dance; without one, grouping only — an error only for an
+    # interactive shell.
+    sig { params(stderr: T.untyped).void }
+    def enable_root(stderr)
+      terminal = Terminal.acquire(@executor.system)
+      terminal ? enable_with_terminal(terminal) : enable_off_tty(stderr)
+    end
+
+    # SIGTSTP and SIGTTOU ignored (probed under a pty; SIGTTIN keeps the OS
+    # default — that is what parks a background-started shell until fg), as
+    # base dispositions: user traps win in either order and `trap -` falls
+    # back here.
+    sig { params(terminal: Terminal).void }
+    def enable_with_terminal(terminal)
+      control.engage(terminal)
+      @executor.trap_runner.set_base('TSTP', IGNORE)
+      @executor.trap_runner.set_base('TTOU', IGNORE)
+      options.set(:monitor, true)
+    end
+
+    # Off-tty monitor is grouping, WUNTRACED waits and the SIGTSTP ignore
+    # alone (probed: dash leaves TTOU stopping the shell there).
+    sig { params(stderr: T.untyped).void }
+    def enable_off_tty(stderr)
+      return refuse(stderr, "can't access tty; job control turned off") if interactive?
+
+      control.engage(nil)
+      @executor.trap_runner.set_base('TSTP', IGNORE)
+      options.set(:monitor, true)
+    end
+
+    # The root-shell side of `set +m`: both stop-signal bases return to the
+    # OS default and the terminal, when held, goes home.
+    sig { void }
+    def drop_monitor
+      @executor.trap_runner.set_base('TSTP', nil)
+      @executor.trap_runner.set_base('TTOU', nil)
+      control.terminal&.restore
+      control.release
+    end
+
+    # The tty a freshly forked job leader should take with it (dash
+    # forkchild's FORK_FG xtcsetpgrp): only a group leader, only while the
+    # shell holds the terminal. Joiners find the group already in front.
+    sig { params(group: Integer).returns(T.untyped) }
+    def handover_tty(group)
+      return if group.nonzero?
+
+      control.terminal&.tty
+    end
+
+    sig { params(stderr: T.untyped, message: String).void }
+    def refuse(stderr, message)
+      stderr.puts("rush: #{message}")
+    end
+
+    sig { returns(JobTable::Control) }
+    def control
+      @executor.jobs.control
+    end
+
+    sig { returns(T::Boolean) }
+    def interactive?
+      options.on?(:interactive)
+    end
+
+    sig { returns(Options) }
+    def options
+      @executor.state.options
+    end
+  end
+end

data/lib/rush/job_report.rb

@@ -0,0 +1,45 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # One line of the jobs listing — and, verbatim, of a pre-prompt
+  # notification: "[n] mark " (plus "pid " under jobs -l), the state, padding
+  # so the command text starts at column 34, then the text itself (empty
+  # outside job control, where dash keeps none either). dash's showjob
+  # format, shared by the jobs builtin and the Repl's notifier.
+  module JobReport
+    extend T::Sig
+
+    sig { params(table: JobTable, job: JobTable::Job, pid_field: String).returns(String) }
+    def self.line(table, job, pid_field = '')
+      head = "[#{job.number}] #{mark(table, job)} #{pid_field}#{state(job)}"
+      "#{head.ljust(33)}#{job.text}"
+    end
+
+    # + marks the current job, - the previous one (newest-first order).
+    sig { params(table: JobTable, job: JobTable::Job).returns(String) }
+    def self.mark(table, job)
+      index = T.must(table.ordered.index(job))
+      ['+', '-'].fetch(index, ' ')
+    end
+
+    # The state column (dash's statusfmt vocabulary): Running, a strsignal
+    # Stopped flavour, Done/Done(n), or the killing signal's description.
+    sig { params(job: JobTable::Job).returns(String) }
+    def self.state(job)
+      return 'Running' if job.running?
+      return Signals.stop_description(T.must(job.stopsig)) if job.stopped?
+
+      settled(job.status)
+    end
+
+    sig { params(status: Status).returns(String) }
+    def self.settled(status)
+      signal = status.termsig
+      return Signals.description(signal) if signal
+
+      code = status.exitstatus
+      code.zero? ? 'Done' : "Done(#{code})"
+    end
+  end
+end

data/lib/rush/job_spec.rb

@@ -0,0 +1,51 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Resolves a %job_id operand (POSIX 2.12 Job Control Job ID) against the
+  # job table: % / %% / %+ name the current job, %- the previous one, %n job
+  # number n. dash keeps no command text away from a tty, so %string and
+  # %?string prefixes match nothing here — No such job, exactly like the
+  # oracle. A failed resolution raises JobError carrying dash's message; the
+  # consuming builtin prefixes its name and fails with status 2.
+  class JobSpec
+    extend T::Sig
+
+    NUMBER = /\A%\d+\z/
+
+    # Fork-inherited display copies resolve for nobody: the jobs listing
+    # shows them (POSIX 2.12 duplicate), but wait/kill/fg/bg in a forked
+    # child answer No such job, exactly like dash (probed: a pipeline
+    # stage lists [1] while `wait %1` in the same stage reports rc=2).
+    sig { params(jobs: JobTable, spec: String).returns(JobTable::Job) }
+    def self.resolve(jobs, spec)
+      case spec
+      when '%', '%%', '%+' then live(jobs.current) || missing('current')
+      when '%-' then live(jobs.previous) || missing('previous')
+      else by_number(jobs, spec)
+      end
+    end
+
+    sig { params(jobs: JobTable, spec: String).returns(JobTable::Job) }
+    def self.by_number(jobs, spec)
+      unknown(spec) unless spec.match?(NUMBER)
+
+      live(jobs.numbered(Integer(spec.delete_prefix('%'), 10))) || unknown(spec)
+    end
+
+    sig { params(job: T.nilable(JobTable::Job)).returns(T.nilable(JobTable::Job)) }
+    def self.live(job)
+      job if job && !job.inherited?
+    end
+
+    sig { params(which: String).returns(T.noreturn) }
+    def self.missing(which)
+      raise JobError, "No #{which} job"
+    end
+
+    sig { params(spec: String).returns(T.noreturn) }
+    def self.unknown(spec)
+      raise JobError, "No such job: #{spec}"
+    end
+  end
+end

data/lib/rush/job_table/control.rb

@@ -0,0 +1,103 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class JobTable
+    # The job-control environment of this shell: the root-shell bit, how
+    # this shell treats stopped children (bare waits, engaged monitor
+    # machinery, or a stage's stop relay), and — with a tty — the acquired
+    # controlling terminal. dash's rootshell/jobctl guards and
+    # ttyfd/initialpgrp globals; monitor and terminal drop together when a
+    # forked child clears its job table, while an armed relay survives the
+    # fork so stops keep bubbling (rush-l4o).
+    class Control
+      extend T::Sig
+
+      sig { returns(T::Boolean) }
+      attr_reader :root
+
+      sig { returns(T.nilable(Terminal)) }
+      attr_reader :terminal
+
+      sig { void }
+      def initialize
+        @root = T.let(true, T::Boolean)
+        @stops = T.let(:default, Symbol)
+        @terminal = T.let(nil, T.nilable(Terminal))
+        @warning = T.let(0, Integer)
+      end
+
+      # Monitor machinery engaged in this shell (grouping, WUNTRACED waits,
+      # stops adopted into the job table).
+      sig { returns(T::Boolean) }
+      def monitor?
+        @stops == :monitor
+      end
+
+      # A pipeline stage forked from a monitor-mode shell is a transparent
+      # member of its job: once armed, a stop this process's own foreground
+      # wait reaps is re-raised onto the process itself, propagating the
+      # stop to the job's owner (rush-l4o; dash reaches the same picture by
+      # exec-ing simple stages in place). Armed child-side before the
+      # subshell reset, while the parent's monitor bit is still readable.
+      sig { void }
+      def arm_stage_relay
+        @stops = :relay if monitor?
+      end
+
+      sig { returns(T::Boolean) }
+      def relay?
+        @stops == :relay
+      end
+
+      # Stops are visible to this shell's waits: the monitor adopts them,
+      # the relay re-raises them.
+      sig { returns(T::Boolean) }
+      def stoppable_waits?
+        monitor? || relay?
+      end
+
+      # `set -m` accepted in the root shell: machinery on, holding the
+      # terminal when one was acquired (nil off-tty — grouping still runs).
+      sig { params(terminal: T.nilable(Terminal)).void }
+      def engage(terminal)
+        @stops = :monitor
+        @terminal = terminal
+      end
+
+      sig { void }
+      def release
+        @stops = :default
+        @terminal = nil
+      end
+
+      # A fork drops root, terminal and monitor together — but keeps an
+      # armed relay, so stops bubble out of nested forks within a stage.
+      sig { void }
+      def fork_child
+        @root = false
+        @terminal = nil
+        @stops = :default if monitor?
+      end
+
+      # dash's job_warning: the first exit with a stopped job warns and is
+      # refused; the window it opens lets the very next command's exit
+      # through, and two interactive ticks re-arm it (a batch shell never
+      # ticks, so it warns exactly once).
+      sig { returns(T::Boolean) }
+      def warn_exit?
+        return false if @warning.positive?
+
+        @warning = 2
+        true
+      end
+
+      # One interactive turn passing (the Repl, as dash's cmdloop decrements
+      # job_warning per iteration).
+      sig { void }
+      def tick_warning
+        @warning -= 1 if @warning.positive?
+      end
+    end
+  end
+end

data/lib/rush/job_table/interruptible_wait.rb

@@ -0,0 +1,70 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Reopens the table only to keep its interruptible-wait implementation next
+  # to the polling collaborator; the core initializer owns these ivars.
+  # :reek:InstanceVariableAssumption
+  class JobTable
+    # WNOHANG polling used only by the wait builtin. Foreground awaits remain
+    # blocking, while a caught trap can stop this wait without reaping its job.
+    class InterruptibleWait
+      extend T::Sig
+
+      POLL_INTERVAL = 0.01
+
+      sig do
+        params(system: SystemCalls, control: Control, target: Integer,
+               pending: T.proc.returns(T.nilable(Integer))).void
+      end
+      def initialize(system, control, target, pending)
+        @system = system
+        @control = control
+        @target = target
+        @pending = pending
+      end
+
+      sig { returns(T.any(Process::Status, Status)) }
+      def call
+        loop do
+          result = interrupted || poll
+          return result if result
+
+          sleep(POLL_INTERVAL)
+        end
+      end
+
+      private
+
+      sig { returns(T.nilable(Status)) }
+      def interrupted
+        code = @pending.call
+        Status.new(code) if code
+      end
+
+      sig { returns(T.nilable(Process::Status)) }
+      def poll
+        pair = @control.stoppable_waits? ? @system.poll_pid_stopped(@target) : @system.poll_pid(@target)
+        pair&.fetch(1)
+      end
+    end
+
+    # The wait builtin alone is interruptible by a caught signal. Polling keeps
+    # JobTable the sole reaper while foreground await remains a blocking wait.
+    sig { params(pid: Integer, pending: T.proc.returns(T.nilable(Integer))).returns(T.nilable(Status)) }
+    def wait_for_interruptibly(pid, &pending)
+      @jobs[pid]&.harvest { interruptible_settle(pid, pending) }
+    rescue Errno::ECHILD
+      Status.success
+    end
+
+    private
+
+    sig do
+      params(pid: Integer, pending: T.proc.returns(T.nilable(Integer))).returns(T.any(Process::Status, Status))
+    end
+    def interruptible_settle(pid, pending)
+      @stash.delete(pid) || InterruptibleWait.new(@system, @control, pid, pending).call
+    end
+  end
+end