wokku-cli 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d6db99db4bf59f5b55f619cbd6abb12fc6b3f711fba103b327e6d0b01479114
-  data.tar.gz: 0b10a6ea71101885f3929f7f6055705b6a0d98ebcb2a21147070911c0522b24a
+  metadata.gz: 90dbd93905c3fc3dc7422cf4342def249b9ff04d3c5bbefd64f5d4a5ccc23cb6
+  data.tar.gz: 01b1043ff82e7ae509ddb36eed9fa6d9657b7321ae82502996c448eb4d755440
 SHA512:
-  metadata.gz: 8b3e284c92712469309c2a3aab4fffa60e26b89727f8bf948e1bfaba87e70b572eca298ec69ee1449d6112656d478294c825f1d826b0a7f9d2f7a02b57820085
-  data.tar.gz: e3f998fd1ec992942da0319c4838cf664dbbda1ef49cb9a777a35da0acc3d1a29ec0486df464f5b45bd3d9cc3eb431098e23b7bb047462d1fc6a27d90f26772d
+  metadata.gz: 7650db80c9d0608c8f879c86f556008ae47af5cd3827e029378e7327e455b9762ef6f4260a73f0d1da61c7c8a93b2bdfe03fd01fae1ca3212e60acbbfa61bc56
+  data.tar.gz: 33fbc61d1092de38e30737cedcb83750bc55fa8193f1cf3604599e5ecf7e6103bc16faa7775c8bab0217d44dc3ba2b33cae6804c921007888f9097c277e94f78

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.2.0 — 2026-05-06
+
+Interactive shell over WebSocket: open a real PTY in your app's container, exec one-off commands, and connect to managed databases without leaving the terminal.
+
+### Added
+- `wokku enter APP` — interactive shell in the app's running container.
+- `wokku ps:exec APP [-t|-T] -- CMD [ARGS...]` — run a command in a one-off container (Heroku-`run`-style; auto-detects TTY, `-t`/`-T` overrides).
+- `wokku databases:connect DB` — interactive client for the managed database (psql / redis-cli / mysql via dokku's `<plugin>:connect`).
+
+### Internals
+- New `Wokku::CableClient` — thin `websocket-driver` wrapper, Bearer-token handshake on `/cable`.
+- New `Wokku::PtySession` — local raw-mode PTY orchestration with SIGWINCH resize and guaranteed `cooked!` restore.
+- Runtime dependency: `websocket-driver ~> 0.7`.
+
+### Requires
+- wokku-cloud server-side support shipped 2026-05-06 (Bearer auth on `ApplicationCable::Connection`, new `TerminalChannel` wire protocol with modes).
+
 ## 0.1.0 — 2026-05-04
 
 First public release on RubyGems.

data/lib/wokku/auth.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Wokku
+  # Authentication flows for `wokku auth:login`.
+  #
+  # CLI requests a device_code + user_code from /auth/device/code, opens
+  # the verification URL in the browser, and polls /auth/device/token
+  # until the user approves the session in the dashboard. Server returns
+  # an api_token which the CLI persists to ~/.wokku/config.
+  module Auth
+    POLL_FLOOR = 1.0  # don't poll faster than 1s regardless of server hint
+
+    module_function
+
+    def login_with_device_flow!(url)
+      code = post_json(url, "/auth/device/code", {})
+      user_code  = code.fetch("user_code")
+      device_code = code.fetch("device_code")
+      verify_uri = code.fetch("verification_uri_complete")
+      interval   = (code["interval"] || 5).to_i
+      expires_at = Time.now + (code["expires_in"] || 600).to_i
+
+      puts
+      puts "  To finish signing in, open this URL in your browser:"
+      puts
+      puts "    #{verify_uri}"
+      puts
+      puts "  And confirm the code:  \e[1m#{user_code}\e[0m"
+      puts
+      open_browser(verify_uri)
+      print "  Waiting for approval"
+
+      loop do
+        if Time.now > expires_at
+          puts
+          abort "Login timed out. Run `wokku auth:login` again."
+        end
+
+        sleep_for([interval, POLL_FLOOR].max)
+        print "."
+        $stdout.flush
+
+        resp = post_raw(url, "/auth/device/token", { device_code: device_code })
+        body = JSON.parse(resp.body) rescue {}
+        case resp.code.to_i
+        when 200
+          token = body.fetch("token")
+          email = body.dig("user", "email")
+          save_config({ "api_url" => url, "token" => token, "email" => email })
+          puts
+          Wokku::Output.status "Logged in as #{email}"
+          Wokku::Output.status "Connected to: #{instance_label(url)}"
+          return
+        when 202
+          # authorization_pending — keep polling
+        when 400
+          # slow_down — back off
+          interval += 5
+        when 403
+          puts
+          abort "Login denied."
+        when 410
+          puts
+          abort "Login code expired. Run `wokku auth:login` again."
+        else
+          puts
+          abort "Login failed: #{resp.code} #{body['error']}"
+        end
+      end
+    end
+
+    def post_json(base_url, path, payload)
+      resp = post_raw(base_url, path, payload)
+      data = JSON.parse(resp.body) rescue {}
+      unless resp.is_a?(Net::HTTPSuccess)
+        abort "Request failed: #{resp.code} #{data['error'] || resp.body}"
+      end
+      data
+    end
+
+    def post_raw(base_url, path, payload)
+      uri = URI("#{base_url}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = 10
+      http.read_timeout = 30
+      req = Net::HTTP::Post.new(uri)
+      req["Content-Type"] = "application/json"
+      req["Accept"] = "application/json"
+      req.body = payload.to_json
+      http.request(req)
+    end
+
+    def open_browser(url)
+      cmd =
+        case RUBY_PLATFORM
+        when /darwin/  then "open"
+        when /mswin|mingw|cygwin/ then "start"
+        else "xdg-open"
+        end
+      # Best-effort; ignore failures (CI, no GUI, etc.)
+      system(cmd, url, out: File::NULL, err: File::NULL) rescue nil
+    end
+
+    def instance_label(url)
+      url.include?("wokku.cloud") ? "wokku.cloud (managed)" : "#{URI(url).host} (self-hosted)"
+    end
+
+    def sleep_for(seconds)
+      Kernel.sleep(seconds)
+    end
+  end
+end

data/lib/wokku/cable_client.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "openssl"
+require "uri"
+require "websocket/driver"
+
+module Wokku
+  class CableClient
+    SUBSCRIBE_TIMEOUT = 10
+
+    def initialize(url:, token:)
+      @uri = URI(url)
+      @token = token
+      @on_message = ->(_) {}
+      @on_close = ->(_) {}
+      @subscribed = false
+      @identifier = nil
+      @socket = open_socket
+      @driver = WebSocket::Driver.client(self)
+      @driver.set_header("Authorization", "Bearer #{@token}") if @token && !@token.empty?
+      @driver.set_header("Origin", origin_header)
+      attach_driver_callbacks
+      @driver.start
+    end
+
+    # Origin matches the cable host so ActionCable's same-origin check passes.
+    # CSRF concerns don't apply: the CLI authenticates via Bearer token, not
+    # a cookie-borne session, so cross-site forgery is not a vector here.
+    def origin_header
+      scheme = @uri.scheme == "wss" ? "https" : "http"
+      port = (@uri.port && ![ 80, 443 ].include?(@uri.port)) ? ":#{@uri.port}" : ""
+      "#{scheme}://#{@uri.host}#{port}"
+    end
+
+    # WebSocket::Driver duck-types these on its socket adapter:
+    def url
+      @uri.to_s
+    end
+
+    def write(data)
+      @socket.write(data)
+    end
+
+    def on_message(&block)
+      @on_message = block
+    end
+
+    def on_close(&block)
+      @on_close = block
+    end
+
+    def subscribe(channel:, params: {})
+      @identifier = JSON.dump({ channel: channel, **params })
+      @driver.text(JSON.dump(command: "subscribe", identifier: @identifier))
+      deadline = Time.now + SUBSCRIBE_TIMEOUT
+      pump_until { @subscribed || Time.now > deadline }
+      raise "subscribe timed out" unless @subscribed
+    end
+
+    def send_message(payload)
+      @driver.text(JSON.dump(command: "message", identifier: @identifier, data: JSON.dump(payload)))
+    end
+
+    def pump(timeout = 0.05)
+      ready = IO.select([@socket], nil, nil, timeout)
+      return unless ready
+      @driver.parse(@socket.read_nonblock(4096))
+    rescue IO::WaitReadable
+      # transient
+    rescue EOFError
+      @on_close.call(:eof)
+    end
+
+    def close
+      @driver.close rescue nil
+      @socket.close rescue nil
+    end
+
+    private
+
+    def open_socket
+      tcp = TCPSocket.new(@uri.host, @uri.port || (@uri.scheme == "wss" ? 443 : 80))
+      return tcp if @uri.scheme == "ws"
+
+      ctx = OpenSSL::SSL::SSLContext.new
+      ctx.set_params
+      ssl = OpenSSL::SSL::SSLSocket.new(tcp, ctx)
+      ssl.hostname = @uri.host
+      ssl.sync_close = true
+      ssl.connect
+      ssl
+    end
+
+    def attach_driver_callbacks
+      @driver.on(:message) { |e| dispatch_frame(e.data) }
+      @driver.on(:close)   { |e| @on_close.call(e) }
+      @driver.on(:error)   { |e| @on_close.call(e) }
+    end
+
+    def dispatch_frame(text)
+      frame = JSON.parse(text)
+      case frame["type"]
+      when "confirm_subscription"
+        @subscribed = true
+      when "ping", "welcome"
+        # ignore
+      else
+        msg = frame["message"]
+        @on_message.call(msg) if msg
+      end
+    end
+
+    def pump_until
+      until yield
+        pump(0.05)
+      end
+    end
+  end
+end

data/lib/wokku/commands/auth.rb

@@ -1,35 +1,18 @@
 # frozen_string_literal: true
 
-# --- Auth ---
-register "auth:login", "Authenticate with Wokku" do
-  print "Wokku API URL [https://wokku.cloud/api/v1]: "
-  url = $stdin.gets.strip
-  url = "https://wokku.cloud/api/v1" if url.empty?
-
-  print "Email: "
-  email = $stdin.gets.strip
-  print "Password: "
-  password = ($stdin.respond_to?(:noecho) ? $stdin.noecho(&:gets) : $stdin.gets).strip
-  puts
-
-  uri = URI("#{url}/auth/login")
-  http = Net::HTTP.new(uri.host, uri.port)
-  http.use_ssl = uri.scheme == "https"
-  req = Net::HTTP::Post.new(uri)
-  req["Content-Type"] = "application/json"
-  req.body = { email: email, password: password }.to_json
-
-  resp = http.request(req)
-  data = JSON.parse(resp.body) rescue {}
+DEFAULT_API_URL = "https://wokku.cloud/api/v1"
 
-  if resp.is_a?(Net::HTTPSuccess) && data["token"]
-    save_config({ "api_url" => url, "token" => data["token"], "email" => email })
-    instance = url.include?("wokku.cloud") ? "wokku.cloud (managed)" : "#{URI(url).host} (self-hosted)"
-    Wokku::Output.status "Logged in as #{email}"
-    Wokku::Output.status "Connected to: #{instance}"
-  else
-    abort "Login failed: #{data['error'] || resp.code}"
+# --- Auth ---
+register "auth:login", "Authenticate with Wokku via browser device flow. Flag: --url URL (for self-hosted)" do
+  url = DEFAULT_API_URL
+  while (arg = ARGV.shift)
+    case arg
+    when "--url" then url = ARGV.shift or abort "--url requires a value"
+    else abort "Unknown argument: #{arg}"
+    end
   end
+
+  Wokku::Auth.login_with_device_flow!(url)
 end
 
 register "auth:logout", "Log out" do

data/lib/wokku/commands/shell.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "uri"
+require "wokku/cable_client"
+require "wokku/pty_session"
+
+# --- wokku enter APP ---
+register "enter", "Open an interactive shell in APP's running container (usage: wokku enter APP)" do
+  app_name = ARGV.shift or abort "Usage: wokku enter APP"
+  Wokku::Commands::Shell.run!(mode: "enter", target_kind: :app, target: app_name, argv: [], force_tty: true)
+end
+
+# --- wokku ps:exec APP -- CMD ARGS... ---
+register "ps:exec", "Run CMD in a one-off container (like `heroku run`; usage: wokku ps:exec APP [-t|-T] -- CMD [ARGS...])" do
+  force = nil
+  app_name = nil
+  argv = []
+  while (arg = ARGV.shift)
+    case arg
+    when "-t", "--tty"    then force = true
+    when "-T", "--no-tty" then force = false
+    when "--"             then argv = ARGV.shift(ARGV.length); break
+    else app_name ||= arg
+    end
+  end
+  abort "Usage: wokku ps:exec APP [-t|-T] -- CMD [ARGS...]" unless app_name && !argv.empty?
+  Wokku::Commands::Shell.run!(mode: "exec", target_kind: :app, target: app_name, argv: argv, force_tty: force)
+end
+
+# --- wokku databases:connect DB ---
+register "databases:connect", "Open an interactive client for DB (usage: wokku databases:connect DB)" do
+  db_name = ARGV.shift or abort "Usage: wokku databases:connect DB"
+  Wokku::Commands::Shell.run!(mode: "db_connect", target_kind: :database, target: db_name, argv: [], force_tty: true)
+end
+
+module Wokku
+  module Commands
+    module Shell
+      module_function
+
+      def run!(mode:, target_kind:, target:, argv:, force_tty:)
+        resource_path = target_kind == :app ? "/apps/#{target}" : "/databases/#{target}"
+        resource = api(:get, resource_path)
+        server_id = resource["server_id"] or abort "could not resolve server for #{target}"
+
+        token = Wokku::Config.api_token or abort "not logged in — run `wokku auth:login`"
+        cable_url = derive_cable_url(Wokku::Config.api_url)
+
+        cable = Wokku::CableClient.new(url: cable_url, token: token)
+        cable.subscribe(channel: "TerminalChannel", params: { server_id: server_id })
+
+        tty = force_tty.nil? ? $stdout.tty? : force_tty
+        session = Wokku::PtySession.new(cable: cable, tty: tty)
+        session.start!(mode: mode, target: target, argv: argv)
+        session.run
+        cable.close
+        exit(session.exit_code || 0)
+      end
+
+      def derive_cable_url(api_url)
+        u = URI(api_url)
+        scheme = u.scheme == "https" ? "wss" : "ws"
+        port = (u.port && ![80, 443].include?(u.port)) ? ":#{u.port}" : ""
+        "#{scheme}://#{u.host}#{port}/cable"
+      end
+    end
+  end
+end

data/lib/wokku/pty_session.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "io/console"
+require "base64"
+
+module Wokku
+  class PtySession
+    attr_reader :exit_code
+
+    def initialize(cable:, tty:)
+      @cable = cable
+      @tty = tty
+      @exit_code = nil
+      @done = false
+    end
+
+    def start!(mode:, target:, argv: [])
+      rows, cols = current_winsize
+      @cable.send_message(type: "start", mode: mode, target: target, argv: argv, cols: cols, rows: rows)
+    end
+
+    # Runs until @done is set by an "exit" or "error" message.
+    # Optional block (used in specs) is called once per pump tick and may return :stop.
+    def run
+      install_message_handler
+      install_signal_handlers if @tty
+
+      IO.console.raw! if @tty
+      begin
+        loop do
+          break if @done
+          forward_stdin if @tty
+          @cable.pump(0.05)
+          break if block_given? && yield == :stop
+        end
+      ensure
+        IO.console.cooked! if @tty
+      end
+    end
+
+    private
+
+    def install_signal_handlers
+      Signal.trap("WINCH") do
+        rows, cols = current_winsize
+        @cable.send_message(type: "resize", cols: cols, rows: rows)
+      end
+    end
+
+    def install_message_handler
+      @cable.on_message do |msg|
+        case msg["type"]
+        when "stdout"
+          $stdout.write(Base64.strict_decode64(msg["data"].to_s))
+          $stdout.flush
+        when "exit"
+          @exit_code = msg["code"].to_i
+          @done = true
+        when "error"
+          warn(msg["message"].to_s)
+          @exit_code = 1
+          @done = true
+        end
+      end
+    end
+
+    def forward_stdin
+      ready = IO.select([$stdin], nil, nil, 0)
+      return unless ready
+      data = $stdin.read_nonblock(4096)
+      @cable.send_message(type: "stdin", data: Base64.strict_encode64(data))
+    rescue IO::WaitReadable, EOFError, TypeError
+      # nothing to read (TypeError: StringIO in tests, or non-IO stdin)
+    end
+
+    def current_winsize
+      IO.console.winsize
+    rescue
+      [24, 80]
+    end
+  end
+end

data/lib/wokku/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Wokku
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/wokku.rb

@@ -11,6 +11,7 @@ require "wokku/output"
 require "wokku/api_client"
 require "wokku/registry"
 require "wokku/helpers"
+require "wokku/auth"
 
 module Wokku
   class << self

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: wokku-cli
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Johannes Dwicahyo
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: websocket-driver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
 description: Deploy and manage apps, databases, domains, and SSH keys on Wokku.cloud
   or self-hosted Wokku servers.
 email:
@@ -24,6 +38,8 @@ files:
 - exe/wokku
 - lib/wokku.rb
 - lib/wokku/api_client.rb
+- lib/wokku/auth.rb
+- lib/wokku/cable_client.rb
 - lib/wokku/commands/activity.rb
 - lib/wokku/commands/addons.rb
 - lib/wokku/commands/apps.rb
@@ -40,6 +56,7 @@ files:
 - lib/wokku/commands/releases.rb
 - lib/wokku/commands/run.rb
 - lib/wokku/commands/servers.rb
+- lib/wokku/commands/shell.rb
 - lib/wokku/commands/ssh_keys.rb
 - lib/wokku/commands/storage.rb
 - lib/wokku/commands/templates.rb
@@ -47,6 +64,7 @@ files:
 - lib/wokku/config.rb
 - lib/wokku/helpers.rb
 - lib/wokku/output.rb
+- lib/wokku/pty_session.rb
 - lib/wokku/registry.rb
 - lib/wokku/version.rb
 homepage: https://wokku.cloud