rush-shell 0.0.2

data/lib/rush/system_calls/process_identity.rb

@@ -0,0 +1,43 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class SystemCalls
+    # Who the shell process is, mixed into SystemCalls: pids for $$/PPID,
+    # effective privileges for the PS1 default, and the invocation name for
+    # login-shell detection.
+    module ProcessIdentity
+      extend T::Sig
+
+      sig { returns(Integer) }
+      def pid
+        Process.pid
+      end
+
+      sig { returns(Integer) }
+      def ppid
+        Process.ppid
+      end
+
+      # The shell's own process group: compared against the terminal's
+      # foreground group when job control acquires the tty (rush-mv8.3).
+      sig { returns(Integer) }
+      def pgrp
+        Process.getpgrp
+      end
+
+      # Whether the shell runs with root privileges: picks the default PS1
+      # ('# ' instead of '$ '), as POSIX permits for privileged users.
+      sig { returns(T::Boolean) }
+      def privileged?
+        Process.euid.zero?
+      end
+
+      # How the process was invoked ($0): a leading '-' marks a login shell.
+      sig { returns(String) }
+      def program_name
+        $PROGRAM_NAME
+      end
+    end
+  end
+end

data/lib/rush/system_calls/resource_limits.rb

@@ -0,0 +1,51 @@
+# typed: false
+# frozen_string_literal: true
+
+module Rush
+  class SystemCalls
+    # Resource-limit wrappers for the `ulimit` builtin. The mapping lives outside
+    # SystemCalls proper so the impure syscall port stays small as it grows.
+    module ResourceLimits
+      RLIMITS = {
+        cpu: Process::RLIMIT_CPU,
+        fsize: Process::RLIMIT_FSIZE,
+        data: Process::RLIMIT_DATA,
+        stack: Process::RLIMIT_STACK,
+        core: Process::RLIMIT_CORE,
+        rss: Process::RLIMIT_RSS,
+        memlock: Process::RLIMIT_MEMLOCK,
+        nproc: Process::RLIMIT_NPROC,
+        nofile: Process::RLIMIT_NOFILE,
+        as: Process::RLIMIT_AS,
+        locks: (Process.const_get(:RLIMIT_LOCKS) if Process.const_defined?(:RLIMIT_LOCKS)),
+        rtprio: Process::RLIMIT_RTPRIO
+      }.freeze
+
+      def current_umask
+        File.umask
+      end
+
+      def change_umask(mask)
+        File.umask(mask)
+      end
+
+      def infinity_limit
+        Process::RLIM_INFINITY
+      end
+
+      def getrlimit(resource)
+        limit = RLIMITS.fetch(resource)
+        return [infinity_limit, infinity_limit] unless limit
+
+        Process.getrlimit(limit)
+      end
+
+      def setrlimit(resource, soft, hard)
+        limit = RLIMITS.fetch(resource)
+        raise Errno::EINVAL unless limit
+
+        Process.setrlimit(limit, soft, hard)
+      end
+    end
+  end
+end

data/lib/rush/system_calls.rb

@@ -0,0 +1,206 @@
+# typed: false
+# frozen_string_literal: true
+
+require 'etc'
+require 'reline'
+require 'tempfile'
+require_relative 'system_calls/file_tests'
+require_relative 'system_calls/collation'
+require_relative 'system_calls/process_identity'
+require_relative 'system_calls/process_control'
+require_relative 'system_calls/resource_limits'
+
+module Rush
+  # The sole impure class: every syscall rush makes is a thin wrapper here, so
+  # specs inject a fake (spec/support/fake_system_calls.rb) and reach every
+  # error branch without touching the real OS. Grows one wrapper per slice.
+  class SystemCalls
+    include FileTests
+    include ProcessIdentity
+    include ProcessControl
+    include ResourceLimits
+
+    COLLATION = Collation.new
+
+    # Run `file` as an external program with argv.first as the child's argv[0]
+    # — for the ordinary $PATH search the caller passes the bare command name
+    # as `file`; `command -p` passes its default-PATH resolution instead,
+    # without renaming the command (dash-probed via `$0`). The [cmd, argv0]
+    # form forbids the shell path even for a single-word command, so `spawn`
+    # never re-interprets words.
+    def spawn(file, env, argv, options)
+      Process.spawn(env, [file, argv.first], *argv.drop(1), options)
+    end
+
+    # The system default PATH (confstr _CS_PATH): the search path `command -p`
+    # uses, guaranteed to find the standard utilities regardless of $PATH.
+    # POSIX defines _CS_PATH on every system; the coalesce only satisfies
+    # confstr's nilable signature.
+    def default_path
+      Etc.confstr(Etc::CS_PATH) || ''
+    end
+
+    # Replace the current process image (the `exec` builtin); the [cmd, argv0]
+    # form forbids the shell path, like #spawn. Returns only if the exec fails.
+    def exec(env, argv, options)
+      Process.exec(env, [argv.first, argv.first], *argv.drop(1), options)
+    end
+
+    # Accumulated CPU times for the `times` builtin: a Process::Tms with utime /
+    # stime for the shell and cutime / cstime for its children. Non-deterministic,
+    # so the builtin's output is verified by format rather than differentially.
+    def times
+      Process.times
+    end
+
+    # Send a signal to a process (the `kill` builtin); signal 0 only probes that
+    # the target exists. Real signal delivery cannot run under the test harness.
+    # :nocov:
+    def kill(signal, pid)
+      Process.kill(signal, pid)
+    end
+
+    # Install a signal disposition for `trap`: a command string ('IGNORE' /
+    # 'SYSTEM_DEFAULT') or, when nil, the block to run when the signal arrives. Mutating
+    # the process's real signal handlers cannot run under the test harness.
+    def trap_signal(name, command, &block)
+      Signal.trap(name, command || block)
+    end
+    # :nocov:
+
+    def pipe
+      IO.pipe
+    end
+
+    # Return a non-owning IO wrapper for an fd that is already open in the rush
+    # process (typically inherited from the parent) but not tracked by IoTable.
+    # A closed fd returns nil so redirection code can report "fd not open".
+    # Unbuffered: every `n>&9` evaluation wraps the fd anew, and buffered
+    # wrappers would flush at exit in GC order — reordering or hiding writes
+    # (rush-erq: container-reversed lines; a `cat` mid-script saw nothing
+    # where dash, which writes straight to the fd, showed the line).
+    def inherited_fd(fd)
+      return if fd.negative?
+
+      IO.for_fd(fd, autoclose: false).tap { |stream| stream.sync = true }
+    rescue Errno::EBADF
+      nil
+    end
+
+    # fork/exit! replace or split the process and so cannot run in-process under
+    # the test harness; the child-side logic they drive is extracted into pure
+    # methods that ARE tested, and real behaviour is covered by subprocess specs.
+    # exit! flushes the standard streams first: $stdout is unbuffered only when a
+    # tty, so a forked child running a builtin would otherwise lose its output.
+    # :nocov:
+    def fork(&blk)
+      Process.fork(&blk)
+    end
+
+    def exit!(code)
+      stdout.flush
+      stderr.flush
+      Process.exit!(code)
+    end
+    # :nocov:
+
+    def chdir(path)
+      Dir.chdir(path)
+    end
+
+    def pwd
+      Dir.pwd
+    end
+
+    def expand_path(path, base)
+      File.expand_path(path, base)
+    end
+
+    def fnmatch?(pattern, str, locale: COLLATION.default_settings)
+      COLLATION.match_shell?(pattern, str, locale) { ShellPattern.new(pattern).match?(str) }
+    end
+
+    # Pathname expansion: libc filters widened Dir.glob candidates and orders
+    # exact matches by LC_COLLATE; unsupported libcs retain the Ruby fallback.
+    def glob(pattern, locale: COLLATION.default_settings)
+      COLLATION.glob(pattern, locale) do
+        ShellPattern.new(pattern).then { |shell_pattern| Dir.glob(shell_pattern.glob_source).grep(shell_pattern) }
+      end
+    end
+
+    # Sync so a builtin's write reaches the file immediately — like a pipe write
+    # end (sync by default), this lets a forked subshell's output survive its
+    # exit! and be visible to a later command. File.new, not File.open: the
+    # redirection keeps the file open past this call — the caller owns the
+    # handle until close_redirect releases it, so the auto-closing block form
+    # would be wrong here.
+    def open_file(path, mode)
+      File.new(path, mode).tap { |io| io.sync = true }
+    end
+
+    # Flush and release a file a redirection opened, so a later command in the
+    # same shell sees the data and the fd does not leak.
+    def close_redirect(io)
+      io.close
+    end
+
+    def read_file(path)
+      File.read(path)
+    end
+
+    # A readable stream carrying a here-document body (a real fd, via a tempfile,
+    # so spawned children can read it).
+    def here_doc(body)
+      Tempfile.new('rush-heredoc').tap do |file|
+        file.write(body)
+        file.rewind
+      end
+    end
+
+    def stdin
+      $stdin
+    end
+
+    def stdout
+      $stdout
+    end
+
+    def stderr
+      $stderr
+    end
+
+    # Interactive-REPL support: read one line of input (nil at EOF) and report
+    # whether standard input / standard error are terminals (POSIX interactivity
+    # requires both).
+    def read_line
+      stdin.gets
+    end
+
+    # Interactive line editing: Reline draws the prompt (on stderr, like the
+    # plain path), records the line into its in-memory history, and returns nil
+    # at EOF. A real-terminal path the test harness cannot drive; the Docker
+    # gate's pty smoke exercises it.
+    # :nocov:
+    def edit_line(prompt)
+      Reline.output = stderr
+      Reline.readline(prompt, true)
+    end
+    # :nocov:
+
+    def tty?
+      stdin.tty?
+    end
+
+    def stderr_tty?
+      stderr.tty?
+    end
+
+    # Home directory of a named user for ~user tilde expansion, or nil if there
+    # is no such user.
+    def home_dir(name)
+      Etc.getpwnam(name).dir
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/rush/terminal.rb

@@ -0,0 +1,126 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # The shell's grip on its controlling terminal under job control
+  # (rush-mv8.3): who to hand it to, how to take it back, and what to restore
+  # when monitor turns off. Acquired by JobControl#enable, dash's setjobctl:
+  # `home` is the shell's own process group once it has made itself a leader,
+  # `initial` the foreground group found at acquisition — where the terminal
+  # returns on `set +m`. Durable job-control state, so it lives on the
+  # JobTable beside the root-shell bit; forked children drop it with the rest
+  # of the table.
+  class Terminal
+    extend T::Sig
+
+    # dash setjobctl(1): find the tty, wait until the shell is in the
+    # foreground, remember the terminal's owner, then become a process-group
+    # leader and take the terminal. Probed: the dance runs whenever the tty
+    # is reachable — interactive or not — and only an interactive shell (the
+    # caller's concern) treats its failure as an error.
+    sig { params(system: SystemCalls).returns(T.nilable(Terminal)) }
+    def self.acquire(system)
+      tty = system.open_tty
+      return unless tty
+
+      initial = wait_foreground(system, tty)
+      initial ? take(system, tty, initial) : abandon(tty)
+    end
+
+    # Wait for the foreground: a shell started in the background must not
+    # steal the terminal, so it stops itself (SIGTTIN to its own group, the
+    # OS default for a background tty read) until a job-control parent
+    # brings it to the front — dash's killpg(0, SIGTTIN) loop. An unreadable
+    # foreground group (tcgetpgrp answering nothing) falls out as nil.
+    sig { params(system: SystemCalls, tty: T.untyped).returns(T.nilable(Integer)) }
+    def self.wait_foreground(system, tty)
+      while (pgrp = system.tcgetpgrp(tty))
+        return pgrp if pgrp == system.pgrp
+
+        system.kill('TTIN', 0)
+      end
+    end
+
+    # Become a process-group leader and take the tty (dash: setpgid(0,
+    # rootpid); xtcsetpgrp): `home` — where foreground jobs return the
+    # terminal — is the shell's own group, its pid, from here on.
+    sig { params(system: SystemCalls, tty: T.untyped, initial: Integer).returns(Terminal) }
+    def self.take(system, tty, initial)
+      system.setpgid(0, 0)
+      new(system: system, tty: tty, home: system.pid, initial: initial).tap(&:reclaim)
+    end
+
+    # A tty whose foreground group cannot be read is no terminal at all
+    # (dash: tcgetpgrp failing is the "can't access tty" case).
+    sig { params(tty: T.untyped).returns(NilClass) }
+    def self.abandon(tty)
+      tty.close
+      nil
+    end
+
+    # The parent-side handover around a foreground wait: give for the
+    # block, reclaim after — bare when no terminal is held (or for a fake
+    # fork's pid-0 launch).
+    sig do
+      type_parameters(:U)
+        .params(terminal: T.nilable(Terminal), leader: Integer, blk: T.proc.returns(T.type_parameter(:U)))
+        .returns(T.type_parameter(:U))
+    end
+    def self.while_held(terminal, leader, &blk)
+      return yield unless terminal && leader.positive?
+
+      terminal.while_given(leader, &blk)
+    end
+
+    private_class_method :wait_foreground, :take, :abandon
+
+    sig { returns(T.untyped) }
+    attr_reader :tty
+
+    sig { params(system: SystemCalls, tty: T.untyped, home: Integer, initial: Integer).void }
+    def initialize(system:, tty:, home:, initial:)
+      @system = system
+      @tty = tty
+      @home = home
+      @initial = initial
+    end
+
+    # Hand the terminal to a foreground job's process group (dash forkchild).
+    sig { params(pgid: Integer).void }
+    def give(pgid)
+      @system.tcsetpgrp(@tty, pgid)
+    end
+
+    # Take the terminal back once the foreground job settles (dash
+    # waitforjob).
+    sig { void }
+    def reclaim
+      give(@home)
+    end
+
+    # A foreground job's whole run: the job's group holds the terminal for
+    # the duration of the block (the wait), and the shell takes it back
+    # however the wait ends.
+    sig do
+      type_parameters(:U)
+        .params(pgid: Integer, blk: T.proc.returns(T.type_parameter(:U)))
+        .returns(T.type_parameter(:U))
+    end
+    def while_given(pgid, &blk)
+      give(pgid)
+      yield
+    ensure
+      reclaim
+    end
+
+    # `set +m`: the terminal returns to whoever owned it at acquisition, the
+    # shell rejoins that group, and the tty handle is released (dash
+    # setjobctl(0)).
+    sig { void }
+    def restore
+      give(@initial)
+      @system.setpgid(0, @initial)
+      @tty.close
+    end
+  end
+end

data/lib/rush/trap_runner.rb

@@ -0,0 +1,169 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Owns the executor's signal/trap handling: it records a trap, installs or
+  # clears the matching OS disposition, runs a delivered signal's action (with $?
+  # preserved, POSIX 2.14), and runs the EXIT trap as the shell terminates. Trap
+  # bodies are parsed and run back through the executor, so this collaborates with
+  # it rather than re-implementing execution.
+  class TrapRunner
+    extend T::Sig
+
+    sig { params(executor: Executor).void }
+    def initialize(executor)
+      @executor = executor
+      @exit_trap = ExitTrap.new(executor)
+      @pending = PendingSignals.new
+      @base = T.let(
+        {}, #: Hash[String, Proc]
+        T::Hash[String, Proc]
+      )
+    end
+
+    # The session's base dispositions (the interactive INT/QUIT/TERM handlers):
+    # what `trap - SIG` and an untouched signal fall back to instead of the OS
+    # default. Subshells drop them (POSIX: caught signals reset in subshells).
+    sig { params(handlers: T::Hash[String, Proc]).void }
+    def install_base(handlers)
+      @base = handlers
+      handlers.each_key { |name| install_signal(name, :default) }
+    end
+
+    # Flip one base disposition without disturbing the rest — `set -m` adds and
+    # removes SIGTSTP's this way mid-session (nil removes). A user trap on the
+    # signal keeps the disposition it installed (dash-verified in both orders);
+    # the base table still updates underneath, so a later `trap -` falls back
+    # correctly.
+    sig { params(name: String, handler: T.nilable(Proc)).void }
+    def set_base(name, handler)
+      @base.delete(name)
+      @base[name] = handler if handler
+      install_signal(name, :default) unless state.traps.action(name)
+    end
+
+    # Run the EXIT trap (if any) as the shell terminates, returning the status the
+    # shell exits with: the given code, unless the trap itself runs `exit`. $?
+    # inside the trap is that same code (POSIX 2.14), so it is published first.
+    sig { params(code: Integer).returns(Integer) }
+    def run_exit_trap(code)
+      run_pending
+      @exit_trap.run(code)
+    end
+
+    # Evaluate caught traps only at explicit shell checkpoints, never from the
+    # Ruby Signal.trap callback. No delivery guard: dash permits nested and
+    # same-signal traps to run at command boundaries inside an action.
+    sig { void }
+    def run_pending
+      @pending.drain { |name| deliver(name) }
+    end
+
+    sig { params(status: Status).returns(Status) }
+    def complete(status)
+      state.record_status(status).tap { run_pending }
+    end
+
+    sig { returns(T::Boolean) }
+    def pending?
+      @pending.any?
+    end
+
+    sig { returns(T.nilable(Integer)) }
+    def pending_exitstatus
+      @pending.first&.then { |name| Signals.number(name) + 128 }
+    end
+
+    # The status a bare `exit` reports: while the EXIT trap runs, the status the
+    # shell is terminating with (POSIX), not the trap body's last $?; otherwise
+    # the last command's status.
+    sig { returns(Integer) }
+    def exiting_status
+      @exit_trap.status
+    end
+
+    # Record a trap and (for real signals, not EXIT) install its disposition so a
+    # delivered signal runs the action / is ignored / restores the default.
+    sig { params(name: String, action: String).void }
+    def set(name, action)
+      state.traps.set(name, action)
+      install_signal(name, action)
+    end
+
+    sig { params(name: String).void }
+    def reset(name)
+      state.traps.clear(name)
+      install_signal(name, :default)
+    end
+
+    sig { void }
+    def reset_caught_for_subshell
+      @exit_trap = ExitTrap.new(@executor)
+      @pending.clear
+      drop_base
+      state.traps.reset_caught.each { |name| install_signal(name, :default) }
+    end
+
+    private
+
+    sig { returns(ShellState) }
+    def state
+      @executor.state
+    end
+
+    sig { params(action: String).void }
+    def fire(action)
+      @executor.run(Parser.new(Lexer.new(action, aliases: state.aliases)).parse)
+    rescue Error => e
+      raise unless ErrorPolicy.decision(:signal_trap, e) == :ignore
+    end
+
+    # An untrappable signal (KILL/STOP) raises; keep the table entry like dash.
+    sig { params(name: String, action: T.any(String, Symbol)).void }
+    def install_signal(name, action)
+      return if name == Signals::EXIT
+
+      install(name, disposition(action))
+    rescue ArgumentError, SystemCallError
+      nil
+    end
+
+    # :default falls back to the session's base handler when one is installed
+    # (an interactive shell survives INT/QUIT/TERM); otherwise the OS default.
+    sig { params(name: String, disposition: T.nilable(String)).void }
+    def install(name, disposition)
+      base = @base.fetch(name, nil)
+      return @executor.system.trap_signal(name, nil) { base.call } if disposition == 'SYSTEM_DEFAULT' && base
+
+      @executor.system.trap_signal(name, disposition) { @pending.record(name) }
+    end
+
+    # Subshells reset the base handlers to the true OS default before the
+    # per-trap reset, so a forked child dies on ^C like any non-interactive
+    # process.
+    sig { void }
+    def drop_base
+      dropped = @base
+      @base = {}
+      dropped.each_key { |name| install_signal(name, :default) }
+    end
+
+    # '' ignores the signal; :default restores the true OS disposition
+    # (SYSTEM_DEFAULT = SIG_DFL — Ruby's plain 'DEFAULT' instead simulates the
+    # signal by raising, which dies as an uncaught-exception traceback where
+    # dash dies silently by signal); a command string installs the handler
+    # block (nil disposition), matching SystemCalls#trap_signal.
+    sig { params(action: T.any(String, Symbol)).returns(T.nilable(String)) }
+    def disposition(action)
+      { '' => 'IGNORE', :default => 'SYSTEM_DEFAULT' }.fetch(action, nil)
+    end
+
+    # Run a delivered signal's action, restoring $? so the interrupted code is
+    # unaffected (POSIX 2.14); an `exit` in the action propagates and terminates.
+    sig { params(name: String).void }
+    def deliver(name)
+      action = state.traps.action(name)
+      state.preserve_status { fire(action) } if action
+    end
+  end
+end

data/lib/rush/trap_table.rb

@@ -0,0 +1,49 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # The shell's trap actions, keyed by canonical signal name (see Rush::Signals).
+  # An action is the command string to run when the signal fires; "" means the
+  # signal is ignored. Resetting a signal drops its entry, restoring the default.
+  class TrapTable
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @actions = {}
+    end
+
+    sig { params(name: String, action: String).returns(String) }
+    def set(name, action)
+      @actions[name] = action
+    end
+
+    sig { params(name: String).returns(T.nilable(String)) }
+    def clear(name)
+      @actions.delete(name)
+    end
+
+    sig { params(name: String).returns(T.nilable(String)) }
+    def action(name)
+      @actions.fetch(name, nil)
+    end
+
+    sig { returns(T::Array[String]) }
+    def reset_caught
+      caught.each { |name| @actions.delete(name) }
+    end
+
+    # [name, action] pairs ordered by signal number, for `trap` with no operands.
+    sig { returns(T::Array[[String, String]]) }
+    def listing
+      @actions.sort_by { |name, _action| Signals.number(name) }
+    end
+
+    private
+
+    sig { returns(T::Array[String]) }
+    def caught
+      @actions.filter_map { |name, action| name unless action.empty? }
+    end
+  end
+end