srsh 0.7.1 → 1.0.0

data/language-docs/MIGRATION.md

@@ -0,0 +1,44 @@
+# Moving an old srsh 0.8 setup to 1.0
+
+The old shell was one large Ruby file. 1.0 is not, but it keeps the bits users actually interacted with: `~/.srshrc`, `~/.srsh_history`, themes, Ruby plugins, the predictive prompt, normal Unix commands, and the original block spellings.
+
+Old RSH still parses:
+
+```rsh
+if $X == 2
+  emit "yes"
+else
+  emit "no"
+end
+
+while $RUNNING
+  work
+end
+
+times 3
+  emit $it
+end
+
+fn twice x
+  return int($x) * 2
+end
+```
+
+New code can use the more capable expression layer and either readable or hot forms:
+
+```rsh
+fn twice(x) => int(x) * 2
+? X == 2 => emit "yes"
+@ 3 -> i => = twice(i)
+```
+
+A few intentional changes:
+
+- `:=` is a local RSH binding; `$NAME :=` writes the process environment.
+- `..` is an inclusive range, `..<` is exclusive.
+- `++` is explicit string concatenation.
+- `|` is a Unix process pipe; `|>` is an RSH value pipeline.
+- missing variables can be made errors with `option nounset yes` or `option strict yes`.
+- normal shell wildcard expansion now works; use quoted wildcards when you want literal `*`/`?` characters.
+
+The brief development-only 1.0.x/1.1/1.2 directories were never release lines. The code they introduced is folded into the unreleased 1.0.0 tree.

data/language-docs/SECURITY.md

@@ -0,0 +1,44 @@
+# Security notes
+
+SRSH is a shell. If you run a command, source a script, load a plugin, call native C, or execute generated code, that code has your user account's privileges. There is no pretend sandbox hiding underneath it.
+
+Things the runtime does try to get right:
+
+- `~/.srsh` state directories are private where the OS permits it.
+- history/state writes use temporary files and atomic replacement.
+- automatically loaded rc/plugin files must be regular files owned by the current user and not group/world writable.
+- symlinked auto-loaded plugins are refused.
+- script, token, nesting, recursion and command-substitution sizes are bounded.
+- `readfile()` and structured process capture have size limits.
+- `cmd(...)` keeps argv data out of shell reparsing.
+- ordinary list/map/string data is copied across RSH task boundaries; deliberate shared mutation uses objects, atoms or channels.
+- worker tasks cannot silently rewrite the process environment or a shared `space`.
+- structured command children are reaped on error paths.
+
+## Dynamic code
+
+`code name ... end` is preferable when you know the code at parse time: the body is parsed before it can run.
+
+`code(string)`, `eval(string)`, `run(string)`, `sh(string)` and `capture(string)` are intentionally dynamic. Do not build those strings from hostile input and then call them. Use values and `cmd(...)` when data is not trusted.
+
+Ruby plugins are trusted code. That is a feature of a Ruby shell, not a security boundary.
+
+## Native C bridges
+
+`bridge` uses the platform C ABI directly. Signature checking only checks the RSH declaration; SRSH cannot prove that the C function on the other side actually has that signature.
+
+A bad pointer, wrong return type, incorrect calling convention, use-after-free in a library, or just a buggy C function can segfault the entire shell. This is normal FFI territory.
+
+Prefer `cstr` for input strings and `cbuf()` for bounded writable memory. Keep raw `ptr` use small and boring. `@self` exposes symbols from the current process and loaded runtime libraries, so only bind symbols you understand.
+
+## Concurrency
+
+Task cancellation stops the Ruby thread as best it can; it does not undo file writes or network activity that already happened.
+
+`parallel()` uses Ruby threads. On CRuby, the GVL still limits CPU-bound Ruby bytecode. `pmap()` uses `fork` on Unix and therefore has process-copy semantics instead.
+
+Objects expose synchronized slot updates, but synchronization does not magically make a multi-step algorithm race-free. Use atoms/channels when the ownership story is clearer that way.
+
+## Audit status
+
+SRSH has automated parser, shell, TTY and concurrency tests, but it has not had an independent security audit. Treat that sentence more seriously than a big “production ready” badge.

data/lib/srsh/app.rb

@@ -0,0 +1,261 @@
+require 'socket'
+require_relative 'version'
+require_relative 'paths'
+require_relative 'state'
+require_relative 'theme'
+require_relative 'history'
+require_relative 'security'
+require_relative 'plugins'
+require_relative 'builtins'
+require_relative 'editor'
+require_relative 'language/parser'
+require_relative 'shell/executor'
+require_relative 'shell/lexer'
+
+module Srsh
+  class App
+    attr_reader :paths, :state, :theme, :history, :plugins, :builtins, :executor
+    attr_accessor :out, :err
+
+    def initialize(out: STDOUT, err: STDERR, home: Dir.home)
+      @out = out
+      @err = err
+      @paths = Paths.new(home).ensure!
+      @state = State.new
+      @theme = Theme.new(paths, state)
+      @history = History.new(paths.history, import_paths: [paths.history_v1])
+      @builtins = Builtins.new(self)
+      @executor = Shell::Executor.new(self)
+      @plugins = Plugins.new(self)
+      @editor = Editor.new(self)
+      @loaded_startup = false
+      @skip_startup = false
+      install_signals
+    end
+
+    def disable_startup!
+      @skip_startup = true
+      self
+    end
+
+    def startup!
+      return if @loaded_startup
+      if @skip_startup
+        @loaded_startup = true
+        return
+      end
+      create_default_rc
+      load_rc
+      plugins.load_all
+      @loaded_startup = true
+    end
+
+    def reload!
+      @state.functions.clear
+      @state.prototypes.clear
+      @state.traits.clear
+      @state.aliases.clear
+      @state.clear_hooks!
+      @builtins.reset_dynamic!
+      @theme.reset_dynamic!
+      load_rc
+      plugins.load_all
+    end
+
+    def run_script(path, argv = [])
+      real = File.expand_path(path)
+      raise Error, "script not found: #{path}" unless File.file?(real)
+      raise Error, 'script too large' if File.size(real) > 4 * 1024 * 1024
+      text = read_script_limited(real)
+      nodes = Language::ProgramParser.new(text).parse
+      scope = { '$0' => real }
+      argv.each_with_index { |value, i| scope["$#{i + 1}"] = value }
+      @state.push_scope(scope)
+      executor.run_program(nodes)
+    ensure
+      @state.pop_scope if defined?(scope) && scope
+    end
+
+    def check_script(path)
+      real = File.expand_path(path)
+      raise Error, "script not found: #{path}" unless File.file?(real)
+      Language::ProgramParser.new(read_script_limited(real)).parse
+      out.puts "#{path}: syntax ok"
+      0
+    rescue StandardError => e
+      err.puts "#{path}: #{e.message}"
+      2
+    end
+
+    def run_command(command)
+      startup!
+      executor.execute_line(command)
+    end
+
+    def run_expression(source)
+      startup!
+      raise ParseError, 'expression cannot contain a newline' if source.to_s.include?("\n")
+      nodes = Language::ProgramParser.new("= #{source}\n").parse
+      executor.run_program(nodes)
+    end
+
+    def run_input(input)
+      text = input.to_s
+      if rsh_candidate?(text)
+        executor.run_program(Language::ProgramParser.new(text.end_with?("\n") ? text : text + "\n").parse)
+      else
+        executor.execute_line(text)
+      end
+    end
+
+    def interactive
+      startup!
+      welcome
+      hostname = Socket.gethostname.split('.').first
+      loop do
+        state.prune_jobs!
+        title
+        input = @editor.read(prompt(hostname))
+        break if input == :eof
+        next if input == :interrupt
+        next if input.nil? || input.strip.empty?
+        record_history(input)
+        begin
+          input = collect_incomplete_input(input)
+          break if input == :eof
+          next if input == :interrupt
+          run_input(input)
+        rescue BreakSignal, NextSignal, ReturnSignal
+          err.puts theme.paint('control-flow marker used outside a script/function', :error, io: err)
+          state.last_status = 2
+        rescue StandardError => e
+          err.puts theme.paint("srsh: #{e.class}: #{e.message}", :error, io: err)
+          state.last_status = 1
+        end
+      end
+      0
+    ensure
+      history.flush
+    end
+
+    def prompt(hostname)
+      "#{theme.paint(short_pwd, :path, io: out)} #{theme.paint(hostname, :host, io: out)}#{theme.paint(' > ', :mark, io: out)}"
+    end
+
+    private
+
+    def rsh_candidate?(text)
+      line = text.to_s.lstrip
+      return true if line.match?(/\A(?:=\s+|emit\s+|return(?:\s|$)|break$|continue$|\^|\?|@|::)/)
+      return true if line.match?(/\A(?:try|if|each|while|fn|task|match|code|use|defer|bridge|space|proto|trait|slot)\b/)
+      return true if line.include?('|>')
+      return true if line.match?(/\A(?:\*?[A-Za-z_][A-Za-z0-9_]*(?:\s*,\s*\*?[A-Za-z_][A-Za-z0-9_]*)+|\$?[A-Za-z_][A-Za-z0-9_]*|[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)+)\s*(?::=|\+=|-=|\*=|\/=|%=|\+\+=)/)
+      return true if line.match?(/\A[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*\s*\(/)
+      false
+    end
+
+    def collect_incomplete_input(first)
+      text = first.to_s
+      loop do
+        return text unless incomplete_input?(text)
+        more = @editor.read(theme.paint('... ', :dim, io: out))
+        return more if more == :eof || more == :interrupt
+        more = more.to_s
+        record_history(more)
+        text << "\n" << more
+      end
+    end
+
+    # History is line-oriented on disk and ghost completion is line-oriented in
+    # the editor.  A bracketed multi-line paste therefore records its physical
+    # lines just like manually entering a continued block instead of stuffing a
+    # newline-bearing pseudo-entry into history.
+    def record_history(text)
+      text.to_s.each_line do |line|
+        line = line.chomp
+        history.add(line) unless line.strip.empty?
+      end
+    end
+
+    def incomplete_input?(text)
+      if rsh_candidate?(text)
+        begin
+          Language::ProgramParser.new(text.end_with?("\n") ? text : text + "\n").parse
+          false
+        rescue IncompleteInput
+          true
+        rescue ParseError
+          false
+        end
+      else
+        begin
+          tokens = Shell::Lexer.scan(text)
+          last = tokens.last
+          last && last.type == :op && %w[| && || < > >> 2> 2>>].include?(last.text)
+        rescue IncompleteInput
+          true
+        rescue ParseError
+          false
+        end
+      end
+    end
+
+    def short_pwd
+      home = paths.home
+      pwd = Dir.pwd
+      pwd.start_with?(home) ? pwd.sub(home, '~') : pwd
+    end
+
+    def title
+      return unless out.respond_to?(:tty?) && out.tty?
+      out.print "\e]0;srsh #{VERSION}: #{Dir.pwd}\a"
+    end
+
+    def welcome
+      out.puts theme.paint("Simple Ruby Shell #{VERSION}", :title, io: out)
+      out.puts theme.paint("Ruby #{RUBY_VERSION} · #{RUBY_PLATFORM}", :dim, io: out)
+      out.puts "type #{theme.paint('help', :key, io: out)} for commands; RSH hot forms work here too\n\n"
+    end
+
+    def load_rc
+      return unless File.file?(paths.rc)
+      unless Security.private_regular_file?(paths.rc)
+        err.puts theme.paint("srsh: refusing unsafe rc file #{paths.rc}", :warn, io: err)
+        return
+      end
+      run_script(paths.rc, [])
+    rescue StandardError => e
+      err.puts theme.paint("srshrc: #{e.class}: #{e.message}", :error, io: err)
+    end
+
+    def create_default_rc
+      return if File.exist?(paths.rc)
+      Security.atomic_write(paths.rc, <<~RSH)
+        # ~/.srshrc: Simple Ruby Shell startup script
+        #
+        # alias ll=ls -lah
+        # $EDITOR := "nano"
+        # scheme ocean
+      RSH
+    rescue SystemCallError
+    end
+
+    def read_script_limited(path)
+      limit = 4 * 1024 * 1024
+      File.open(path, 'rb') do |io|
+        data = io.read(limit + 1) || ''.b
+        raise Error, 'script too large' if data.bytesize > limit
+        data.force_encoding(Encoding::UTF_8)
+        raise Error, 'script is not valid UTF-8' unless data.valid_encoding?
+        data
+      end
+    end
+
+    def install_signals
+      Signal.trap('INT', 'IGNORE')
+      Signal.trap('TTOU', 'IGNORE') if Signal.list.key?('TTOU')
+      Signal.trap('TTIN', 'IGNORE') if Signal.list.key?('TTIN')
+      Signal.trap('TSTP', 'IGNORE') if Signal.list.key?('TSTP')
+    end
+  end
+end