portage-cli 0.7.5 → 0.8.0

data/lib/portage/cli/browser_profile/cdp.rb

@@ -0,0 +1,67 @@
+require "net/http"
+require "uri"
+require "json"
+require "portage/ucp/support/connection"
+
+module Portage
+  module Cli
+    module BrowserProfile
+      # The plain-HTTP half of Chrome DevTools Protocol: the
+      # `http://127.0.0.1:<port>/json/*` endpoints every Chromium browser
+      # exposes once started with `--remote-debugging-port`. Used for
+      # "is the profile running, and what tab is it on" (`.version`/
+      # `.list`) and to open a tab already navigated to a URL (`.new_tab`)
+      # without needing the WebSocket layer (CdpSocket) at all for that.
+      #
+      # Every call is read-only against the local debugging port, GET/PUT
+      # requests only, `route: :probe` (same route category ProbeCache's
+      # own `/.well-known/ucp` probes use) so it's subject to whatever
+      # proxy config a `--no-proxy` list already exempts localhost from.
+      # A failure (not running, timeout, bad JSON) returns nil rather than
+      # raising — callers (Profile) decide what that means.
+      module Cdp
+        TIMEOUT = 3
+        HOST = "127.0.0.1".freeze
+
+        def self.version(port:, host: HOST) = get(host, port, "/json/version")
+
+        def self.list(port:, host: HOST) = Array(get(host, port, "/json/list"))
+
+        # Opens a new tab already navigated to `url` — Chrome's own
+        # `/json/new?<url>` endpoint, a PUT since it creates something
+        # server-side.
+        def self.new_tab(port:, url:, host: HOST)
+          get(host, port, "/json/new?#{URI.encode_www_form_component(url)}", method: :put)
+        end
+
+        # `/json/close/<id>` answers plain text ("Target is closing"), not
+        # JSON — checked by success status only, never parsed as JSON.
+        def self.close_tab(port:, id:, host: HOST)
+          uri = URI("http://#{host}:#{port}/json/close/#{id}")
+          fetch(uri, :get).is_a?(Net::HTTPSuccess)
+        rescue StandardError
+          false
+        end
+
+        def self.get(host, port, path, method: :get)
+          uri = URI("http://#{host}:#{port}#{path}")
+          response = fetch(uri, method)
+          return nil unless response.is_a?(Net::HTTPSuccess)
+
+          JSON.parse(response.body)
+        rescue StandardError
+          nil
+        end
+        private_class_method :get
+
+        def self.fetch(uri, method)
+          Portage::Ucp::Support::Connection.start(uri, route: :probe, open_timeout: TIMEOUT,
+                                                       read_timeout: TIMEOUT) do |http|
+            method == :put ? http.request(Net::HTTP::Put.new(uri.request_uri)) : http.get(uri.request_uri)
+          end
+        end
+        private_class_method :fetch
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_profile/cdp_socket.rb

@@ -0,0 +1,186 @@
+require "socket"
+require "securerandom"
+require "digest/sha1"
+require "base64"
+require "json"
+require "uri"
+require "timeout"
+
+module Portage
+  module Cli
+    module BrowserProfile
+      # A minimal, dependency-free WebSocket JSON-RPC client for a Chrome
+      # DevTools Protocol target — just enough to call `Runtime.evaluate`/
+      # `Page.navigate`/`Page.enable` on a page's own `webSocketDebuggerUrl`
+      # synchronously, one request at a time. Not a general WebSocket
+      # client: text frames only, no compression extension, and no
+      # concurrent in-flight requests — Bridge never has two CDP calls
+      # outstanding at once, so `#call` blocks until its own response (by
+      # `id`) comes back, discarding any unsolicited event frame in
+      # between.
+      #
+      # `transport:` is injectable (any object answering `#write`/`#read`/
+      # `#close`, e.g. a real TCPSocket) so specs never open a real socket
+      # — see cdp_socket_spec.rb.
+      class CdpSocket
+        GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11".freeze
+        TIMEOUT = 30
+
+        def self.connect(ws_url, transport: nil, timeout: TIMEOUT)
+          uri = URI.parse(ws_url)
+          transport ||= TCPSocket.new(uri.host, uri.port)
+          handshake!(transport, uri, timeout: timeout)
+          new(transport)
+        end
+
+        def initialize(transport)
+          @transport = transport
+          @next_id = 1
+        end
+
+        # @return [Hash] the CDP "result" object.
+        # @raise [RuntimeError] the CDP "error" object's message, when the
+        #   browser itself rejected the command (bad method/params, no
+        #   such target) — distinct from an *evaluated script* raising,
+        #   which comes back as a normal result with `exceptionDetails`.
+        def call(method, params = {})
+          id = @next_id
+          @next_id += 1
+          send_frame(JSON.generate(id: id, method: method, params: params))
+          await_response(id)
+        end
+
+        def close
+          @transport.close
+        rescue StandardError
+          nil
+        end
+
+        private
+
+        def await_response(id)
+          loop do
+            message = JSON.parse(read_message)
+            next if message["id"] != id
+
+            raise message.dig("error", "message").to_s if message["error"]
+
+            return message["result"] || {}
+          end
+        end
+
+        # --- outbound framing (client -> server frames MUST be masked,
+        # RFC 6455 §5.1) ---
+
+        def send_frame(payload)
+          bytes = payload.b
+          mask = SecureRandom.random_bytes(4)
+          @transport.write(frame_header(0x1, bytes.bytesize) + mask + xor(bytes, mask))
+        end
+
+        def send_pong(payload)
+          bytes = payload.to_s.b
+          mask = SecureRandom.random_bytes(4)
+          @transport.write(frame_header(0xA, bytes.bytesize) + mask + xor(bytes, mask))
+        end
+
+        def frame_header(opcode, length)
+          first = 0x80 | opcode # FIN=1
+          return [first, 0x80 | length].pack("CC") if length <= 125
+          return [first, 0x80 | 126, length].pack("CCn") if length <= 0xFFFF
+
+          [first, 0x80 | 127, length].pack("CCQ>")
+        end
+
+        def xor(bytes, mask)
+          bytes.each_byte.with_index.map { |byte, i| byte ^ mask.getbyte(i % 4) }.pack("C*")
+        end
+
+        # --- inbound framing (server -> client frames are never masked)
+        # ---
+
+        # Reads whole logical messages (following any continuation
+        # frames), answering pings and dropping pongs, until it has one
+        # worth handing to #await_response.
+        def read_message
+          buffer = +""
+          loop do
+            fin, opcode, payload = read_one_frame
+            case opcode
+            when 0x9 then send_pong(payload)
+            when 0x8 then raise "CDP socket closed by the browser"
+            when 0xA then nil
+            else buffer << payload
+            end
+            return buffer if fin && [0x0, 0x1].include?(opcode)
+          end
+        end
+
+        def read_one_frame
+          b1, b2 = read_exactly(2).unpack("CC")
+          fin = b1[7] == 1
+          opcode = b1 & 0x0F
+          masked = b2[7] == 1
+          [fin, opcode, read_payload(b2 & 0x7F, masked)]
+        end
+
+        def read_payload(length, masked)
+          length = read_exactly(2).unpack1("n") if length == 126
+          length = read_exactly(8).unpack1("Q>") if length == 127
+          mask = read_exactly(4) if masked
+          payload = length.positive? ? read_exactly(length) : +""
+          mask ? xor(payload, mask) : payload
+        end
+
+        def read_exactly(length)
+          return +"" if length <= 0
+
+          Timeout.timeout(TIMEOUT) do
+            data = +""
+            while data.bytesize < length
+              chunk = @transport.read(length - data.bytesize)
+              raise "CDP socket closed by the browser" if chunk.nil?
+
+              data << chunk
+            end
+            data
+          end
+        end
+
+        # --- handshake (RFC 6455 §4) ---
+
+        def self.handshake!(transport, uri, timeout:)
+          key = SecureRandom.base64(16)
+          Timeout.timeout(timeout) { transport.write(handshake_request(uri, key)) }
+          headers = Timeout.timeout(timeout) { read_headers(transport) }
+          verify_handshake!(headers, key)
+        end
+        private_class_method :handshake!
+
+        def self.handshake_request(uri, key)
+          path = uri.path.to_s.empty? ? "/" : uri.path
+          path += "?#{uri.query}" if uri.query
+          "GET #{path} HTTP/1.1\r\nHost: #{uri.host}:#{uri.port}\r\nUpgrade: websocket\r\n" \
+            "Connection: Upgrade\r\nSec-WebSocket-Key: #{key}\r\nSec-WebSocket-Version: 13\r\n\r\n"
+        end
+        private_class_method :handshake_request
+
+        def self.read_headers(transport)
+          data = +""
+          data << transport.read(1) until data.end_with?("\r\n\r\n")
+          data
+        end
+        private_class_method :read_headers
+
+        def self.verify_handshake!(headers, key)
+          raise "CDP handshake failed: #{headers.lines.first}" unless headers.start_with?("HTTP/1.1 101")
+
+          expected = Base64.strict_encode64(Digest::SHA1.digest(key + GUID))
+          accept = headers[/Sec-WebSocket-Accept:\s*(\S+)/i, 1]
+          raise "CDP handshake failed: unexpected Sec-WebSocket-Accept" unless accept == expected
+        end
+        private_class_method :verify_handshake!
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_profile/errors.rb

@@ -0,0 +1,26 @@
+module Portage
+  module Cli
+    module BrowserProfile
+      # Base for everything this feature raises — a caller (cli.rb, Buy)
+      # can rescue this one class instead of naming each subclass.
+      class Error < StandardError; end
+
+      # `Browsers.binary_for` found nothing installed for the requested
+      # browser.
+      class BrowserNotFoundError < Error; end
+
+      # The profile process never answered its own CDP endpoint within the
+      # launch wait — a slow machine, a browser that failed to start, or a
+      # port already held by something else.
+      class LaunchError < Error; end
+
+      # docs/plans/buy-skill-and-local-browser.md Phase 6: driving stayed
+      # inside the allowed domains (the store being bought from, plus its
+      # checkout host once known) or this stopped the run rather than
+      # continue on an unexpected host. Never rescued into "try again
+      # somewhere else" — the whole point is that nothing here recovers by
+      # itself.
+      class DomainNotAllowedError < Error; end
+    end
+  end
+end

data/lib/portage/cli/browser_profile/launcher.rb

@@ -0,0 +1,34 @@
+module Portage
+  module Cli
+    module BrowserProfile
+      # The one place `Process.spawn` is called from this feature —
+      # injectable (`spawn:`) so Profile's own specs never start a real
+      # browser (docs/plans/buy-skill-and-local-browser.md Phase 6's own
+      # "specs must not launch a real browser" rule).
+      #
+      # Flags: `--user-data-dir` is always the dedicated Portage profile
+      # directory (never the browser's default one — Chrome 136+ refuses
+      # remote debugging on the default profile anyway, and this never
+      # tries), `--remote-debugging-port` is this profile's own fixed
+      # port, and `--no-first-run`/`--no-default-browser-check` keep the
+      # launch from popping up onboarding UI the first time. Detached
+      # (its own process group, stdout/stderr discarded) so `portage
+      # browser profile open` returns immediately rather than blocking on
+      # the browser's own lifetime.
+      class Launcher
+        def initialize(spawn: ->(*args) { Process.spawn(*args) })
+          @spawn = spawn
+        end
+
+        def launch(binary:, profile_dir:, port:, url: nil)
+          argv = [binary, "--user-data-dir=#{profile_dir}", "--remote-debugging-port=#{port}",
+                  "--no-first-run", "--no-default-browser-check"]
+          argv << url if url
+          pid = @spawn.call(*argv, %i[out err] => File::NULL, pgroup: true)
+          Process.detach(pid)
+          pid
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_profile/profile.rb

@@ -0,0 +1,93 @@
+require "fileutils"
+require_relative "browsers"
+require_relative "cdp"
+require_relative "errors"
+require_relative "launcher"
+
+module Portage
+  module Cli
+    module BrowserProfile
+      # `portage browser profile init|open|status` (docs/plans/
+      # buy-skill-and-local-browser.md Phase 6): a dedicated Chromium
+      # profile directory under ~/.portage/browser/<browser>/profile,
+      # launched with remote debugging bound to that profile only —
+      # never the browser's own default profile, and never a directory
+      # this class didn't create itself. The user signs into their
+      # shopping sites in this profile once; nothing here ever reads a
+      # credential, cookie or autofill store from it (that's Chromium's
+      # own job once the shopper is looking at the page).
+      class Profile
+        ROOT = File.join(Dir.home, ".portage", "browser").freeze
+        DEFAULT_PORT = 9223
+
+        attr_reader :browser, :port, :dir
+
+        def initialize(browser: "chrome", root: ROOT, port: DEFAULT_PORT, launcher: Launcher.new, cdp: Cdp,
+                       poll_attempts: 20, poll_interval: 0.25, sleep_fn: ->(s) { sleep s })
+          raise ArgumentError, "unsupported browser #{browser.inspect} (want one of #{Browsers::CHROMIUM})" unless
+            Browsers::CHROMIUM.include?(browser)
+
+          @browser = browser
+          @dir = File.join(root, browser, "profile")
+          @port = port
+          @launcher = launcher
+          @cdp = cdp
+          @poll_attempts = poll_attempts
+          @poll_interval = poll_interval
+          @sleep_fn = sleep_fn
+        end
+
+        # Never launches anything — just makes sure the dedicated profile
+        # directory exists, so `portage browser profile open` always has
+        # somewhere of its own to point `--user-data-dir` at.
+        def init!
+          FileUtils.mkdir_p(@dir)
+          { browser: @browser, dir: @dir, port: @port, created: true }
+        end
+
+        # @return [Hash] `running:` plus, when running, whatever
+        #   `/json/version` reports (Browser, protocolVersion, …) — no
+        #   HTTP request is ever made to anything but 127.0.0.1:`port`.
+        def status
+          version = @cdp.version(port: @port)
+          base = { running: !version.nil?, browser: @browser, dir: @dir, port: @port }
+          version ? base.merge(version) : base
+        end
+
+        # Launches the browser if it isn't already running on this
+        # profile's port, then either opens a new tab at `url` or hands
+        # back the first existing tab. Idempotent: calling this against an
+        # already-running profile just attaches.
+        def open!(url: nil)
+          launch! unless status[:running]
+          attach(url)
+        end
+
+        private
+
+        def launch!
+          binary = Browsers.binary_for(@browser)
+          raise BrowserNotFoundError, "#{@browser} isn't installed on this machine" unless binary
+
+          FileUtils.mkdir_p(@dir)
+          @launcher.launch(binary: binary, profile_dir: @dir, port: @port)
+          wait_until_running!
+        end
+
+        def wait_until_running!
+          @poll_attempts.times do
+            return true if status[:running]
+
+            @sleep_fn.call(@poll_interval)
+          end
+          raise LaunchError, "#{@browser} didn't answer its remote-debugging port (#{@port}) in time"
+        end
+
+        def attach(url)
+          target = url ? @cdp.new_tab(port: @port, url: url) : @cdp.list(port: @port).first
+          { running: true, browser: @browser, dir: @dir, port: @port, target: target }
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/browser_profile.rb

@@ -0,0 +1,25 @@
+require_relative "browser_profile/errors"
+require_relative "browser_profile/browsers"
+require_relative "browser_profile/cdp"
+require_relative "browser_profile/cdp_socket"
+require_relative "browser_profile/allowlist"
+require_relative "browser_profile/bridge"
+require_relative "browser_profile/launcher"
+require_relative "browser_profile/profile"
+
+module Portage
+  module Cli
+    # `portage browser profile init|open|status` — the Portage browser
+    # profile (docs/plans/buy-skill-and-local-browser.md Phase 6, Tier B).
+    # A dedicated Chromium-family profile directory under
+    # ~/.portage/browser/, never the browser's own default profile, that
+    # `portage buy --handoff-target profile` drives as a WebMCP bridge
+    # (see Bridge) limited to a domain allowlist (Allowlist) — the store
+    # being bought from, plus its checkout host once known. The user signs
+    # into their shopping sites in it once; Portage never reads a
+    # credential/cookie/autofill store from it, never touches a payment
+    # field, and never clicks pay.
+    module BrowserProfile
+    end
+  end
+end