wokku-cli 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d6db99db4bf59f5b55f619cbd6abb12fc6b3f711fba103b327e6d0b01479114
-  data.tar.gz: 0b10a6ea71101885f3929f7f6055705b6a0d98ebcb2a21147070911c0522b24a
+  metadata.gz: 820e03562fff67b93f087227eb2da57e79e761c43ac5c108680699ce068a480e
+  data.tar.gz: '077218e9886faadb334a615e225a3f61802688f29f6e9ac53625ca4f505f632d'
 SHA512:
-  metadata.gz: 8b3e284c92712469309c2a3aab4fffa60e26b89727f8bf948e1bfaba87e70b572eca298ec69ee1449d6112656d478294c825f1d826b0a7f9d2f7a02b57820085
-  data.tar.gz: e3f998fd1ec992942da0319c4838cf664dbbda1ef49cb9a777a35da0acc3d1a29ec0486df464f5b45bd3d9cc3eb431098e23b7bb047462d1fc6a27d90f26772d
+  metadata.gz: 9518d6c33f111278305093a0d55f925772fe3363f4abe95df3d32b83e105d03f3e0bd2001add8f696c717d5e89352926fec2c1220fe7cb74baebc523a8c6812d
+  data.tar.gz: 1326795840aae9837bb480a821e466ce8c64e90a0fc5ed2f01c8929b7adb16da27760aa7d3c459fc65cf60afd18ac5de006be0e790d639af8eb6e09296ae9dcd

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 0.4.0 — 2026-06-01
+
+MCP commands — wire the wokku-plugin Claude Code MCP server with one command. Pairs with wokku-cloud canonical backlog 1.3.
+
+### Added
+
+- `wokku mcp:install` — registers the Wokku MCP server in Claude Code using the active CLI token + API URL.
+- `wokku mcp:switch` — re-pushes the current CLI token to the MCP config (after `auth:login` swapped accounts).
+- `wokku mcp:logout` — removes the Wokku MCP server from Claude Code.
+
+Shells out to `claude mcp add / remove` so we don't depend on Claude Code's internal config-file layout (it changes between versions). Aborts with a clear "install Claude Code first" error if the `claude` CLI isn't on PATH.
+
+## 0.3.0 — 2026-05-31
+
+Bundle v2 — boxes, shared addons (user-pick per box), and dedicated upgrades for PostgreSQL / MySQL / MongoDB / Redis. Pairs with wokku-cloud Phase 7 prep PRs #67–#73.
+
+### Added
+- `apps:create` gains `--box-size SIZE` (sleeping/small/medium/large/xlarge), `--shared pg,redis,...` (comma-separated shared engines to attach), `--dedicated-db postgres|mysql|mongodb`, `--dedicated-redis`. All optional — omitting them keeps the old free-tier default.
+- `addons:shared:enable APP ENGINE` — attach a shared engine (Pg/Redis/Memcached/RabbitMQ/Meilisearch). Free plan limited to Pg+Redis.
+- `addons:shared:disable APP ENGINE` — detach a shared engine + destroy its tenant data.
+- `addons:dedicated:upgrade APP ENGINE` — upgrade to a dedicated container. Pg/Redis migrate from shared (data preserved). MySQL/MongoDB are fresh-create. Quota: 3 per plan; size follows the box size.
+- `addons` listing now shows `kind: shared|dedicated` per row.
+
+### Deprecated
+- `addons:add` — kept for back-compat with wokku-cloud servers that haven't flipped `BUNDLE_V2_ENABLED=true` yet. When the server has bundle v2 on, this endpoint returns 410 Gone with guidance to use the new commands above.
+
+### Requires
+- wokku-cloud server-side support shipped 2026-05-31 (Phase 7 prep PRs #67–#73).
+
+## 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/README.md

@@ -1,6 +1,8 @@
 # wokku-cli
 
-CLI for [Wokku](https://wokku.cloud) — deploy and manage apps, databases, domains, and SSH keys on Wokku.cloud or self-hosted Wokku servers.
+CLI for [Wokku Cloud](https://wokku.cloud) — deploy and manage apps, databases, domains, and SSH keys.
+
+> **Wokku Cloud only.** This CLI talks to the Wokku REST API, which ships only with the managed Wokku Cloud product. The open-source Wokku web UI ([github.com/johannesdwicahyo/wokku](https://github.com/johannesdwicahyo/wokku)) does not expose `/api/v1`, so the CLI cannot point at a self-hosted Wokku install. Self-host users should use the web UI directly, or `ssh dokku@your-host` for command-line operations.
 
 ## Install
 
@@ -26,22 +28,47 @@ wokku logs myapp -f
 
 ## Commands
 
-Run `wokku --help` for the full list. Highlights:
+Run `wokku --help` for the full list. ~39 first-class commands today, grouped:
 
-- **Apps:** `apps`, `apps:create`, `apps:destroy`, `apps:info`
-- **Process:** `ps:start/stop/restart/scale/rebuild`, `redeploy`
+- **Apps:** `apps`, `apps:create`, `apps:destroy`, `apps:info`, `apps:transfer`
+- **Process:** `ps`, `ps:start/stop/restart/scale/rebuild`, `redeploy`
 - **Config:** `config`, `config:set`, `config:get`, `config:unset`, `config:export`
-- **Domains:** `domains`, `domains:add/remove/clear`, `certs:enable`
-- **Databases:** `databases`, `databases:create/destroy/link/unlink/info`
+- **Domains + SSL:** `domains`, `domains:add/remove/clear`, `certs:enable`, `certs:disable`
+- **Databases:** `databases`, `databases:create/destroy/link/unlink/info`, `backups`, `backups:create/restore`
 - **SSH keys:** `ssh-keys`, `ssh-keys:add/remove`
-- **Servers:** `servers`, `servers:info`, `servers:default`
-- **Logs:** `wokku logs APP --follow`
-- **Run / passthrough:** `wokku run APP -- COMMAND`, `wokku do APP -- DOKKU_ARGS`
+- **Servers:** `servers`, `servers:info`, `servers:default` (multi-Dokku-host installs)
+- **Teams:** `teams`, `teams:members`, `teams:invite`, `teams:remove`
+- **Logs:** `wokku logs APP --follow [--tail N]`
+- **Run / passthrough:** `wokku run APP -- COMMAND` (one-off in a fresh container), `wokku do APP -- DOKKU_ARGS` (arbitrary `dokku` CLI passthrough)
+
+### Parity with Dokku
+
+`wokku do` is the bridge for the ~110 Dokku subcommands not yet first-classed here. Anything `dokku <something> APP` does, `wokku do APP -- <something>` does too — same exit code, same stdout.
+
+If you find yourself running the same `wokku do` invocation repeatedly, open an issue — that's the queue for promoting commands to first-class status.
 
 ## Global flags
 
-- `--json` — machine-readable JSON output (read commands)
+- `--json` — machine-readable JSON output (read commands only)
 - `--quiet` / `-q` — suppress success messages and hints
+- `--server NAME` — target a specific Dokku host on multi-server installs (default: your account's primary)
+
+## Configuration
+
+Set once and forget:
+
+```sh
+export WOKKU_API_TOKEN=...   # from wokku.cloud/dashboard/profile
+```
+
+`WOKKU_API_URL` defaults to `https://wokku.cloud/api/v1` and shouldn't need to change.
+
+## What's New in v0.2.0 (May 2026)
+
+- `apps:transfer` for moving an app between teams
+- `--quiet` flag now also suppresses progress bars (not just success lines) — friendlier in scripts
+- `wokku do` exit codes pass through correctly when wrapped in pipelines (was previously masked to 0)
+- Multi-server defaults — `wokku servers:default` persists per-account, not per-shell
 
 ## License
 

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/addons.rb

@@ -6,18 +6,25 @@ register "addons", "List add-ons (usage: wokku addons APP)" do
   data = api(:get, "/apps/#{id}/addons")
   Wokku::Output.render(data) do |d|
     if d.is_a?(Array)
-      table(d.map { |a| { "name" => a["name"], "type" => a["service_type"], "status" => a["status"] } })
+      table(d.map { |a|
+        {
+          "name"   => a["name"],
+          "type"   => a["service_type"],
+          "kind"   => a["shared"] ? "shared" : "dedicated",
+          "status" => a["status"]
+        }
+      })
     else
       puts_json d
     end
   end
 end
 
-register "addons:add", "Add add-on (usage: wokku addons:add APP postgres)" do
+register "addons:add", "[LEGACY pre-Bundle-v2] Add add-on (usage: wokku addons:add APP postgres). Returns 410 under Bundle v2 — use addons:shared:enable or addons:dedicated:upgrade instead." do
   id = ARGV.shift || abort("Usage: wokku addons:add APP SERVICE_TYPE")
   service_type = ARGV.shift || abort("Missing service type (postgres, redis, mysql, etc)")
   name = nil
-  while arg = ARGV.shift
+  while (arg = ARGV.shift)
     name = ARGV.shift if arg == "--name"
   end
   body = { service_type: service_type }
@@ -25,3 +32,31 @@ register "addons:add", "Add add-on (usage: wokku addons:add APP postgres)" do
   data = api(:post, "/apps/#{id}/addons", body)
   Wokku::Output.status "Added #{service_type}: #{data['name'] || data['id']}"
 end
+
+# --- Bundle v2 — shared engines ---
+# User-pick at box creation OR via these commands later. Free plan limited
+# to postgres + redis; other plans get all 5 (memcached, rabbitmq, meilisearch
+# also available).
+register "addons:shared:enable", "Enable a shared engine on an app (usage: wokku addons:shared:enable APP ENGINE). ENGINE: postgres|redis|memcached|rabbitmq|meilisearch" do
+  id     = ARGV.shift || abort("Usage: wokku addons:shared:enable APP ENGINE")
+  engine = ARGV.shift || abort("Missing engine")
+  data   = api(:post, "/apps/#{id}/addons/shared", { engine: engine })
+  Wokku::Output.status(data["message"] || "Enabled shared #{engine} on #{id}")
+end
+
+register "addons:shared:disable", "Disable a shared engine on an app (usage: wokku addons:shared:disable APP ENGINE)" do
+  id     = ARGV.shift || abort("Usage: wokku addons:shared:disable APP ENGINE")
+  engine = ARGV.shift || abort("Missing engine")
+  data   = api(:delete, "/apps/#{id}/addons/shared/#{engine}")
+  Wokku::Output.status(data["message"] || "Disabled shared #{engine} on #{id}")
+end
+
+# --- Bundle v2 — dedicated upgrade ---
+# Pg/Redis migrate from shared (existing data preserved). MySQL/MongoDB
+# are fresh-create. Quota: 3 per plan, size follows the box size.
+register "addons:dedicated:upgrade", "Upgrade a box to a dedicated DB or Redis (usage: wokku addons:dedicated:upgrade APP ENGINE). ENGINE: postgres|mysql|mongodb|redis" do
+  id     = ARGV.shift || abort("Usage: wokku addons:dedicated:upgrade APP ENGINE")
+  engine = ARGV.shift || abort("Missing engine (postgres|mysql|mongodb|redis)")
+  data   = api(:post, "/apps/#{id}/addons/dedicated", { engine: engine })
+  Wokku::Output.status(data["message"] || "Dedicated #{engine} upgrade queued for #{id}")
+end

data/lib/wokku/commands/apps.rb

@@ -14,19 +14,33 @@ register "apps:info", "Show app details (usage: wokku apps:info APP)" do
   Wokku::Output.render(data) { |d| puts_json d }
 end
 
-register "apps:create", "Create app (usage: wokku apps:create NAME [--server SERVER] [--branch BRANCH])" do
+register "apps:create", "Create app (usage: wokku apps:create NAME [--server SERVER] [--branch BRANCH] [--box-size SIZE] [--shared pg,redis,...] [--dedicated-db postgres|mysql|mongodb] [--dedicated-redis])" do
   name = ARGV.shift || abort("Usage: wokku apps:create NAME [--server SERVER]")
   server = nil
   branch = "main"
-  while arg = ARGV.shift
+  box_size = nil
+  shared = nil
+  dedicated_db = nil
+  dedicated_redis = false
+  while (arg = ARGV.shift)
     case arg
-    when "--server" then server = ARGV.shift
-    when "--branch" then branch = ARGV.shift
+    when "--server"           then server = ARGV.shift
+    when "--branch"           then branch = ARGV.shift
+    when "--box-size"         then box_size = ARGV.shift
+    when "--shared"           then shared = ARGV.shift  # comma-separated engine names
+    when "--dedicated-db"     then dedicated_db = ARGV.shift
+    when "--dedicated-redis"  then dedicated_redis = true
     end
   end
   server = resolve_server(explicit: server)
-  data = api(:post, "/apps", { name: name, server_id: server, deploy_branch: branch })
+  body = { name: name, server_id: server, deploy_branch: branch }
+  body[:box_size] = box_size if box_size
+  body[:enabled_shared_engines] = shared.split(",").map(&:strip) if shared
+  body[:dedicated_db_engine] = dedicated_db if dedicated_db
+  body[:add_dedicated_redis] = true if dedicated_redis
+  data = api(:post, "/apps", body)
   Wokku::Output.status "Created app: #{data['name']} (id: #{data['id']})"
+  Array(data["warnings"]).each { |w| Wokku::Output.warn(w) }
 end
 
 register "apps:destroy", "Delete app (usage: wokku apps:destroy APP)" do

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/mcp.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# Wokku MCP commands — install / switch / logout the Wokku MCP server
+# in Claude Code so the user's CLI token gets passed to the plugin.
+# Shells out to `claude mcp` (Claude Code CLI) so we don't need to know
+# Claude Code's exact config-file layout — it changes between versions.
+
+MCP_SERVER_NAME = "wokku"
+
+def claude_cli_available?
+  system("command -v claude >/dev/null 2>&1")
+end
+
+def require_claude_cli!
+  return if claude_cli_available?
+  abort <<~MSG
+    The `claude` CLI is not installed.
+    Wokku MCP commands shell out to it to write your Claude Code config.
+
+    Install Claude Code (https://claude.com/claude-code) and retry.
+  MSG
+end
+
+def require_logged_in!
+  return if Wokku::Config.api_token
+  abort "Not logged in. Run: wokku auth:login"
+end
+
+def install_mcp_entry!
+  url   = Wokku::Config.api_url
+  token = Wokku::Config.api_token
+
+  # Idempotent — silently no-ops if the entry doesn't exist yet.
+  system("claude mcp remove #{Shellwords.escape(MCP_SERVER_NAME)} > /dev/null 2>&1")
+
+  ok = system(
+    "claude", "mcp", "add", MCP_SERVER_NAME,
+    "--env", "WOKKU_API_URL=#{url}",
+    "--env", "WOKKU_API_TOKEN=#{token}",
+    "--", "npx", "-y", "@johannesdwicahyo/wokku-plugin"
+  )
+  ok or abort "claude mcp add failed — check `claude mcp list` and retry."
+end
+
+register "mcp:install", "Add the Wokku MCP server to Claude Code with your CLI token" do
+  require_claude_cli!
+  require_logged_in!
+  require "shellwords"
+
+  install_mcp_entry!
+  Wokku::Output.status "MCP server '#{MCP_SERVER_NAME}' installed in Claude Code."
+  Wokku::Output.status "Restart Claude Code, then ask: \"Deploy this project to Wokku\""
+end
+
+register "mcp:switch", "Re-push the current CLI token to the Wokku MCP server (after auth:login)" do
+  require_claude_cli!
+  require_logged_in!
+  require "shellwords"
+
+  install_mcp_entry!
+  Wokku::Output.status "MCP server '#{MCP_SERVER_NAME}' now points at the current CLI session."
+  Wokku::Output.status "Restart Claude Code for the new token to take effect."
+end
+
+register "mcp:logout", "Remove the Wokku MCP server from Claude Code" do
+  require_claude_cli!
+  require "shellwords"
+
+  ok = system("claude", "mcp", "remove", MCP_SERVER_NAME)
+  if ok
+    Wokku::Output.status "MCP server '#{MCP_SERVER_NAME}' removed from Claude Code."
+  else
+    Wokku::Output.status "No MCP entry named '#{MCP_SERVER_NAME}' to remove."
+  end
+end

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/output.rb

@@ -39,5 +39,14 @@ module Wokku
       return if Wokku.quiet? || Wokku.json?
       puts message
     end
+
+    # Non-fatal warning (e.g. partial-success cases like "app created
+    # but the dedicated DB upgrade failed to enqueue"). Stderr so it
+    # doesn't pollute pipeable stdout; visible even with --quiet but
+    # silenced under --json (the JSON response carries the warning).
+    def warn(message)
+      return if Wokku.json?
+      $stderr.puts "WARNING: #{message}"
+    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.4.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.4.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
@@ -36,10 +52,12 @@ files:
 - lib/wokku/commands/do.rb
 - lib/wokku/commands/domains.rb
 - lib/wokku/commands/logs.rb
+- lib/wokku/commands/mcp.rb
 - lib/wokku/commands/ps.rb
 - 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 +65,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