gdkbox 0.1.1 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13ef02da003147624f1bf52ef134de61acba1cb43e950b3359686d3e916a1658
-  data.tar.gz: c9b0697a87b799a54c90df07b36c112e56b4f0ad97da13ec02eac5bca7d25c38
+  metadata.gz: 851b8b309a5e04c8e48d1090e45453b0f8464779a0d1cb30aaa69e5edf0829fe
+  data.tar.gz: 01af5d8bd6d09cca936bf801f22a82ff143e4357b86ce47dc6478659d19d3f9e
 SHA512:
-  metadata.gz: 5a606c354092f3d0c16392174d68d589c87c348569defa631766eff4ca5169d1afcb3444c107aeab058186d9b5966e7ba439a1ab88e38fa62b2f4dadd233415f
-  data.tar.gz: d15ae6669f61436afd12a90b5d4cabd72fa7441e04f1b69199dbd9b8a58c8a2e39bf5d7b522f8576116e0492f539a970f9d6b589142494ffb3fcf252e91a2fac
+  metadata.gz: 9a5201a873d0f54c7864f2e746e7077ea406f12f6ffce032280579ab1241d74fd743e6a4376204d89aa73bb75f30cdb697cc9bb99e3253e5f819d9e03d0adf17
+  data.tar.gz: 569e92b7c9d527932912790e6a0e2b48be01920d5bd29cd80788673827adc17a2230fcd66f212f006b704f5e8b8b7fcee4154d0d7d502ff87e470d7b10afca31

data/README.md

@@ -1,5 +1,9 @@
 # gdkbox
 
+[![Gem Version](https://img.shields.io/gem/v/gdkbox)](https://rubygems.org/gems/gdkbox)
+[![Gem Downloads](https://img.shields.io/gem/dt/gdkbox)](https://rubygems.org/gems/gdkbox)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
 Spin up a [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit)
 "in a box" with a single command, then connect to it from **VS Code** and run
 **Claude Code** agents against a real GitLab development environment.
@@ -51,14 +55,22 @@ gdkbox ls               # list your boxes and their status
 
 ## Install
 
-From this directory:
+`gdkbox` is published on [RubyGems](https://rubygems.org/gems/gdkbox):
+
+```sh
+gem install gdkbox
+```
+
+### From source
+
+To build and install from a checkout of this repository:
 
 ```sh
 gem build gdkbox.gemspec
-gem install ./gdkbox-0.1.0.gem
+gem install ./gdkbox-*.gem
 ```
 
-Or run it straight from a checkout without installing:
+Or run it straight from the checkout without installing:
 
 ```sh
 ./bin/gdkbox up myenv
@@ -68,7 +80,8 @@ Or run it straight from a checkout without installing:
 
 | Command | Description |
 | --- | --- |
-| `gdkbox up NAME` | Pull the GDK image, start a box, enable SSH, install Claude Code, register VS Code host. |
+| `gdkbox up NAME` | Pull the GDK image (only if not already local), start a box, enable SSH, install Claude Code, register VS Code host. |
+| `gdkbox update-image` | Pull the latest GDK-in-a-box image, with a progress bar and download speed (`--image` to override). |
 | `gdkbox ls` | List boxes and their container status (`--json` for orchestrators). |
 | `gdkbox status NAME` | Show container state and connection details (`--json`). |
 | `gdkbox dispatch NAME` | Run a Claude Code agent task headlessly in the box (`--task`/`--task-file`). |

data/lib/gdkbox/box.rb

@@ -88,7 +88,10 @@ module GDKBox
       public_key = @ssh_key.ensure!
       cname = @config.container_name(name)
 
-      @docker.pull(image)
+      # Only pull when the image is missing locally, so `gdkbox up` on a warm
+      # machine does not hit the registry; `gdkbox update-image` is the
+      # explicit way to refresh.
+      @docker.pull(image) unless @docker.image_exists?(image)
 
       # Reserve the host ports atomically. `next_port` reads the store, so
       # parallel `gdkbox up` runs would otherwise all pick the same "next free"

data/lib/gdkbox/cli.rb

@@ -69,6 +69,35 @@ module GDKBox
       end
     end
 
+    desc "update-image", "Pull the latest GDK-in-a-box image"
+    long_desc <<~DESC
+      Re-pulls the GDK image so new boxes start from the latest published
+      version. The image is large, so progress is shown as a bar while it
+      downloads. Defaults to the configured image (config.yml / $GDKBOX_IMAGE)
+      or the official one; override with --image.
+
+      Existing boxes keep the image they were created with; recreate a box
+      (`gdkbox rm NAME` then `gdkbox up NAME`) to adopt the freshly pulled one.
+    DESC
+    option :image, type: :string, desc: "Override the GDK image to pull"
+    def update_image
+      ensure_docker!
+      image = options[:image] || config.default_image
+      docker = Docker.new
+
+      say "Pulling #{image} ...", :green
+      bar = ProgressBar.new
+      docker.pull(image) do |progress|
+        label = "#{progress.completed}/#{progress.total} layers"
+        label += " · #{progress.human_speed}" if progress.human_speed
+        bar.update(progress.fraction, label)
+      end
+      bar.finish
+
+      say "Updated. New boxes will use this image; recreate existing boxes to adopt it.", :green
+    end
+    map "update-image" => :update_image
+
     desc "ls", "List all GDK boxes and their status"
     option :json, type: :boolean, default: false,
       desc: "Print the fleet as a JSON array (for orchestrators)"

data/lib/gdkbox/docker.rb

@@ -15,8 +15,181 @@ module GDKBox
       !@shell.which("docker").nil?
     end
 
-    def pull(image)
-      @shell.run!("docker", "pull", image)
+    # Whether the image is already present locally.
+    def image_exists?(image)
+      @shell.run("docker", "image", "inspect", image).success?
+    end
+
+    # Pull an image. With no block the pull runs quietly and the (captured)
+    # Result is returned. With a block the pull is streamed and the block is
+    # called with a PullProgress after every line of `docker pull` output, so a
+    # caller can drive a progress bar. Raises CommandError on a non-zero exit.
+    def pull(image, &block)
+      return @shell.run!("docker", "pull", image) unless block
+
+      tracker = PullProgress.new
+      result = @shell.stream_tty("docker", "pull", image) do |line|
+        tracker.ingest(line)
+        block.call(tracker)
+      end
+      unless result.success?
+        raise CommandError.new(["docker", "pull", image], result.status, result.stderr)
+      end
+
+      result
+    end
+
+    # Parses the terminal output of `docker pull` (see Shell#stream_tty) into an
+    # overall completion fraction and a download rate. Docker repaints one line
+    # per layer, each shaped like "<layer-id>: <status> [==>   ]  5MB/50MB". We
+    # track every layer we have seen and score its progress in 0.0..1.0: a
+    # download fills the first half of a layer and extraction the second, so the
+    # fraction rises smoothly rather than jumping only when a whole layer
+    # completes. Bytes reported on "Downloading" lines are summed across layers
+    # and sampled against a clock to derive the current download speed.
+    class PullProgress
+      # States that mark a layer as fully pulled.
+      DONE = ["Pull complete", "Already exists"].freeze
+
+      # Docker repaints many times a second across parallel layers; recomputing
+      # speed on every burst line would divide a small byte delta by a
+      # near-zero time and report absurd spikes. Instead accumulate bytes and
+      # only recompute the rate once this much time has elapsed.
+      SAMPLE_INTERVAL = 0.25
+
+      # SI byte units as docker prints them (base 1000).
+      UNITS = { "B" => 1, "kB" => 1000, "MB" => 1000**2,
+                "GB" => 1000**3, "TB" => 1000**4 }.freeze
+
+      # +clock+ returns a monotonically increasing time in seconds; it is
+      # injected in tests so speed is deterministic.
+      def initialize(clock: nil)
+        @layers = {}
+        @downloaded = Hash.new(0) # layer id => bytes pulled so far
+        @sizes = {}               # layer id => total bytes (once known)
+        @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        @speed = nil              # bytes/second, or nil until measurable
+      end
+
+      def ingest(line)
+        id, status = line.split(": ", 2)
+        return unless status
+        # The first line ("<tag>: Pulling from <repo>") is not a layer.
+        return if status.start_with?("Pulling from")
+
+        track_bytes(id, status)
+        @layers[id] = score(status)
+      end
+
+      # Number of layers fully pulled so far.
+      def completed
+        @layers.count { |_id, value| value >= 1.0 }
+      end
+
+      # Number of distinct layers seen so far.
+      def total
+        @layers.size
+      end
+
+      # Overall progress in 0.0..1.0 (0.0 before any layer is known).
+      def fraction
+        return 0.0 if @layers.empty?
+
+        @layers.values.sum / @layers.size
+      end
+
+      # Current download speed in bytes/second, or nil before it can be
+      # measured (needs two samples with elapsed time and new bytes).
+      def speed
+        @speed
+      end
+
+      # Current download speed as a human string (e.g. "12.3 MB/s"), or nil.
+      def human_speed
+        return nil unless @speed && @speed.positive?
+
+        "#{human_size(@speed)}/s"
+      end
+
+      private
+
+      # Update per-layer downloaded bytes from a status line and resample speed.
+      def track_bytes(id, status)
+        if status.start_with?("Downloading")
+          current, total_size = parse_sizes(status)
+          @sizes[id] = total_size if total_size
+          record_bytes(id, current) if current
+        elsif DONE.any? { |s| status.start_with?(s) } || status.start_with?("Download complete")
+          # Finalize the layer's byte count once its download is done.
+          record_bytes(id, @sizes[id]) if @sizes[id]
+        end
+      end
+
+      # Downloaded bytes only grow, so keep the max we have seen for the layer.
+      def record_bytes(id, bytes)
+        @downloaded[id] = [@downloaded[id], bytes].max
+        sample_speed
+      end
+
+      # Recompute the rate over the bytes accumulated since the last sample,
+      # but only once at least SAMPLE_INTERVAL has passed so bursty repaints do
+      # not produce spikes. A window that gained no bytes reports 0 (a stall or
+      # the extraction phase) so a stale figure is not left on screen.
+      def sample_speed
+        now = @clock.call
+        total_bytes = @downloaded.values.sum
+        if @prev_time.nil?
+          @prev_time = now
+          @prev_bytes = total_bytes
+          return
+        end
+
+        dt = now - @prev_time
+        return if dt < SAMPLE_INTERVAL
+
+        @speed = total_bytes > @prev_bytes ? (total_bytes - @prev_bytes) / dt : 0.0
+        @prev_time = now
+        @prev_bytes = total_bytes
+      end
+
+      # The "current/total" byte figures from a "Downloading ... 5MB/50MB" line,
+      # as [current_bytes, total_bytes]; either may be nil if not present.
+      def parse_sizes(status)
+        sizes = status.scan(/([\d.]+)\s*([kMGT]?B)\b/).map do |num, unit|
+          (num.to_f * UNITS.fetch(unit, 1)).to_i
+        end
+        [sizes[0], sizes[1]]
+      end
+
+      def human_size(bytes)
+        units = UNITS.keys
+        size = bytes.to_f
+        i = 0
+        while size >= 1000 && i < units.length - 1
+          size /= 1000
+          i += 1
+        end
+        format("%.1f %s", size, units[i])
+      end
+
+      def score(status)
+        return 1.0 if DONE.any? { |s| status.start_with?(s) }
+        return 0.5 + (0.5 * ratio(status)) if status.start_with?("Extracting")
+        return 0.5 * ratio(status) if status.start_with?("Downloading")
+        return 0.5 if status.start_with?("Verifying Checksum", "Download complete")
+
+        0.0 # "Pulling fs layer", "Waiting", anything not yet started
+      end
+
+      # The fill ratio of a "[===>      ]" progress meter, or 0.0 if absent.
+      def ratio(status)
+        return 0.0 unless (m = status.match(/\[([^\]]*)\]/))
+
+        inner = m[1]
+        return 0.0 if inner.empty?
+
+        (inner.count("=") + inner.count(">")).to_f / inner.length
+      end
     end
 
     # Start a detached container, returning its id.

data/lib/gdkbox/progress_bar.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module GDKBox
+  # A single-line terminal progress bar.
+  #
+  # Rendering is only enabled on a TTY so piped or JSON output stays clean; on a
+  # non-TTY the bar is silent and the caller's regular `say` messages carry the
+  # story instead. The bar redraws in place with a carriage return until
+  # +finish+ moves the cursor to the next line.
+  class ProgressBar
+    def initialize(out: $stderr, width: 30, enabled: nil)
+      @out = out
+      @width = width
+      @enabled = enabled.nil? ? (out.respond_to?(:tty?) && out.tty?) : enabled
+    end
+
+    def enabled?
+      @enabled
+    end
+
+    # Redraw the bar at the given fraction (clamped to 0.0..1.0) with an
+    # optional trailing label (e.g. "12/40 layers").
+    def update(fraction, label = nil)
+      return unless @enabled
+
+      fraction = [[fraction.to_f, 0.0].max, 1.0].min
+      filled = (fraction * @width).round
+      bar = ("█" * filled) + ("░" * (@width - filled))
+      text = format("\r[%s] %3d%%", bar, (fraction * 100).round)
+      text += " #{label}" if label && !label.empty?
+      @out.print(text)
+      @out.flush
+    end
+
+    # Fill the bar and drop to a fresh line so later output is not overwritten.
+    def finish(label = nil)
+      return unless @enabled
+
+      update(1.0, label)
+      @out.print("\n")
+      @out.flush
+    end
+  end
+end

data/lib/gdkbox/shell.rb

@@ -48,10 +48,57 @@ module GDKBox
       run!(*args, input: input).stdout
     end
 
+    # Run a command attached to a pseudo-terminal, yielding each line of its
+    # output as it appears so callers can render live progress. A PTY is used
+    # (rather than a pipe) because some programs adapt their output to whether
+    # they are interactive: `docker pull`, for instance, only prints per-layer
+    # byte counts and progress bars when it believes it is on a terminal. ANSI
+    # escape sequences are stripped and carriage-return repaints are split into
+    # separate lines before yielding. Returns a Result with empty stdout/stderr
+    # (the output was streamed, not captured) and the child's exit status; never
+    # raises on a non-zero exit.
+    def stream_tty(*args, input: nil)
+      require "pty"
+      argv = args.map(&:to_s)
+      reader, writer, pid = PTY.spawn(*argv)
+      writer.write(input) if input
+      writer.close
+
+      buffer = +""
+      begin
+        loop do
+          buffer << reader.readpartial(4096)
+          while (idx = buffer.index(/[\r\n]/))
+            line = clean_tty(buffer.slice!(0..idx))
+            yield line if block_given? && line
+          end
+        end
+      rescue Errno::EIO, EOFError
+        # The child exited and closed its end of the PTY.
+      ensure
+        reader.close unless reader.closed?
+      end
+
+      trailing = clean_tty(buffer)
+      yield trailing if block_given? && trailing
+      _, status = Process.wait2(pid)
+      Result.new("", "", status&.exitstatus || 1)
+    end
+
     # Resolve an executable on PATH, returning its path or nil.
     def which(command)
       result = run("sh", "-c", "command -v #{command}")
       result.success? ? result.stdout.strip : nil
     end
+
+    private
+
+    # Strip ANSI escape sequences and CR/LF from a raw PTY segment, returning
+    # the trimmed text or nil when nothing meaningful remains (e.g. a bare
+    # cursor-movement escape used to repaint the display).
+    def clean_tty(raw)
+      text = raw.gsub(/\e\[[0-9;?]*[A-Za-z]/, "").tr("\r\n", "").strip
+      text.empty? ? nil : text
+    end
   end
 end

data/lib/gdkbox/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GDKBox
-  VERSION = "0.1.1"
+  VERSION = "0.1.5"
 end

data/lib/gdkbox.rb

@@ -7,6 +7,7 @@ end
 
 require "gdkbox/version"
 require "gdkbox/shell"
+require "gdkbox/progress_bar"
 require "gdkbox/config"
 require "gdkbox/docker"
 require "gdkbox/store"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gdkbox
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.5
 platform: ruby
 authors:
 - jotolo
@@ -62,6 +62,7 @@ files:
 - lib/gdkbox/config.rb
 - lib/gdkbox/docker.rb
 - lib/gdkbox/harness.rb
+- lib/gdkbox/progress_bar.rb
 - lib/gdkbox/provisioner.rb
 - lib/gdkbox/shell.rb
 - lib/gdkbox/skills.rb
@@ -71,9 +72,14 @@ files:
 - lib/gdkbox/version.rb
 - lib/gdkbox/vscode.rb
 - skills/gdkbox-fleet/SKILL.md
+homepage: https://gitlab.com/jotolo_gl/gdkbox
 licenses:
 - MIT
-metadata: {}
+metadata:
+  source_code_uri: https://gitlab.com/jotolo_gl/gdkbox
+  bug_tracker_uri: https://gitlab.com/jotolo_gl/gdkbox/-/issues
+  documentation_uri: https://gitlab.com/jotolo_gl/gdkbox/-/blob/main/README.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib