terminalwire 0.3.5.alpha2 → 2.0.0

data/lib/terminalwire/v2/server/context.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Terminalwire::V2
+  module Server
+    # The server's handle on the client's machine. CLI code calls these methods
+    # (puts, gets, file.read, ...) and the Context turns them into protocol frames
+    # via the Runtime. Output is one-way; input and filesystem ops are synchronous
+    # request/response.
+    class Context
+      def initialize(runtime)
+        @runtime = runtime
+        @stdout_sid = nil
+        @stderr_sid = nil
+        @request = {}
+      end
+
+      # The incoming HTTP connection profile, captured at the WebSocket upgrade
+      # (the Rack adapter sets it): { host:, ip:, user_agent:, headers: }. The
+      # client identifies itself in headers — chiefly a real User-Agent — so server
+      # code can see who connected (and a `terminalwire about` can light it up).
+      attr_accessor :request
+
+      # The client's real IP (through Fly/proxies), its User-Agent, and the raw
+      # incoming HTTP headers. nil/empty when unknown (e.g. non-HTTP transports).
+      def remote_ip   = @request[:ip]
+      def user_agent  = @request[:user_agent]
+      def http_headers = @request[:headers] || {}
+
+      # The client build version, parsed from the User-Agent
+      # ("terminalwire-exec/<version> (…)"). The version is a client-reported fact
+      # in a header, never derived from the URL. nil if the client sent no UA.
+      def client_version
+        user_agent && user_agent[%r{terminalwire-exec/(\S+)}, 1]
+      end
+
+      # The client's live terminal (rows/cols/tty?/color?), kept current by the
+      # runtime's read pump as resize frames arrive.
+      def terminal = @runtime.terminal
+
+      # The program name + arguments the client launched with (from the hello).
+      # CLI parsers (OptionParser, Thor, GLI, …) consume `program_arguments`.
+      def program_name = @runtime.program && @runtime.program["name"]
+      def program_arguments = Array(@runtime.program && @runtime.program["args"])
+
+      # The entitlement the client granted this session: its authority (origin),
+      # the path globs it will allow writes within, and the permitted schemes/env
+      # vars. The CLIENT enforces this; here it's a read-only view so server code
+      # can stay inside the sandbox (e.g. learn where it may persist a file).
+      def entitlement = @runtime.entitlement
+
+      # The capability set negotiated for this session — the intersection the
+      # client and server agreed on in the handshake. Branch on this to offer
+      # optional features only when the connected client supports them.
+      def capabilities = @runtime.connection.capabilities
+
+      # The client directory this origin may persist files into — its sandbox —
+      # derived from the first granted path glob (".../**" -> "..."). Returns nil
+      # if no writable path was granted. Used like:
+      #
+      #   context.file.write("#{context.storage_path}/session.json", data)
+      def storage_path
+        glob = entitlement && entitlement.dig("paths", 0, "glob")
+        glob && glob.sub(%r{/\*\*\z}, "")
+      end
+
+      # The server-manageable root on the client — the USER subtree
+      # (~/.terminalwire/usr), so binary_path = root_path/bin = ~/.terminalwire/usr/bin
+      # (installed app launchers). It deliberately does NOT point at ~/.terminalwire:
+      # the system bin (the terminalwire-exec engine) and the control dir (authorities)
+      # live above this and are off-limits — a server can't reach them even with a
+      # grant. A SYMBOLIC tilde path the client expands + enforces; only the privileged
+      # terminalwire.com origin is granted ~/.terminalwire/usr/bin/** (installer-seeded).
+      def root_path = Pathname.new("~/.terminalwire/usr")
+
+      # Register a callback fired when the client's window resizes.
+      def on_resize(&block) = @runtime.on_resize(&block)
+
+      # Output is flow-controlled and chunked by the runtime: write_data sizes each
+      # data frame to the client's available credit and blocks when the window is
+      # exhausted, so a fast server can't outrun a slow client.
+      def print(data, stream: :stdout)
+        sid = stream == :stderr ? (@stderr_sid ||= open(:stderr)) : (@stdout_sid ||= open(:stdout))
+        @runtime.write_data(sid, data.to_s)
+      end
+
+      def puts(data = "", stream: :stdout)
+        print("#{data}\n", stream: stream)
+      end
+
+      def warn(data = "")
+        puts(data, stream: :stderr)
+      end
+
+      def stdin
+        @stdin ||= Stdin.new(@runtime)
+      end
+
+      # Convenience delegators (Thor's shell uses these).
+      def gets = stdin.gets
+      def getpass = stdin.getpass
+
+      def env(name)
+        @runtime.request(:env, :read, { "name" => name.to_s })
+      end
+
+      # Read keystrokes for the duration of the block: the client puts its terminal
+      # in `mode` and streams keypresses, restoring it when the block exits (even
+      # on error). Foundation for REPLs and interactive TUIs.
+      #
+      #   mode: :raw    — char-at-a-time, no echo, signals as bytes (TUIs)
+      #   mode: :cbreak — char-at-a-time, echo + signal keys on (single-key y/n)
+      #
+      #   context.raw_input { |keys| keys.each { |bytes| handle(bytes) } }
+      def raw_input(mode: Protocol::Mode::RAW)
+        sid = @runtime.open_raw_input(mode: mode.to_s)
+        yield RawInput.new(@runtime, sid)
+      ensure
+        @runtime.close_raw_input(sid) if sid
+      end
+
+      # Single-keypress read with echo + signal keys left on (cbreak): the y/n
+      # prompt case. Returns the first byte(s) the user types.
+      def read_key
+        raw_input(mode: Protocol::Mode::CBREAK) { |keys| return keys.read }
+      end
+
+      # Query the client's terminal with a control sequence and return its reply
+      # (e.g. cursor-position report "\e[6n" -> "\e[row;colR"). The client writes
+      # the query to its tty and reads the terminal's response. Used by advanced
+      # TUI libraries that probe the terminal. Support is advertised via the
+      # terminal-query capability (see #capabilities); a client without a tty
+      # answers with an io error. (Enforcement isn't wired yet — this issues the
+      # request regardless — so check #capabilities yourself if that matters.)
+      def query_terminal(sequence, timeout: 1.0)
+        @runtime.request(:terminal, :query, { "sequence" => sequence.b, "timeout" => timeout })
+      end
+
+      def file
+        @file ||= File.new(@runtime)
+      end
+
+      def directory
+        @directory ||= Directory.new(@runtime)
+      end
+
+      def browser
+        @browser ||= Browser.new(@runtime)
+      end
+
+      def exit(status = 0)
+        @runtime.emit(Frames.exit(status: status))
+      end
+
+      private
+
+      def open(stream)
+        @runtime.open_output(stream)
+      end
+
+      # Reads keystroke chunks from a raw input stream. #read returns the next
+      # chunk (or nil when the stream closes); #each yields until close.
+      class RawInput
+        def initialize(runtime, sid)
+          @runtime = runtime
+          @sid = sid
+        end
+
+        def read = @runtime.read_raw(@sid)
+
+        def each
+          return enum_for(:each) unless block_given?
+
+          while (bytes = read)
+            yield bytes
+          end
+        end
+      end
+
+      # Resource facades — thin request wrappers with a Ruby-ish interface.
+
+      class Stdin
+        DEFAULT_CHUNK = 64 * 1024
+
+        def initialize(runtime) = @runtime = runtime
+
+        def gets = @runtime.request(:stdin, :gets)
+        def getpass = @runtime.request(:stdin, :getpass)
+
+        # Is the client's stdin a terminal (vs a pipe/file)? Branch on this to
+        # decide between prompting and draining piped data.
+        def tty? = @runtime.terminal.stdin.tty?
+
+        # Pull up to `n` bytes from the client's stdin. Returns [data, eof].
+        def read_chunk(n = DEFAULT_CHUNK)
+          response = @runtime.request(:stdin, :read_chunk, { "n" => n })
+          [response["data"] || "".b, response["eof"]]
+        end
+
+        # Drain the client's stdin to EOF (for piped input).
+        def read
+          buffer = +"".b
+          loop do
+            data, eof = read_chunk
+            buffer << data.b # force binary: chunks may arrive as UTF-8 (msgpack
+            break if eof     # str) or binary (bin); mixing them would raise.
+          end
+          buffer
+        end
+
+        # Yield each chunk as it arrives until EOF (streaming without buffering).
+        def each_chunk(n = DEFAULT_CHUNK)
+          return enum_for(:each_chunk, n) unless block_given?
+
+          loop do
+            data, eof = read_chunk(n)
+            yield data unless data.empty?
+            break if eof
+          end
+        end
+      end
+
+      class File
+        def initialize(runtime) = @runtime = runtime
+        def read(path)            = @runtime.request(:file, :read, { "path" => path.to_s })
+        def write(path, content)  = @runtime.request(:file, :write, { "path" => path.to_s, "content" => content })
+        def append(path, content) = @runtime.request(:file, :append, { "path" => path.to_s, "content" => content })
+        def delete(path)          = @runtime.request(:file, :delete, { "path" => path.to_s })
+        def exist?(path)          = @runtime.request(:file, :exist, { "path" => path.to_s })
+        # chmod the file to `mode` (an integer like 0o755). The client requires an
+        # rw grant on the path and rejects a missing mode.
+        def change_mode(path, mode) = @runtime.request(:file, :change_mode, { "path" => path.to_s, "mode" => mode })
+      end
+
+      class Directory
+        def initialize(runtime) = @runtime = runtime
+        def list(path)          = @runtime.request(:directory, :list, { "path" => path.to_s })
+        alias_method :ls, :list # v1 commands call `directory.ls`; same op, no protocol change
+        def create(path)        = @runtime.request(:directory, :create, { "path" => path.to_s })
+        def exist?(path)        = @runtime.request(:directory, :exist, { "path" => path.to_s })
+        def delete(path)        = @runtime.request(:directory, :delete, { "path" => path.to_s })
+      end
+
+      class Browser
+        def initialize(runtime) = @runtime = runtime
+        def launch(url)         = @runtime.request(:browser, :launch, { "url" => url.to_s })
+      end
+    end
+  end
+end

data/lib/terminalwire/v2/server/dual_thor.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "thor" # reuse the v2 Shell + Helpers
+
+module Terminalwire::V2
+  module Server
+    # ONE Thor CLI, BOTH protocols. Apply `Server.dualize(MyCLI)` to a Thor class
+    # that already includes the v1 `Terminalwire::Thor` adapter, and it runs
+    # unchanged over the v1 AND v2 wire. This works because both servers invoke a
+    # CLI through the SAME entry — `cli_class.terminalwire(arguments:, context:)` —
+    # and both contexts expose the same I/O surface (puts/print/warn/gets/getpass).
+    #
+    # The adapter:
+    #   - its single `terminalwire` entry builds the v2 Shell for a v2 context and
+    #     otherwise delegates to the v1 adapter via `super` (preserving the v1/rails
+    #     shell exactly);
+    #   - its helpers route bare puts/print/warn/gets/getpass through the active
+    #     `shell.context`, which is whichever protocol's context is live.
+    module DualThor
+      def self.included(base)
+        base.extend ClassMethods
+        base.include Terminalwire::V2::Server::Thor::Helpers
+      end
+
+      module ClassMethods
+        def terminalwire(arguments:, context:, &block)
+          if context.is_a?(Terminalwire::V2::Server::Context)
+            dispatch(nil, arguments.dup, nil, shell: Terminalwire::V2::Server::Thor::Shell.new(context)) do |instance|
+              block.call(instance) if block
+            end
+          else
+            super # v1 adapter's terminalwire (its own shell)
+          end
+        end
+      end
+    end
+
+    # Walk a Thor class + its subcommand tree, making every command class respond to
+    # both protocols. Idempotent. Returns the class so it reads as a transform.
+    def self.dualize(klass, seen = {})
+      return klass if seen[klass]
+      seen[klass] = true
+      klass.include(DualThor) unless klass.include?(DualThor)
+      klass.subcommand_classes.each_value { |sub| dualize(sub, seen) } if klass.respond_to?(:subcommand_classes)
+      klass
+    end
+
+    # Walk a Thor class + its subcommand tree, making every command class speak v2
+    # NATIVELY — it includes Terminalwire::V2::Server::Thor (whose `terminalwire`
+    # dispatches with the v2 shell, no v1 `super`). This is the v2-only path: the
+    # app loads only the v2 gem. `dualize` is the transitional both-protocols path.
+    # Idempotent. Returns the class.
+    def self.terminalize(klass, seen = {})
+      return klass if seen[klass]
+      seen[klass] = true
+      klass.include(Terminalwire::V2::Server::Thor) unless klass.include?(Terminalwire::V2::Server::Thor)
+      klass.subcommand_classes.each_value { |sub| terminalize(sub, seen) } if klass.respond_to?(:subcommand_classes)
+      klass
+    end
+  end
+end

data/lib/terminalwire/v2/server/flow.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Terminalwire::V2
+  module Server
+    # Credit-based flow control for server -> client output streams (the SSH /
+    # HTTP-2 window model). Each output stream has a window: the number of bytes
+    # the client will accept before the server must wait. #reserve is called on
+    # the sending (CLI) thread before emitting a data frame — it blocks only until
+    # *some* credit exists, then takes up to what's asked (so a write larger than
+    # the window can never deadlock); #grant is called on the read-pump thread when
+    # a window_adjust arrives and wakes the sender. This is what stops a fast
+    # server from outrunning a slow client and ballooning the transport's buffers.
+    #
+    # The core invariant it enforces: at any instant, the bytes the server has
+    # sent but not yet had credited never exceed the window the client granted.
+    class FlowController
+      def initialize
+        @windows = {}
+        @mutex = Mutex.new
+        @cv = ConditionVariable.new
+        @closed = false
+        @error = nil
+      end
+
+      # Begin tracking a stream with an initial window (the client's offer). The
+      # credit accounting itself lives in the pure Window (the protocol rule);
+      # this class only adds the blocking + thread-safety (the implementation).
+      def open(sid, initial)
+        @mutex.synchronize { @windows[sid] = Window.new(initial) }
+      end
+
+      # Reserve up to `max` bytes for `sid`, blocking only until at least one byte
+      # of credit exists, then taking min(available, max). Returns the amount
+      # taken. Sizing each frame to current credit means a single write larger
+      # than the window never deadlocks. Raises if shut down while waiting.
+      def reserve(sid, max)
+        @mutex.synchronize do
+          loop do
+            raise(@error || ProtocolError.new("flow closed")) if @closed
+
+            window = @windows[sid]
+            taken = window ? window.take(max) : 0
+            return taken if taken.positive?
+
+            @cv.wait(@mutex)
+          end
+        end
+      end
+
+      # Return `bytes` of credit for `sid` (from a window_adjust) and wake senders.
+      def grant(sid, bytes)
+        @mutex.synchronize do
+          # A grant for an unknown/closed stream is harmless and ignored.
+          @windows[sid]&.grant(bytes)
+          @cv.broadcast
+        end
+      end
+
+      def available(sid)
+        @mutex.synchronize { @windows[sid]&.available || 0 }
+      end
+
+      def close(sid)
+        @mutex.synchronize { @windows.delete(sid) }
+      end
+
+      # Unblock every waiting sender with an error (connection died).
+      def shutdown(error)
+        @mutex.synchronize do
+          @closed = true
+          @error = error
+          @cv.broadcast
+        end
+      end
+    end
+  end
+end

data/lib/terminalwire/v2/server/handler.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Terminalwire::V2
+  module Server
+    # The framework-agnostic server entrypoint: performs the handshake, runs your
+    # CLI with a Terminalwire-backed context, handles errors, and exits the client.
+    # A Rails or Rack adapter just builds a transport and calls this.
+    #
+    # Your CLI can be ANY of:
+    #   * a block / callable run(context, args) — works with OptionParser, GLI,
+    #     dry-cli, or hand-rolled parsing. The block runs inside `Server.redirect`,
+    #     so $stdout/$stderr/$stdin and bare puts/gets already target the client.
+    #   * a Thor class via `cli_class:` (it gets Thor's dedicated shell adapter).
+    #
+    #   # OptionParser (or anything using the standard IO globals):
+    #   Handler.new do |ctx, args|
+    #     opts = {}
+    #     OptionParser.new { |o| o.on("--name NAME") { |v| opts[:name] = v } }.parse!(args)
+    #     puts "hello #{opts[:name]}"
+    #   end
+    #
+    #   # Thor:
+    #   Handler.new(cli_class: MyThorCLI)
+    class Handler
+      DEFAULT_ERROR_MESSAGE = "An error occurred. Please try again."
+
+      # @param cli_class [Class, nil] a Thor CLI that `include`s Server::Thor
+      # @param run [#call, nil] a callable (context, args) for non-Thor CLIs
+      # @param report [#call, nil] optional callable invoked with unexpected errors
+      # @param verbose [Boolean] show full backtraces to the client (dev only)
+      # @yield [context, args] block form of `run:`
+      def initialize(cli_class: nil, run: nil, report: nil, verbose: false,
+                     error_message: DEFAULT_ERROR_MESSAGE, &block)
+        @cli_class = cli_class
+        @run = run || block
+        @report = report
+        @verbose = verbose
+        @error_message = error_message
+
+        return if @cli_class || @run
+
+        raise ArgumentError, "provide a Thor cli_class:, a run: callable, or a block"
+      end
+
+      # Run one session over the given transport. Returns the exit status.
+      # `request` is the incoming HTTP connection profile from the Rack env
+      # ({ host:, ip:, user_agent:, headers: }) — threaded in so URL helpers can use
+      # the host (v1 set `cli.default_url_options[:host]` the same way) and so server
+      # code / `about` can see who connected.
+      def call(transport:, request: {})
+        runtime = Runtime.new(transport: transport).handshake
+        context = Context.new(runtime)
+        context.request = request
+        arguments = context.program_arguments
+        status = 0
+
+        begin
+          begin
+            dispatch(context, arguments, request[:host])
+          rescue Interrupt, Interrupted
+            status = 130
+          rescue SystemExit => e
+            # A command that called `exit`/`abort` raises SystemExit (not a
+            # StandardError). Without this it would slip past the rescue below, the
+            # ensure would send the client `exit(0)` — reporting success — and the
+            # exception would then silently kill the CLI thread. Honor the real code.
+            status = e.status
+          rescue StandardError => e
+            status = handle_error(e, context)
+          ensure
+            # Teardown must not be interrupted. A late Ctrl-C (delivered as an async
+            # Interrupted via Thread#raise) landing here would abort the exit-frame
+            # write or runtime close and hang the client — the very failure the
+            # interrupt machinery exists to avoid. Mask async interrupts for the
+            # duration so the exit frame always flushes and the runtime always closes.
+            Thread.handle_interrupt(Interrupt => :never, Interrupted => :never) do
+              context.exit(status)
+              runtime.close
+            end
+          end
+        rescue Interrupt, Interrupted
+          # An interrupt that fired in a rescue clause above, before the mask took
+          # hold, surfaces here. Teardown still ran in the ensure, so just report it.
+          status = 130
+        end
+
+        status
+      end
+
+      private
+
+      # Route to the Thor adapter or the generic redirect-based runner. `host`, when
+      # present, is set on the per-session Thor instance so Rails URL helpers resolve
+      # (instance-level, like v1 — no shared class-global to race across sessions).
+      def dispatch(context, arguments, host = nil)
+        if @cli_class
+          @cli_class.terminalwire(arguments: arguments, context: context) do |cli|
+            cli.default_url_options[:host] = host if host && cli.respond_to?(:default_url_options)
+          end
+        else
+          # Generic path: point the global IO streams at the client, then run the
+          # user's callable. OptionParser/GLI/dry-cli/bare puts all Just Work.
+          Server.redirect(context, argv: arguments) do
+            @run.call(context, arguments)
+          end
+        end
+      end
+
+      def handle_error(error, context)
+        # A denied resource op means the client refused the grant: show an actionable
+        # message (the client also prints the exact `terminalwire-policy … --approve`
+        # locally) instead of the scary generic one — and don't report it (it's a
+        # consent decision, not a bug).
+        if denied_error?(error)
+          context.warn("Terminalwire couldn't manage your install — it needs filesystem " \
+                       "access you haven't granted (#{error.message}). Your client printed " \
+                       "the `terminalwire-policy … --approve` command to grant it.")
+        # Thor's own user-facing errors (unknown command, bad args) are friendly
+        # already — pass them through verbatim. OptionParser's are too.
+        elsif friendly_error?(error)
+          context.warn(error.message)
+        else
+          @report&.call(error)
+          context.warn(@verbose ? backtrace(error) : @error_message)
+        end
+        1
+      end
+
+      def denied_error?(error)
+        error.is_a?(ResponseError) && error.code == "denied"
+      end
+
+      def friendly_error?(error)
+        (defined?(::Thor::Error) && error.is_a?(::Thor::Error)) ||
+          (defined?(::OptionParser::ParseError) && error.is_a?(::OptionParser::ParseError))
+      end
+
+      def backtrace(error)
+        "#{error.class}: #{error.message}\n#{Array(error.backtrace).join("\n")}"
+      end
+    end
+  end
+end

data/lib/terminalwire/v2/server/io.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Terminalwire::V2
+  module Server
+    # An IO-shaped object backed by the Terminalwire Context. This is the
+    # universal adapter: anything that writes to an IO (Kernel#puts, OptionParser
+    # help/errors, Logger, a library's `output:`) or reads from one (`$stdin.gets`)
+    # works against the client's terminal when handed one of these.
+    #
+    # `Server.redirect` swaps the global $stdout/$stderr/$stdin for these so an
+    # ordinary CLI needs no Terminalwire-specific code; Thor uses them directly
+    # because its shell captures the streams at construction.
+    class IO
+      # @param context [Context]
+      # @param stream [:stdout, :stderr, :stdin]
+      def initialize(context, stream)
+        @context = context
+        @stream = stream
+      end
+
+      # --- writing (stdout/stderr) ---
+
+      def print(*args)
+        args.each { |arg| @context.print(arg.to_s, stream: @stream) }
+        nil
+      end
+
+      def write(*args)
+        args.sum { |arg| s = arg.to_s; @context.print(s, stream: @stream); s.bytesize }
+      end
+
+      def <<(arg)
+        @context.print(arg.to_s, stream: @stream)
+        self
+      end
+
+      def puts(*args)
+        if args.empty?
+          @context.print("\n", stream: @stream)
+        else
+          args.flatten.each { |arg| @context.print("#{arg}\n", stream: @stream) }
+        end
+        nil
+      end
+
+      def printf(format, *args)
+        print(format % args)
+      end
+
+      def flush = self
+      def sync = true
+      def sync=(value)
+        value
+      end
+
+      # --- reading (stdin) ---
+
+      def gets(*) = @context.stdin.gets
+      def getpass(*) = @context.stdin.getpass
+      def read = @context.stdin.read
+
+      def each_line(&block)
+        return enum_for(:each_line) unless block
+
+        while (line = gets)
+          block.call(line)
+        end
+      end
+      alias each each_line
+
+      # --- terminal reflection (so tty-screen/tty-table/pastel target the client) ---
+
+      # Per-stream: this proxy's own stream is what isatty(stdout) etc. ask about.
+      def tty? = @context.terminal.stream(@stream).tty?
+      def winsize = @context.terminal.winsize
+      def isatty = tty?
+
+      # Answer the window-size ioctl (TIOCGWINSZ) that tty-screen probes, filling
+      # the caller's buffer with the CLIENT's [rows, cols] — so tty-screen-based
+      # libraries (tty-progressbar, tty-spinner, …) size to the client instead of
+      # crashing on a non-IO stream. Other ioctls are no-ops.
+      def ioctl(_cmd, buf = nil)
+        if buf.is_a?(String)
+          rows, cols = @context.terminal.winsize
+          buf[0, 8] = [rows.to_i, cols.to_i, 0, 0].pack("S4") # matches tty-screen's "SSSS"
+        end
+        0
+      end
+    end
+  end
+end