rush-shell 0.0.2

data/lib/rush/builtins/cd.rb

@@ -0,0 +1,127 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `cd [dir]` — change the working directory, maintaining a *logical* PWD
+    # (not Dir.pwd, which resolves symlinks) plus OLDPWD. Defaults to $HOME.
+    class Cd < Base
+      extend T::Sig
+
+      # A CDPATH resolution result: the path to chdir to, and whether POSIX
+      # requires printing the resolved logical directory after a successful cd.
+      Target = Data.define(:path, :echo)
+
+      sig { returns(Status) }
+      def call
+        target = operands.first || executor.state.variables.get('HOME')
+        return report('HOME not set') unless target
+
+        target == '-' ? change_back : change_to(target)
+      end
+
+      private
+
+      sig { params(dir: String).returns(Status) }
+      def change_to(dir)
+        target = resolve_cdpath(dir)
+        perform_chdir(target.path)
+        success_after_cdpath(target)
+      rescue Errno::ENOENT, Errno::ENOTDIR
+        report("#{dir}: No such file or directory")
+      end
+
+      sig { returns(Status) }
+      def change_back
+        dir = oldpwd
+        perform_chdir(dir)
+        success_with_echo
+      rescue Errno::ENOENT, Errno::ENOTDIR
+        report("#{dir}: No such file or directory")
+      end
+
+      sig { returns(String) }
+      def oldpwd
+        executor.state.variables.get('OLDPWD') || executor.state.variables.current_pwd
+      end
+
+      sig { params(dir: String).returns(Target) }
+      def resolve_cdpath(dir)
+        return Target.new(path: dir, echo: false) unless search_cdpath?(dir)
+
+        cdpath_targets(dir).find { |target| executor.system.directory?(target.path) } ||
+          Target.new(path: dir, echo: false)
+      end
+
+      sig { params(dir: String).returns(T::Boolean) }
+      def search_cdpath?(dir)
+        cdpath? && relative_cdpath_operand?(dir)
+      end
+
+      sig { params(dir: String).returns(T::Boolean) }
+      def relative_cdpath_operand?(dir)
+        !dir.start_with?('/') && !%w[. ..].include?(dir.split('/', 2).first)
+      end
+
+      sig { returns(T::Boolean) }
+      def cdpath?
+        !!executor.state.variables.get('CDPATH')
+      end
+
+      sig { params(dir: String).returns(T::Array[Target]) }
+      def cdpath_targets(dir)
+        cdpath_entries.map { |prefix| cdpath_target(prefix, dir) }
+      end
+
+      sig { returns(T::Array[String]) }
+      def cdpath_entries
+        T.must(executor.state.variables.get('CDPATH')).split(':', -1)
+      end
+
+      sig { params(prefix: String, dir: String).returns(Target) }
+      def cdpath_target(prefix, dir)
+        Target.new(path: cdpath_path(prefix, dir), echo: cdpath_echo?(prefix))
+      end
+
+      sig { params(prefix: String, dir: String).returns(String) }
+      def cdpath_path(prefix, dir)
+        prefix.empty? ? dir : "#{prefix}/#{dir}"
+      end
+
+      sig { params(prefix: String).returns(T::Boolean) }
+      def cdpath_echo?(prefix)
+        !prefix.empty?
+      end
+
+      sig { params(dir: String).void }
+      def perform_chdir(dir)
+        executor.system.chdir(dir)
+        update_pwd(dir)
+      end
+
+      sig { returns(Status) }
+      def success_with_echo
+        stdout.puts(executor.state.variables.current_pwd)
+        success
+      end
+
+      sig { params(target: Target).returns(Status) }
+      def success_after_cdpath(target)
+        target.echo ? success_with_echo : success
+      end
+
+      sig { params(dir: String).void }
+      def update_pwd(dir)
+        variables = executor.state.variables
+        variables.move_to(executor.system.expand_path(dir, variables.current_pwd))
+      end
+
+      # A failed cd exits 2, matching the dash oracle (POSIX only asks for >0).
+      sig { params(message: String).returns(Status) }
+      def report(message)
+        stderr.puts("rush: cd: #{message}")
+        failure(2)
+      end
+    end
+  end
+end

data/lib/rush/builtins/colon.rb

@@ -0,0 +1,16 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `:` — the null command; expands its arguments and always succeeds.
+    class Colon < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        success
+      end
+    end
+  end
+end

data/lib/rush/builtins/command.rb

@@ -0,0 +1,137 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `command [-p] name [arg ...]` runs name as a command, skipping shell
+    # functions (so a function can call the builtin it shadows); -p searches
+    # the system default PATH (confstr _CS_PATH) for an external instead of
+    # $PATH, without changing the child's environment. `command -v name`
+    # prints how name resolves — the name itself for a keyword / function /
+    # builtin, the path for an external — and -V the long `type` form; both
+    # exit 127 for an unknown name, 0 with no operand, and -V outranks -v.
+    class Command < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        opts = CommandOptions.new(operands)
+        bad = opts.illegal
+        bad ? illegal_option(bad) : dispatch(opts)
+      end
+
+      private
+
+      sig { params(opts: CommandOptions).returns(Status) }
+      def dispatch(opts)
+        return no_name(opts) unless opts.name
+        return verbose(opts) if opts.verbose?
+        return verify(opts) if opts.verify?
+
+        run(opts)
+      end
+
+      # dash exits 0 for a bare `command`, `command -v` and `command -V` alike
+      # (probed); the bare run form is the colon builtin's no-op.
+      sig { params(opts: CommandOptions).returns(Status) }
+      def no_name(opts)
+        return success if opts.verbose? || opts.verify?
+
+        Colon.new(executor, [], io).call
+      end
+
+      sig { params(opts: CommandOptions).returns(Status) }
+      def verify(opts)
+        print_terse(lookup(opts).find(opts.name))
+      end
+
+      sig { params(match: CommandLookup::Match).returns(Status) }
+      def print_terse(match)
+        return failure(127) unless match.known?
+
+        stdout.puts(match.terse)
+        success
+      end
+
+      sig { params(opts: CommandOptions).returns(Status) }
+      def verbose(opts)
+        print_description(T.must(opts.name), lookup(opts).find(opts.name))
+      end
+
+      sig { params(name: String, match: CommandLookup::Match).returns(Status) }
+      def print_description(name, match)
+        return not_described(name) unless match.known?
+
+        stdout.puts(match.describe)
+        success
+      end
+
+      sig { params(name: String).returns(Status) }
+      def not_described(name)
+        stdout.puts("#{name}: not found")
+        failure(127)
+      end
+
+      sig { params(opts: CommandOptions).returns(CommandLookup) }
+      def lookup(opts)
+        opts.default_path? ? default_lookup : CommandLookup.new(executor)
+      end
+
+      sig { returns(CommandLookup) }
+      def default_lookup
+        CommandLookup.new(executor, path: executor.system.default_path)
+      end
+
+      sig { params(opts: CommandOptions).returns(Status) }
+      def run(opts)
+        name = T.must(opts.name)
+        builtin = executor.builtins.lookup(name)
+        builtin ? run_builtin(builtin, opts) : run_external(name, opts)
+      end
+
+      sig { params(builtin: T.class_of(Base), opts: CommandOptions).returns(Status) }
+      def run_builtin(builtin, opts)
+        builtin.new(executor, opts.operands, io, command_environment).call
+      rescue Error => e
+        raise unless ErrorPolicy.decision(:command, e) == :demote2
+
+        demoted_error(e)
+      end
+
+      sig { params(error: StandardError).returns(Status) }
+      def demoted_error(error)
+        stderr.puts("rush: #{error.message}")
+        failure(2)
+      end
+
+      sig { params(name: String, opts: CommandOptions).returns(Status) }
+      def run_external(name, opts)
+        external = External.new(executor, opts.operands, io, command_environment)
+        return external.call unless opts.default_path?
+
+        run_on_default_path(name, external)
+      end
+
+      # The default-PATH resolution happens here in the shell (dash does the
+      # same): the resolved file is executed while argv[0] stays the name as
+      # typed, and $PATH is neither consulted nor mutated.
+      sig { params(name: String, external: External).returns(Status) }
+      def run_on_default_path(name, external)
+        path = default_lookup.executable_path(name)
+        path ? external.call_file(path) : not_found(name)
+      end
+
+      sig { params(name: String).returns(Status) }
+      def not_found(name)
+        stderr.puts("rush: #{name}: not found")
+        failure(127)
+      end
+
+      sig { params(letter: String).returns(Status) }
+      def illegal_option(letter)
+        stderr.puts("rush: command: Illegal option #{letter}")
+        failure(2)
+      end
+    end
+  end
+end

data/lib/rush/builtins/command_options.rb

@@ -0,0 +1,103 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # The parsed option prefix of the `command` builtin's argv: leading
+    # clusters of -p / -v / -V letters (repeats accumulate; -V outranks -v,
+    # as in dash), an optional `--` terminator, then the operands. A letter
+    # outside the set is recorded as `illegal` (e.g. '-z'), which `command`
+    # reports with status 2; `+x` or a lone `-` is an operand, not options.
+    class CommandOptions
+      extend T::Sig
+
+      LETTERS = T.let({ 'p' => :default_path, 'v' => :verify, 'V' => :verbose }.freeze,
+                      T::Hash[String, Symbol])
+
+      # A dash followed by letters, except the bare `--` terminator (a lone
+      # dash or a +cluster is an operand — dash-probed).
+      CLUSTER = /\A-(?!-\z)./
+
+      sig { returns(T::Array[String]) }
+      attr_reader :operands
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :illegal
+
+      sig { params(args: T::Array[String]).void }
+      def initialize(args)
+        @args = args
+        @flags = T.let([], T::Array[Symbol])
+        @illegal = T.let(nil, T.nilable(String))
+        @operands = T.let(consume, T::Array[String])
+      end
+
+      sig { returns(T.nilable(String)) }
+      def name
+        operands.first
+      end
+
+      sig { returns(T::Boolean) }
+      def default_path?
+        @flags.include?(:default_path)
+      end
+
+      sig { returns(T::Boolean) }
+      def verify?
+        @flags.include?(:verify)
+      end
+
+      sig { returns(T::Boolean) }
+      def verbose?
+        @flags.include?(:verbose)
+      end
+
+      private
+
+      sig { returns(T::Array[String]) }
+      def consume
+        index = count_clusters
+        @args.drop(arg_at(index) == '--' ? index + 1 : index)
+      end
+
+      sig { returns(Integer) }
+      def count_clusters
+        index = 0
+        index += 1 while take(index)
+        index
+      end
+
+      sig { params(index: Integer).returns(T::Boolean) }
+      def take(index)
+        return false unless cluster?(index)
+
+        arg_at(index).chars.drop(1).all? { |letter| record(letter) }
+      end
+
+      sig { params(index: Integer).returns(T::Boolean) }
+      def cluster?(index)
+        arg_at(index).match?(CLUSTER)
+      end
+
+      sig { params(index: Integer).returns(String) }
+      def arg_at(index)
+        @args.fetch(index, '')
+      end
+
+      # The letter's flag (feeding take's all?-driven cluster scan), nil once
+      # the letter proves illegal.
+      sig { params(letter: String).returns(T.nilable(Symbol)) }
+      def record(letter)
+        flag = LETTERS.fetch(letter) { record_illegal(letter) }
+        @flags << flag if flag
+        flag
+      end
+
+      sig { params(letter: String).returns(NilClass) }
+      def record_illegal(letter)
+        @illegal = "-#{letter}"
+        nil
+      end
+    end
+  end
+end

data/lib/rush/builtins/continue_.rb

@@ -0,0 +1,19 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `continue [n]` — resume the n-th enclosing loop's next iteration
+    # (default 1); the shared POSIX 2.9.5 semantics live in LoopJump.
+    class Continue < LoopJump
+      extend T::Sig
+
+      private
+
+      sig { returns(T.class_of(LoopControl)) }
+      def signal
+        ContinueSignal
+      end
+    end
+  end
+end

data/lib/rush/builtins/declare.rb

@@ -0,0 +1,27 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # Shared engine of `export` and `readonly`: each operand is `name[=value]` —
+    # the value is assigned first when one is given, then the subclass's marking
+    # applies on the variable table. Both always report success.
+    class Declare < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        operands.each { |operand| declare(operand) }
+        success
+      end
+
+      private
+
+      # Apply this builtin's marking to one name[=value] operand.
+      sig { params(_operand: String).void }
+      def declare(_operand)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/rush/builtins/defaults.rb

@@ -0,0 +1,28 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # The shell's builtin commands and the default name -> implementation table.
+  module Builtins
+    extend T::Sig
+
+    # The builtins available in Slice 1. Later slices extend this table.
+    DEFAULTS = {
+      ':' => Colon, 'true' => True, 'false' => False,
+      'echo' => Echo, 'exit' => Exit, 'pwd' => Pwd, 'cd' => Cd,
+      'break' => Break, 'continue' => Continue, 'return' => Return,
+      'test' => Test, '[' => Test, 'set' => Set, 'shift' => Shift,
+      'export' => Export, 'unset' => Unset, 'eval' => Eval, 'getopts' => Getopts, 'read' => Read,
+      'printf' => Printf, '.' => Dot, 'readonly' => Readonly, 'exec' => Exec,
+      'local' => Local, 'type' => Type, 'command' => Command, 'trap' => Trap,
+      'kill' => Kill, 'alias' => Alias, 'unalias' => Unalias,
+      'hash' => Hash, 'times' => Times, 'umask' => Umask, 'ulimit' => Ulimit, 'wait' => Wait,
+      'jobs' => Jobs, 'fg' => Fg, 'bg' => Bg
+    }.freeze
+
+    sig { returns(Registry) }
+    def self.default_registry
+      Registry.new.tap { |registry| DEFAULTS.each { |name, klass| registry.register(name, klass) } }
+    end
+  end
+end

data/lib/rush/builtins/dot.rb

@@ -0,0 +1,52 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `. filename` — read the file and run it in the current shell, so its
+    # functions and variables persist. The file is read command by command
+    # (SourceRunner), so an alias or function it defines shapes its own later
+    # lines. Redirections apply to the file's commands (executor.with_io);
+    # exit/break/continue propagate to the caller, but `return` is bounded to the
+    # dot script — it stops the file and becomes the `.` command's status (POSIX
+    # 2.14), unlike eval. A missing file or a syntax error is a special-builtin
+    # error that aborts a non-interactive shell with status 2 (BuiltinError); a
+    # missing operand is a plain usage error that does not abort. PATH search for
+    # an unqualified name arrives later.
+    class Dot < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        return usage if operands.empty?
+
+        source(operands.first)
+      rescue Errno::ENOENT
+        raise BuiltinError, ".: #{operands.first}: No such file or directory"
+      end
+
+      private
+
+      sig { params(path: T.untyped).returns(Status) }
+      def source(path)
+        text = executor.system.read_file(path)
+        executor.with_io(io) { run_text(text) }
+      rescue ParseError => e
+        raise BuiltinError, ".: #{e}"
+      end
+
+      sig { params(text: String).returns(Status) }
+      def run_text(text)
+        SourceRunner.new(executor, text).run
+      rescue ReturnSignal => e
+        Status.new(e.code)
+      end
+
+      sig { returns(Status) }
+      def usage
+        stderr.puts('rush: .: filename argument required')
+        failure(2)
+      end
+    end
+  end
+end

data/lib/rush/builtins/echo.rb

@@ -0,0 +1,37 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `echo [-n] [arg...]` — joins arguments with spaces and adds a trailing
+    # newline; `-n` suppresses it. XSI escape processing (\n, \t, \c, ...) is
+    # added in Phase 2.
+    class Echo < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        stdout.write(render)
+        success
+      end
+
+      private
+
+      sig { returns(String) }
+      def render
+        body = printed.join(' ')
+        newline? ? "#{body}\n" : body
+      end
+
+      sig { returns(T::Boolean) }
+      def newline?
+        !operands.first.eql?('-n')
+      end
+
+      sig { returns(T::Array[String]) }
+      def printed
+        newline? ? operands : operands.drop(1)
+      end
+    end
+  end
+end

data/lib/rush/builtins/eval.rb

@@ -0,0 +1,25 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `eval [arg ...]` — join the arguments with spaces and run the result in
+    # the current shell, returning its status. The input is read command by
+    # command (SourceRunner), so an `alias` or function defined by one command
+    # shapes how the next is parsed. A redirection on eval applies to the parsed
+    # commands (executor.with_io), and exit/break/continue/return all propagate
+    # to the enclosing context. A syntax error is a special-builtin error: it
+    # aborts a non-interactive shell with status 2 (BuiltinError), after the
+    # complete commands before it have run.
+    class Eval < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        executor.with_io(io) { SourceRunner.new(executor, operands.join(' ')).run }
+      rescue ParseError => e
+        raise BuiltinError, "eval: #{e}"
+      end
+    end
+  end
+end

data/lib/rush/builtins/exec.rb

@@ -0,0 +1,54 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `exec [command [arg ...]]` — with no command, make the redirections
+    # permanent for the rest of the shell; with a command, replace the shell
+    # process with it (applying the redirections first). A failed exec aborts the
+    # shell with 127 (not found) or 126 (not executable), matching dash.
+    class Exec < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        operands.empty? ? redirect_shell : replace_process
+      end
+
+      private
+
+      sig { returns(Status) }
+      def redirect_shell
+        executor.replace_io(io)
+        success
+      end
+
+      sig { returns(T.noreturn) }
+      def replace_process
+        executor.system.exec(command_environment, operands, options)
+      rescue Errno::ENOENT
+        abort_exec('not found', 127)
+      rescue Errno::EACCES
+        abort_exec('Permission denied', 126)
+      end
+
+      sig { params(reason: String, code: Integer).returns(T.noreturn) }
+      def abort_exec(reason, code)
+        report_exec_error(reason)
+        raise ExitSignal, code
+      end
+
+      sig { params(reason: String).void }
+      def report_exec_error(reason)
+        stderr.puts("rush: #{operands.first}: #{reason}")
+      rescue Errno::EBADF
+        nil
+      end
+
+      sig { returns(T::Hash[T.any(Integer, Symbol), T.untyped]) }
+      def options
+        io.to_spawn_options.merge(close_others: true)
+      end
+    end
+  end
+end

data/lib/rush/builtins/exit.rb

@@ -0,0 +1,45 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `exit [n]` — unwind to the top level via ExitSignal, carrying the status n
+    # (the executor's exiting status when no operand is given: the last command's
+    # status normally, or the shell's terminating status inside the EXIT trap).
+    # A non-numeric n is a special-builtin error. With a stopped job in the
+    # table the first exit is refused — "You have stopped jobs.", status 0 —
+    # and an immediately repeated exit goes through (dash's stoppedjobs
+    # guard, probed batch and interactive alike; only the interactive prompt
+    # loop re-arms the warning).
+    class Exit < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        return refuse_stopped if stopped_jobs?
+
+        raise ExitSignal, code
+      end
+
+      private
+
+      # Stopped jobs block the exit once (the Control's dash-job_warning
+      # window arms on the first refusal).
+      sig { returns(T::Boolean) }
+      def stopped_jobs?
+        executor.jobs.ordered.any?(&:stopped?) && executor.jobs.control.warn_exit?
+      end
+
+      sig { returns(Status) }
+      def refuse_stopped
+        stderr.puts('You have stopped jobs.')
+        success
+      end
+
+      sig { returns(Integer) }
+      def code
+        operands.empty? ? executor.trap_runner.exiting_status : numeric_operand(operands.fetch(0))
+      end
+    end
+  end
+end

data/lib/rush/builtins/export.rb

@@ -0,0 +1,20 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `export name[=value] ...` — mark each name for inclusion in the environment
+    # of subsequently executed commands; see Declare for the shared engine.
+    # (The `-p` listing form arrives with the variable-printing slice.)
+    class Export < Declare
+      extend T::Sig
+
+      private
+
+      sig { params(operand: String).void }
+      def declare(operand)
+        executor.state.variables.export_operand(operand)
+      end
+    end
+  end
+end