rush-shell 0.0.2

data/lib/rush/builtins/false_.rb

@@ -0,0 +1,16 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `false` — does nothing, fails (status 1).
+    class False < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        failure
+      end
+    end
+  end
+end

data/lib/rush/builtins/fd_operand.rb

@@ -0,0 +1,87 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # Resolves test/[ operands that name shell file descriptors through the
+    # command's logical IoTable. In production, a redirected File/pipe/tty has a
+    # real fileno; rewriting to that descriptor lets the kernel's existing
+    # File/IO predicates answer exactly as if the shell had applied dup2.
+    class FdOperand
+      extend T::Sig
+
+      PATH_OPERATORS = %w[-e -f -d -r -w -x -s -p -b -c -S -g -u].freeze
+      STANDARD_PATHS = { '/dev/stdin' => 0, '/dev/stdout' => 1, '/dev/stderr' => 2 }.freeze
+      FD_PATH = %r{\A/(?:dev|proc/self)/fd/(\d+)\z}
+      CLOSED_PATH = '/dev/fd/-'
+      CLOSED_DESCRIPTOR = '-1'
+
+      sig { params(io: IoTable).void }
+      def initialize(io)
+        @io = io
+      end
+
+      sig { params(operator: String, operand: String).returns(String) }
+      def resolve(operator, operand)
+        return descriptor(operand) if operator == '-t'
+        return operand unless PATH_OPERATORS.include?(operator)
+
+        path(operand)
+      end
+
+      private
+
+      # Steep 2 crashes internally on &:to_s here, so keep the explicit block.
+      # rubocop:disable Style/SymbolProc
+      sig { params(operand: String).returns(String) }
+      def descriptor(operand)
+        fd = integer(operand)
+        fd ? rewrite(fd, operand, CLOSED_DESCRIPTOR) { |fileno| fileno.to_s } : operand
+      end
+      # rubocop:enable Style/SymbolProc
+
+      sig { params(operand: String).returns(String) }
+      def path(operand)
+        fd = path_fd(operand)
+        fd ? rewrite(fd, operand, CLOSED_PATH) { |fileno| "/dev/fd/#{fileno}" } : operand
+      end
+
+      sig do
+        params(fd: Integer, original: String, closed: String,
+               blk: T.proc.params(fileno: Integer).returns(String)).returns(String)
+      end
+      def rewrite(fd, original, closed, &blk)
+        entry = @io.entry(fd)
+        return original unless entry
+        return closed if entry.closed?
+
+        replacement(entry, original, &blk)
+      end
+
+      sig do
+        params(entry: FdEntry, original: String,
+               blk: T.proc.params(fileno: Integer).returns(String)).returns(String)
+      end
+      def replacement(entry, original, &blk)
+        fileno = entry.stream.fileno
+        fileno ? yield(fileno) : original
+      rescue IOError, SystemCallError
+        original
+      end
+
+      sig { params(operand: String).returns(T.nilable(Integer)) }
+      def path_fd(operand)
+        standard = STANDARD_PATHS.fetch(operand, nil)
+        return standard if standard
+
+        match = FD_PATH.match(operand)
+        integer(match[1].to_s) if match
+      end
+
+      sig { params(text: String).returns(T.nilable(Integer)) }
+      def integer(text)
+        Integer(text, 10) if text.match?(/\A\s*\+?\d+\s*\z/)
+      end
+    end
+  end
+end

data/lib/rush/builtins/getopts.rb

@@ -0,0 +1,96 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `getopts optstring name [args...]` — parse one POSIX short option per call,
+    # storing the option in `name`, the next public position in OPTIND and any
+    # option argument in OPTARG. A leading ':' in optstring enables silent error
+    # mode for bad options / missing arguments.
+    class Getopts < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        return usage if operands.size < 2
+
+        apply(GetoptsParser.new(state: state, optstring: optstring, arguments: arguments, optind: optind).call)
+      end
+
+      private
+
+      sig { returns(Status) }
+      def usage
+        report('getopts: Usage: getopts optstring var [arg...]')
+        failure(2)
+      end
+
+      sig { params(result: GetoptsParser::Result).returns(Status) }
+      def apply(result)
+        store(result)
+        report_message(result.message)
+        Status.new(result.exitstatus)
+      end
+
+      # The variable updates a getopts step produces: `name`, OPTARG, OPTIND.
+      sig { params(result: GetoptsParser::Result).void }
+      def store(result)
+        variables.assign(name, result.name)
+        update_optarg(result.optarg)
+        variables.assign('OPTIND', result.optind.to_s)
+      end
+
+      sig { params(value: T.untyped).void }
+      def update_optarg(value)
+        return if value.is_a?(Symbol) # GetoptsParser::KEEP, the only Symbol optarg
+
+        value ? variables.assign('OPTARG', value) : variables.unset('OPTARG')
+      end
+
+      sig { params(message: T.nilable(String)).void }
+      def report_message(message)
+        report(message) if message
+      end
+
+      sig { params(message: String).void }
+      def report(message)
+        stderr.puts(message)
+      rescue Errno::EBADF
+        nil
+      end
+
+      sig { returns(Integer) }
+      def optind
+        value = Integer(variables.get('OPTIND') || '1', 10)
+        value.positive? ? value : 1
+      rescue ArgumentError
+        1
+      end
+
+      sig { returns(T::Array[String]) }
+      def arguments
+        operands.drop(2).empty? ? executor.state.positional.to_a : operands.drop(2)
+      end
+
+      sig { returns(String) }
+      def optstring
+        operands.fetch(0)
+      end
+
+      sig { returns(String) }
+      def name
+        operands.fetch(1)
+      end
+
+      sig { returns(GetoptsState) }
+      def state
+        executor.state.getopts
+      end
+
+      sig { returns(ShellVariables) }
+      def variables
+        executor.state.variables
+      end
+    end
+  end
+end

data/lib/rush/builtins/hash.rb

@@ -0,0 +1,64 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `hash [-r] [name ...]` — the command-location cache. With names, look each up
+    # in PATH and remember it; a name containing a slash or naming a builtin /
+    # function / keyword is a silent no-op, an unresolvable name an error (status
+    # 1). `-r` forgets all. With no operands, list the remembered locations, one
+    # path per line, sorted by name.
+    #
+    # Divergence: rush does not auto-populate the cache as commands run (POSIX/dash
+    # remember a utility's location when it is used); only an explicit `hash name`
+    # records one. Observable only via `<cmd>; hash` and noted in the journal — the
+    # cache is otherwise bit-for-bit consistent with dash.
+    class Hash < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        return reset if operands.first == '-r'
+
+        operands.empty? ? list : remember(operands)
+      end
+
+      private
+
+      sig { returns(T::Hash[String, String]) }
+      def cache
+        executor.state.command_hash
+      end
+
+      sig { returns(Status) }
+      def reset
+        cache.clear
+        success
+      end
+
+      sig { returns(Status) }
+      def list
+        cache.sort.each { |_name, path| stdout.puts(path) }
+        success
+      end
+
+      sig { params(names: T::Array[String]).returns(Status) }
+      def remember(names)
+        missing = names.reject { |name| known?(name) }
+        missing.each { |name| stderr.puts("rush: hash: #{name}: not found") }
+        missing.empty? ? success : failure
+      end
+
+      # Whether the name is a known command; a resolvable PATH command is also
+      # cached (a slash path or a builtin / function is known but not cached).
+      sig { params(name: String).returns(T::Boolean) }
+      def known?(name)
+        return true if name.include?('/')
+
+        match = CommandLookup.new(executor).find(name)
+        match.cache_into(cache)
+        match.known?
+      end
+    end
+  end
+end

data/lib/rush/builtins/job_resume.rb

@@ -0,0 +1,107 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # Shared base of fg and bg: resolve each %id operand (no operand means
+    # the current job, and an empty table is "No current job", like dash),
+    # refuse a job that was not created under job control — dash's per-job
+    # jobctl bit, independent of the monitor flag now in force (probed
+    # across set -m/+m flips) — and resume survivors with SIGCONT to the
+    # job's process group. dash loops multiple operands for both commands;
+    # the last one's status is the builtin's.
+    class JobResume < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        specs = operands.empty? ? [nil] : operands
+        specs.map { |spec| resume_one(spec) }.fetch(-1)
+      rescue JobError => e
+        bad(e.message)
+      end
+
+      private
+
+      # A job outside job control aborts the whole command (dash's sh_error:
+      # later operands never run), through the same status-2 error path as a
+      # bad %id.
+      sig { params(spec: T.nilable(String)).returns(Status) }
+      def resume_one(spec)
+        job = JobSpec.resolve(executor.jobs, spec || '%+')
+        raise JobError, refusal(spec) unless job.controlled?
+
+        resume(job)
+      end
+
+      # The subclass's whole move: bg lists and leaves the job running in
+      # the background; fg reattaches and waits.
+      sig { params(_job: JobTable::Job).returns(Status) }
+      def resume(_job)
+        # :nocov: overridden by fg/bg
+        raise NotImplementedError
+        # :nocov:
+      end
+
+      sig { params(spec: T.nilable(String)).returns(String) }
+      def refusal(spec)
+        spec ? "job #{spec} not created under job control" : 'job not created under job control'
+      end
+
+      sig { params(message: String).returns(Status) }
+      def bad(message)
+        stderr.puts("#{argv.fetch(0)}: #{message}")
+        failure(2)
+      end
+    end
+
+    # `fg [%id...]`: bring a job to the foreground — the command line goes
+    # to stdout (an empty placeholder until the command-text column lands
+    # with rush-mv8.6), SIGCONT resumes the group, the terminal follows it
+    # (JobControl#foreground), and the shell waits as for any foreground
+    # job: the job's status becomes $?, a ^Z parks it Stopped again under
+    # the same number, and a finished job leaves the table (dash frees the
+    # entry it fg-waited).
+    class Fg < JobResume
+      extend T::Sig
+
+      private
+
+      sig { params(job: JobTable::Job).returns(Status) }
+      def resume(job)
+        stdout.puts(job.text)
+        executor.job_control.foreground(job.members, text: job.text) do
+          job.continue(executor.system)
+          settle(job)
+        end
+      end
+
+      # A finished job answers from memory (dash's fg on a dead-but-
+      # remembered entry: getstatus, probed 137); a live one waits every
+      # member (JobTable#settle_members). Either way a signal death reports
+      # like any foreground wait's (dash: fg + kill prints Killed).
+      sig { params(job: JobTable::Job).returns(Status) }
+      def settle(job)
+        verdict = SignalReport.report(job.finished? ? job.status : executor.jobs.settle_members(job), stderr)
+        executor.jobs.forget(job) unless verdict.stopped?
+        verdict
+      end
+    end
+
+    # `bg [%id...]`: resume a stopped job in the background — "[n] " and the
+    # (mv8.6) command line to stdout, SIGCONT, the entry runs on in the
+    # table and the terminal stays with the shell.
+    class Bg < JobResume
+      extend T::Sig
+
+      private
+
+      sig { params(job: JobTable::Job).returns(Status) }
+      def resume(job)
+        job.continue(executor.system)
+        stdout.puts("[#{job.number}] #{job.text}")
+        success
+      end
+    end
+  end
+end

data/lib/rush/builtins/jobs.rb

@@ -0,0 +1,86 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `jobs [-l|-p] [%id...]`: list background jobs, newest first, + and -
+    # marking the current and previous job, states Running / Done / Done(n) /
+    # a signal description. -l inserts the pid after the mark; -p prints only
+    # pids. The command column (34) stays empty away from a tty, exactly like
+    # dash, which keeps no command text there. Displaying a finished job
+    # frees its entry (-p does not); a bad %id reports No such job with
+    # status 2 after the entries already rendered (dash-verified).
+    class Jobs < Base
+      extend T::Sig
+
+      # The flag picks a rendering style; anything else is an illegal option.
+      STYLES = T.let({ nil => :short_line, '-l' => :long_line, '-p' => :pid_line }.freeze,
+                     T::Hash[T.nilable(String), Symbol])
+
+      sig { returns(Status) }
+      def call
+        executor.jobs.poll
+        flag, args = split_flag(operands)
+        STYLES.key?(flag) ? show(STYLES.fetch(flag), args) : bad("Illegal option #{flag}")
+      rescue JobError => e
+        bad(e.message)
+      end
+
+      private
+
+      # tuple: the optional leading -flag and the remaining %id operands.
+      sig { params(args: T::Array[String]).returns([T.nilable(String), T::Array[String]]) }
+      def split_flag(args)
+        args.first&.start_with?('-') ? [args.fetch(0), args.drop(1)] : [nil, args]
+      end
+
+      sig { params(style: Symbol, args: T::Array[String]).returns(Status) }
+      def show(style, args)
+        line = method(style)
+        each_selected(args) { |job| line.call(job) }
+        success
+      end
+
+      # Resolution stays interleaved with rendering so a bad %id aborts after
+      # the entries before it have already been printed, as dash does.
+      sig { params(args: T::Array[String], blk: T.proc.params(job: JobTable::Job).returns(T.untyped)).void }
+      def each_selected(args, &blk)
+        return executor.jobs.ordered.each(&blk) if args.empty?
+
+        args.each { |spec| yield(JobSpec.resolve(executor.jobs, spec)) }
+      end
+
+      sig { params(job: JobTable::Job).void }
+      def pid_line(job)
+        stdout.puts(job.pid)
+      end
+
+      sig { params(job: JobTable::Job).void }
+      def long_line(job)
+        report(job, "#{job.pid} ")
+      end
+
+      sig { params(job: JobTable::Job).void }
+      def short_line(job)
+        report(job, '')
+      end
+
+      # dash's showjob line (JobReport). Displaying counts as reporting (no
+      # pre-prompt notification follows), a displayed finished job is freed —
+      # a Stopped one is not: it is still alive, and dash keeps listing it
+      # (probed) — and the bare-pid style never frees or reports.
+      sig { params(job: JobTable::Job, pid_field: String).void }
+      def report(job, pid_field)
+        stdout.puts(JobReport.line(executor.jobs, job, pid_field))
+        job.reported
+        executor.jobs.forget(job) if job.finished?
+      end
+
+      sig { params(message: String).returns(Status) }
+      def bad(message)
+        stderr.puts("jobs: #{message}")
+        failure(2)
+      end
+    end
+  end
+end

data/lib/rush/builtins/kill.rb

@@ -0,0 +1,152 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `kill [-s sigspec | -sigspec | -signum] pid|%id...` sends a signal (TERM
+    # by default) to each process; `kill -0 pid` only checks that it exists.
+    # Signal names follow Rush::Signals (case-insensitive, no "SIG" prefix);
+    # numbers go straight to the OS so the unnamed ones (16, RT, ...) still
+    # work. A %id targets the job's process group (-pid, as dash) — without
+    # the terminal half of job control no such group exists, so delivery
+    # fails "no such process", status 1, and the job survives (dash parity).
+    # `kill -l N` prints the signal name for a number or wait status (128 +
+    # signal), and a bare `kill -l` lists the known names. A bad spec or an
+    # unresolved %id exits 2; a delivery that fails exits 1.
+    class Kill < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        return usage if operands.empty?
+        return list(operands.drop(1)) if operands.first == '-l'
+
+        spec, pids = parse
+        send_signal(spec, pids)
+      end
+
+      private
+
+      # tuple, not Array: parse is destructured into send_signal's two arguments.
+      sig { returns([String, T::Array[String]]) }
+      # mutant:disable -- for incomplete `-s`, the returned sigspec is ignored:
+      # `send_signal` reports usage before resolving any signal when no pid exists.
+      def parse
+        first = operands.fetch(0)
+        return [operands.fetch(1, ''), operands.drop(2)] if first == '-s'
+        return [first.delete_prefix('-'), operands.drop(1)] if flag?(first)
+
+        ['TERM', operands]
+      end
+
+      sig { params(arg: String).returns(T::Boolean) }
+      def flag?(arg)
+        arg.start_with?('-') && !arg.eql?('-')
+      end
+
+      sig { params(spec: String, pids: T::Array[String]).returns(Status) }
+      def send_signal(spec, pids)
+        return usage if pids.empty?
+
+        signal = resolve(spec)
+        signal ? deliver(signal, pids) : bad("#{spec}: invalid signal specification")
+      rescue JobError => e
+        bad(e.message)
+      end
+
+      # A numeric spec goes straight to the OS (Integer); a name decodes to its
+      # canonical String, or nil when the spec is unknown.
+      sig { params(spec: String).returns(T.nilable(T.any(Integer, String))) }
+      def resolve(spec)
+        return Integer(spec) if spec.match?(/\A\d+\z/)
+
+        Signals.decode(spec)
+      end
+
+      sig { params(signal: T.any(Integer, String), pids: T::Array[String]).returns(Status) }
+      def deliver(signal, pids)
+        failed = pids.reject { |pid| send_to(signal, pid) }
+        failed.empty? ? success : failure
+      end
+
+      # Returns a truthy OS delivery count on success, nil when delivery failed.
+      sig { params(signal: T.any(Integer, String), pid: String).returns(T.nilable(Integer)) }
+      def send_to(signal, pid)
+        target = os_target(pid)
+        executor.system.kill(signal, target)
+      rescue SystemCallError, ArgumentError, TypeError
+        oops("#{pid}: no such process")
+      end
+
+      # A %id names the job's process group: negative pid, like dash. An
+      # unresolved %id raises JobError past the delivery loop (status 2).
+      sig { params(pid: String).returns(Integer) }
+      def os_target(pid)
+        return -JobSpec.resolve(executor.jobs, pid).pid if pid.start_with?('%')
+
+        Integer(pid)
+      end
+
+      sig { params(args: T::Array[String]).returns(Status) }
+      def list(args)
+        args.empty? ? list_all : list_one(args.fetch(0))
+      end
+
+      sig { returns(Status) }
+      def list_all
+        Signals::NUMBERS.each { |num, name| stdout.puts(name) if num.nonzero? }
+        success
+      end
+
+      sig { params(arg: String).returns(Status) }
+      def list_one(arg)
+        name = listed_signal_name(arg)
+        name ? ok(name) : invalid_signal(arg)
+      end
+
+      sig { params(arg: String).returns(T.nilable(String)) }
+      def listed_signal_name(arg)
+        return unless arg.match?(/\A\d+\z/)
+
+        num = adjust(Integer(arg))
+        return unless num.positive?
+
+        Signals::NUMBERS.fetch(num, nil)
+      end
+
+      sig { params(num: Integer).returns(Integer) }
+      # mutant:disable -- for `kill -l 128`, `128` and `0` are both invalid;
+      # changing the wait-status boundary is observationally equivalent there.
+      def adjust(num)
+        num >= 129 ? num - 128 : num
+      end
+
+      sig { params(name: String).returns(Status) }
+      def ok(name)
+        stdout.puts(name)
+        success
+      end
+
+      sig { params(spec: T.nilable(String)).returns(Status) }
+      def invalid_signal(spec)
+        bad("#{spec}: invalid signal specification")
+      end
+
+      sig { returns(Status) }
+      def usage
+        bad('usage: kill [-s sigspec | -signum] pid ...')
+      end
+
+      sig { params(message: String).returns(Status) }
+      def bad(message)
+        stderr.puts("kill: #{message}")
+        failure(2)
+      end
+
+      sig { params(message: String).returns(NilClass) }
+      def oops(message)
+        stderr.puts("kill: #{message}")
+      end
+    end
+  end
+end

data/lib/rush/builtins/local.rb

@@ -0,0 +1,40 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `local name[=value] ...` — inside a function, mark each name as local so its
+    # prior value is restored when the function returns. A bare name keeps its
+    # current value (dash semantics); name=value also assigns. Used outside a
+    # function it is an error with status 2.
+    class Local < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        return not_in_function unless state.variables.in_function?
+
+        operands.each { |operand| declare(operand) }
+        success
+      end
+
+      private
+
+      sig { returns(ShellState) }
+      def state
+        executor.state
+      end
+
+      sig { params(operand: String).void }
+      def declare(operand)
+        state.variables.declare_local_operand(operand)
+      end
+
+      sig { returns(Status) }
+      def not_in_function
+        stderr.puts('rush: local: not in a function')
+        failure(2)
+      end
+    end
+  end
+end

data/lib/rush/builtins/loop_jump.rb

@@ -0,0 +1,45 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # Shared engine of `break` and `continue` (POSIX 2.9.5). Both are successful
+    # builtins, so they set $? to 0 before unwinding: the status is seen after
+    # the loop, and by the next iteration's body. With no enclosing loop the
+    # builtin is a no-op; a level past the actual nesting is clamped, so
+    # `break 5` in two loops exits both. The level (>= 1) is validated even
+    # with no loop, so `break abc` still aborts. Subclasses name the signal
+    # that carries the level up to the enclosing loop runner.
+    class LoopJump < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        level = validated
+        executor.state.record_status(success)
+        raise signal, clamped(level) if executor.state.loops.any?
+
+        success
+      end
+
+      private
+
+      # The LoopControl subclass this builtin unwinds with.
+      sig { returns(T.class_of(LoopControl)) }
+      def signal
+        raise NotImplementedError
+      end
+
+      sig { returns(Integer) }
+      def validated
+        first = operands.first
+        first ? numeric_operand(first, min: 1) : 1
+      end
+
+      sig { params(level: Integer).returns(Integer) }
+      def clamped(level)
+        [level, executor.state.loops.depth].min
+      end
+    end
+  end
+end