terminalwire 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1240b61fdcc7553eb7d55495ca20b4401c9516641a024a7a59f64ac3fda9144
-  data.tar.gz: 6511112c08684aa011b2026537b8f62c3e7900233f2ea98c4df2f47ccdf2b621
+  metadata.gz: 9fec6bb413813bdaa761403bca8fcaebb92b884a448cfe3b5cba7fc56e3589b0
+  data.tar.gz: 319498815fe666a7266f1dcfd2648af1e15477f7f42f22cd8661f2c42bda45c9
 SHA512:
-  metadata.gz: 9f5761849e14d51d6491ea7c024769724607081db57968d05abcc25c713dd4afb7808ab4d29873b50c4b2611bcc5e246be3dc7c0bb436fd9ef8c8c4e98e35e10
-  data.tar.gz: f23b101082f1cd1395742ffafffb5c87b5a31d0255153ec5b8c7139cde00a4419575056593a25da6276e33a27b190da2e45b6f3512fa38c7489c4ce98a91a0f3
+  metadata.gz: bbc8104d13cd4acf420c0c5873b4f1df0749ea94768c91a9ceb6100d34c9fe6da0cd62bf4bb717a5c5e5fdc4f3d7395db0a0cd44b5d88cb1e18006dab6c3f791
+  data.tar.gz: daeeb21577a26536a4daad6c61b07f1b6a96a23ea52adfbc4eb25881b2948a1010f81ffc6b4958eb92befc0bae348b18cbecf4aeecea813c0b84b18ea0e33ace

data/LICENSE.txt

@@ -1 +1 @@
-Copyright (c) 2024 Brad Gessler. Email brad@terminalwire.com to discuss commercial licensing.
+Copyright (c) 2024 Brad Gessler. Email brad@terminalwire.com to discuss licensing.

data/README.md

@@ -1,8 +1,6 @@
 # Terminalwire
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/terminalwire`. To experiment with that code, run `bin/console` for an interactive prompt.
+Unlike most command-line tools for web services that require an API, Terminalwire streams terminal I/O between a web server and client over WebSockets. This means you can use your preferred command-line parser within your favorite web server framework to deliver a delightful CLI experience to your users.
 
 ## Installation
 
@@ -14,9 +12,19 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install terminalwire
 
-## Usage
+## Rails
+
+Run the intallation command:
+
+    $ rails g terminalwire:install my-app
+
+This generates the `./bin/my-app` file. Run it to verify that it connects to the server.
+
+    $ bin/my-app
+    Commands:
+      my-app help [COMMAND]  # Describe available commands or one specific command
 
-TODO: Write usage instructions here
+To edit the command-line, open `./app/cli/main_cli.rb` and make changes to the `MainCLI` class.
 
 ## Development
 
@@ -30,7 +38,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/termin
 
 ## License
 
-The gem is available as a propietary license. Email brad@terminalwire.com to discuss commercial licensing.
+The gem is available as a propietary license. Email brad@terminalwire.com to discuss licensing.
 
 ## Code of Conduct
 

data/examples/exec/localrails

@@ -0,0 +1,2 @@
+#!/usr/bin/env terminalwire-exec
+url: "ws://localhost:3000/terminal"

data/exe/terminalwire-exec

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+require_relative "../lib/terminalwire.rb"
+
+begin
+  Terminalwire::Client::Binary.execute
+rescue Terminalwire::Error => e
+  puts e.message
+  exit 1
+end

data/lib/generators/terminalwire/install/USAGE

@@ -0,0 +1,9 @@
+Description:
+    Installs Terminalwire
+
+Example:
+    bin/rails generate terminalwire:install
+
+    This will create:
+        app/terminal/application_terminal.rb
+        bin/<your-app>

data/lib/generators/terminalwire/install/install_generator.rb

@@ -0,0 +1,37 @@
+require "bundler"
+
+class Terminalwire::InstallGenerator < Rails::Generators::Base
+  source_root File.expand_path("templates", __dir__)
+
+  argument :binary_name, type: :string, required: true, banner: "binary_name"
+
+  def create_terminal_files
+    template "application_terminal.rb.tt", Rails.root.join("app/terminal/application_terminal.rb")
+  end
+
+  def create_binary_files
+    copy_file "bin/terminalwire", binary_path
+    chmod binary_path, 0755, verbose: false
+  end
+
+  def add_route
+    route <<~ROUTE
+      match "/terminal",
+        to: Terminalwire::WebSocket::ThorServer.new(ApplicationTerminal),
+        via: [:get, :connect]
+    ROUTE
+  end
+
+  def print_post_install_message
+    say ""
+    say "Terminalwire has been successfully installed!", :green
+    say "Run `#{binary_path.relative_path_from(Rails.root)}` to verify everything is in working order. For support visit https://terminalwire.com."
+    say ""
+  end
+
+  private
+
+  def binary_path
+    Rails.root.join("bin", binary_name)
+  end
+end

data/lib/generators/terminalwire/install/templates/application_terminal.rb.tt

@@ -0,0 +1,36 @@
+# Learn how to use Thor at http://whatisthor.com.
+class ApplicationTerminal < Thor
+  include Terminalwire::Thor
+
+  def self.basename = "<%= binary_name %>"
+
+  desc "hello NAME", "say hello to NAME"
+  def hello(name)
+    puts "Hello #{name}"
+  end
+
+  desc "login", "Login to your account"
+  def login
+    print "Email: "
+    email = gets
+
+    print "Password: "
+    password = getch
+
+    if self.current_user = User.authenticate(email, password)
+      puts "Successfully logged in as #{user.email}."
+    else
+      puts "Could not find a user with that email and password."
+    end
+  end
+
+  private
+
+  def current_user=(user)
+    session["user_id"] = user.id
+  end
+
+  def current_user
+    @current_user ||= User.find(session.fetch("user_id"))
+  end
+end

data/lib/generators/terminalwire/install/templates/bin/terminalwire

@@ -0,0 +1,2 @@
+#!/usr/bin/env terminalwire-exec
+url: "ws://localhost:3000/terminal"

data/lib/terminalwire/client/binary.rb

@@ -0,0 +1,35 @@
+require "pathname"
+require "yaml"
+require "uri"
+
+module Terminalwire::Client
+  class Binary
+    attr_reader :arguments, :path, :configuration, :url
+
+    def initialize(path:, arguments:)
+      @arguments = arguments
+      @path = Pathname.new(path)
+      @configuration = YAML.load_file(@path)
+      @url = URI(@configuration.fetch("url"))
+    rescue Errno::ENOENT => e
+      raise Terminalwire::Error, "File not found: #{@path}"
+    rescue URI::InvalidURIError => e
+      raise Terminalwire::Error, "Invalid URI: #{@url}"
+    rescue KeyError => e
+      raise Terminalwire::Error, "Missing key in configuration: #{e}"
+    end
+
+    def start
+      Terminalwire::Client.websocket(url:, arguments:)
+    end
+
+    def self.execute
+      case ARGV
+      in path, *arguments
+        new(path:, arguments:).start
+      end
+    rescue NoMatchingPatternError => e
+      raise Terminalwire::Error, "Launched with incorrect arguments: #{ARGV}"
+    end
+  end
+end

data/lib/terminalwire/client.rb

@@ -0,0 +1,213 @@
+module Terminalwire
+  module Client
+    module Resource
+      class IO < Terminalwire::Resource::Base
+        def dispatch(action, data)
+          if @device.respond_to?(action)
+            respond @device.public_send(action, data)
+          else
+            raise "Unknown action #{action} for device ID #{@id}"
+          end
+        end
+      end
+
+      class STDOUT < IO
+        def connect
+          @device = $stdout
+        end
+      end
+
+      class STDIN < IO
+        def connect
+          @device = $stdin
+        end
+
+        def dispatch(action, data)
+          respond case action
+          when "puts"
+            @device.puts(data)
+          when "gets"
+            @device.gets
+          when "getpass"
+            @device.getpass
+          end
+        end
+      end
+
+      class STDERR < IO
+        def connect
+          @device = $stderr
+        end
+      end
+
+      class File < Terminalwire::Resource::Base
+        def connect
+          @files = {}
+        end
+
+        def dispatch(action, data)
+          respond case action
+          when "read"
+            read_file(data)
+          when "write"
+            write_file(data.fetch(:path), data.fetch(:content))
+          when "append"
+            append_to_file(data.fetch(:path), data.fetch(:content))
+          when "mkdir"
+            mkdir(data.fetch(:path))
+          when "exist"
+            exist?(data.fetch(:path))
+          else
+            raise "Unknown action #{action} for file device"
+          end
+        end
+
+        def mkdir(path)
+          FileUtils.mkdir_p(::File.expand_path(path))
+        end
+
+        def exist?(path)
+          ::File.exist? ::File.expand_path(path)
+        end
+
+        def read_file(path)
+          ::File.read ::File.expand_path(path)
+        end
+
+        def write_file(path, content)
+          ::File.open(::File.expand_path(path), "w") { |f| f.write(content) }
+        end
+
+        def append_to_file(path, content)
+          ::File.open(::File.expand_path(path), "a") { |f| f.write(content) }
+        end
+
+        def disconnect
+          @files.clear
+        end
+      end
+
+      class Browser < Terminalwire::Resource::Base
+        def dispatch(action, data)
+          respond case action
+          when "launch"
+            Launchy.open(data)
+            "Launched browser with URL: #{data}"
+          else
+            raise "Unknown action #{action} for browser device"
+          end
+        end
+      end
+    end
+
+    class ResourceMapper
+      def initialize(connection, resources)
+        @connection = connection
+        @resources = resources
+        @devices = Hash.new { |h,k| h[Integer(k)] }
+      end
+
+      def connect_device(id, type)
+        klass = @resources.find(type)
+        if klass
+          device = klass.new(id, @connection)
+          device.connect
+          @devices[id] = device
+          @connection.write(event: "device", action: "connect", status: "success", id: id, type: type)
+        else
+          @connection.write(event: "device", action: "connect", status: "failure", id: id, type: type, message: "Unknown device type")
+        end
+      end
+
+      def dispatch(id, action, data)
+        device = @devices[id]
+        if device
+          device.dispatch(action, data)
+        else
+          raise "Unknown device ID: #{id}"
+        end
+      end
+
+      def disconnect_device(id)
+        device = @devices.delete(id)
+        device&.disconnect
+        @connection.write(event: "device", action: "disconnect", id: id)
+      end
+    end
+
+    class Handler
+      VERSION = "0.1.0".freeze
+
+      include Logging
+
+      attr_reader :arguments, :program_name
+
+      def initialize(connection, resources = self.class.resources, arguments: ARGV, program_name: $0)
+        @connection = connection
+        @resources = resources
+        @arguments = arguments
+      end
+
+      def connect
+        @devices = ResourceMapper.new(@connection, @resources)
+
+        @connection.write(event: "initialize", protocol: { version: VERSION }, arguments:, program_name:)
+
+        loop do
+          handle @connection.recv
+        end
+      end
+
+      def handle(message)
+        case message
+        in { event: "device", action: "connect", id:, type: }
+          @devices.connect_device(id, type)
+        in { event: "device", action: "command", id:, command:, data: }
+          @devices.dispatch(id, command, data)
+        in { event: "device", action: "disconnect", id: }
+          @devices.disconnect_device(id)
+        in { event: "exit", status: }
+          exit Integer(status)
+        end
+      end
+
+      def self.resources
+        ResourceRegistry.new.tap do |resources|
+          resources << Client::Resource::STDOUT
+          resources << Client::Resource::STDIN
+          resources << Client::Resource::STDERR
+          resources << Client::Resource::Browser
+          resources << Client::Resource::File
+        end
+      end
+    end
+
+    def self.tcp(...)
+      socket = TCPSocket.new(...)
+      transport = Terminalwire::Transport::Socket.new(socket)
+      connection = Terminalwire::Connection.new(transport)
+      Terminalwire::Client::Handler.new(connection)
+    end
+
+    def self.socket(...)
+      socket = UNIXSocket.new(...)
+      transport = Terminalwire::Transport::Socket.new(socket)
+      connection = Terminalwire::Connection.new(transport)
+      Terminalwire::Client::Handler.new(connection)
+    end
+
+    def self.websocket(url:, arguments: ARGV)
+      url = URI(url)
+
+      Async do |task|
+        endpoint = Async::HTTP::Endpoint.parse(url)
+
+        Async::WebSocket::Client.connect(endpoint) do |connection|
+          transport = Terminalwire::Transport::WebSocket.new(connection)
+          connection = Terminalwire::Connection.new(transport)
+          Terminalwire::Client::Handler.new(connection, arguments:).connect
+        end
+      end
+    end
+  end
+end

data/lib/terminalwire/server.rb

@@ -0,0 +1,239 @@
+module Terminalwire
+  module Server
+    module Resource
+      class IO < Terminalwire::Resource::Base
+        def puts(data)
+          command("puts", data: data)
+        end
+
+        def print(data)
+          command("print", data: data)
+        end
+
+        def gets
+          command("gets")
+        end
+
+        def flush
+          # @connection.flush
+        end
+
+        private
+
+        def command(command, data: nil)
+          @connection.write(event: "device", id: @id, action: "command", command: command, data: data)
+          @connection.recv&.fetch(:response)
+        end
+      end
+
+      class STDOUT < IO
+      end
+
+      class STDIN < IO
+        def getpass
+          command("getpass")
+        end
+      end
+
+      class STDERR < IO
+      end
+
+      class File < Terminalwire::Resource::Base
+        def read(path)
+          command("read", path.to_s)
+        end
+
+        def write(path, content)
+          command("write", { 'path' => path.to_s, 'content' => content })
+        end
+
+        def append(path, content)
+          command("append", { 'path' => path.to_s, 'content' => content })
+        end
+
+        def mkdir(path)
+          command("mkdir", { 'path' => path.to_s })
+        end
+
+        def exist?(path)
+          command("exist", { 'path' => path.to_s })
+        end
+
+        private
+
+        def command(action, data)
+          @connection.write(event: "device", id: @id, action: "command", command: action, data: data)
+          response = @connection.recv
+          response.fetch(:response)
+        end
+      end
+
+      class Browser < Terminalwire::Resource::Base
+        def launch(url)
+          command("launch", data: url)
+        end
+
+        private
+
+        def command(command, data: nil)
+          @connection.write(event: "device", id: @id, action: "command", command: command, data: data)
+          @connection.recv.fetch(:response)
+        end
+      end
+    end
+
+    class ResourceMapper
+      include Logging
+
+      def initialize(connection, resources = self.class.resources)
+        @id = -1
+        @resources = resources
+        @devices = Hash.new { |h,k| h[Integer(k)] }
+        @connection = connection
+      end
+
+      def connect_device(type)
+        id = next_id
+        logger.debug "Server: Requesting client to connect device #{type} with ID #{id}"
+        @connection.write(event: "device", action: "connect", id: id, type: type)
+        response = @connection.recv
+        case response
+        in { status: "success" }
+          logger.debug "Server: Resource #{type} connected with ID #{id}."
+          @devices[id] = @resources.find(type).new(id, @connection)
+        else
+          logger.debug "Server: Failed to connect device #{type} with ID #{id}."
+        end
+      end
+
+      private
+
+      def next_id
+        @id += 1
+      end
+
+      def self.resources
+        ResourceRegistry.new.tap do |resources|
+          resources << Server::Resource::STDOUT
+          resources << Server::Resource::STDIN
+          resources << Server::Resource::STDERR
+          resources << Server::Resource::Browser
+          resources << Server::Resource::File
+        end
+      end
+    end
+
+    class Session
+      extend Forwardable
+
+      attr_reader :stdout, :stdin, :stderr, :browser, :file
+
+      def_delegators :@stdout, :puts, :print
+      def_delegators :@stdin, :gets, :getpass
+
+      def initialize(connection:)
+        @connection = connection
+        @devices = ResourceMapper.new(@connection)
+        @stdout = @devices.connect_device("stdout")
+        @stdin = @devices.connect_device("stdin")
+        @stderr = @devices.connect_device("stderr")
+        @browser = @devices.connect_device("browser")
+        @file = @devices.connect_device("file")
+
+        if block_given?
+          begin
+            yield self
+          ensure
+            exit
+          end
+        end
+      end
+
+      def exec(&shell)
+        instance_eval(&shell)
+      ensure
+        exit
+      end
+
+      def exit(status = 0)
+        @connection.write(event: "exit", status: status)
+      end
+
+      def close
+        @connection.close
+      end
+    end
+
+    class MyCLI < ::Thor
+      include Terminalwire::Thor
+
+      desc "greet NAME", "Greet a person"
+      def greet(name)
+        name = ask "What's your name?"
+        say "Hello, #{name}!"
+      end
+    end
+
+    class Socket
+      include Logging
+
+      def initialize(server_socket)
+        @server_socket = server_socket
+      end
+
+      def listen
+        logger.info "Socket: Sistening..."
+        loop do
+          client_socket = @server_socket.accept
+          logger.debug "Socket: Client #{client_socket.inspect} connected"
+          handle_client(client_socket)
+        end
+      end
+
+      private
+
+      def handle_client(socket)
+        transport = Transport::Socket.new(socket)
+        connection = Connection.new(transport)
+
+        Thread.new do
+          handler = Handler.new(connection)
+          handler.run
+        end
+      end
+    end
+
+    class Handler
+      include Logging
+
+      def initialize(connection)
+        @connection = connection
+      end
+
+      def run
+        logger.info "Server Handler: Running"
+        loop do
+          message = @connection.recv
+          case message
+          in { event: "initialize", arguments:, program_name: }
+            Session.new(connection: @connection) do |session|
+              MyCLI.start(arguments, session: session)
+            end
+          end
+        end
+      rescue EOFError, Errno::ECONNRESET
+        logger.info "Server Handler: Client disconnected"
+      ensure
+        @connection.close
+      end
+    end
+
+    def self.tcp(...)
+      Server::Socket.new(TCPServer.new(...))
+    end
+
+    def self.socket(...)
+      Server::Socket.new(UNIXServer.new(...))
+    end
+  end
+end

data/lib/terminalwire/thor.rb

@@ -0,0 +1,43 @@
+module Terminalwire
+  module Thor
+    class Shell < ::Thor::Shell::Basic
+      extend Forwardable
+
+      # Encapsulates all of the IO devices for a Terminalwire connection.
+      attr_reader :session
+
+      def_delegators :@session, :stdin, :stdout, :stderr
+
+      def initialize(session)
+        @session = session
+        super()
+      end
+    end
+
+    def self.included(base)
+      base.extend ClassMethods
+
+      # I have to do this in a block to deal with some of Thor's DSL
+      base.class_eval do
+        extend Forwardable
+
+        protected
+
+        no_commands do
+          def_delegators :shell, :session
+          def_delegators :session, :stdout, :stdin, :stderr, :browser
+          def_delegators :stdout, :puts, :print
+          def_delegators :stdin, :gets
+        end
+      end
+    end
+
+    module ClassMethods
+      def start(given_args = ARGV, config = {})
+        session = config.delete(:session)
+        config[:shell] = Shell.new(session) if session
+        super(given_args, config)
+      end
+    end
+  end
+end