wslc-wip 0.4.1 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5808f27cf9f20fab582caacc33a35f4727d1b74764b8e541fe9f10a82ec8ceaa
-  data.tar.gz: 79c031022523b9ea21dfc79d7b160bcc46ab71cebe9f98d89050758ba581d986
+  metadata.gz: be995c6781c440a7fd84dd3c3bbbddd6799154b59694edce5aa653d80c7d6e53
+  data.tar.gz: 7fb1638a125b2bce92212e8ff525a38e31e2d8aa4386e3e74e379420d4df9c91
 SHA512:
-  metadata.gz: 4b64f0d01f0f54476b5acacc7094dc6c54f2ea5ed480272644b20839a9a1d3217d9c32748935eb20d75f5ee3672012d6c8799dfba8192b1fa656e16a7c65380f
-  data.tar.gz: 5ab533ffee65252d885c20862c32450f3d4b7c5c4a8019cf2314e5075b9c3f5ea49efd551f08cf73c170663b90cebe420533be7041e5d20c6eff1988e6b3a758
+  metadata.gz: 539721780baa7f366f215581629a761c85e396823e05ff08a3da97c2d0de7808d1470c959240867a5a0ab762f4441ea8b2cb22c92f0063712a18c6b0f80dc4fe
+  data.tar.gz: fc00ceceeeb01cd63ac931ff2ffeea1f64848f38a1222b60b8c5de7a501e914a3820d61abbd7d437ebd412e2046958223edab7b46d582b5cb6ef693badf5cc3e

data/README.md

@@ -5,6 +5,8 @@
 [![License: MIT](https://img.shields.io/github/license/slidict/wip.svg)](LICENSE)
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-red.svg)](wslc-wip.gemspec)
 
+Homepage: https://wslc-wip.slidict.com/
+
 `wip` is a Ruby-built OSS CLI wrapper that brings a [`dip`](https://github.com/bibendi/dip)-like
 workflow to Microsoft WSLC. It collects a project's container, image, environment variables, and
 commands into a single `wip.yml`, and forwards them to `wslc.exe` / `wslc` as safe argument arrays
@@ -127,8 +129,48 @@ dependencies down (the network itself is left in place). Each dependency entry a
 | `wip NAME ARGS...` | Run `commands.NAME`, appending any extra arguments |
 
 TTY allocation is decided by combining the command's config, the CLI option, and whether both
-stdin and stdout are real TTYs. Set `WIP_DEBUG=1` to print the `Shellwords`-joined command before
-running it.
+stdin and stdout are real TTYs.
+
+Pass `--debug` (or set `WIP_DEBUG=1`) to see where time is going: wip prints each step it takes —
+checking for an existing network/container/dependency, and running the resolved `wslc`/`docker`
+command — along with how long that step took, e.g.:
+
+```console
+$ wip rails c --debug
+wip: [debug] running: wslc.exe exec -it -w /app app bin/rails c
++ wslc.exe exec -it -w /app app bin/rails c
+...
+wip: [debug] done in 4.32s: running: wslc.exe exec -it -w /app app bin/rails c
+```
+
+For long-running interactive commands (like `rails c`), the "done" line only prints after you
+exit, but the timestamp of the `+ ...` line tells you when wip finished its own setup and handed
+off to `wslc`/`docker` — useful for telling wip-side overhead apart from time spent booting inside
+the container.
+
+While a step is still running, wip also prints a host resource snapshot (load average, memory,
+disk I/O, and the top CPU-consuming processes) every 5 seconds, so a hang is visible even before
+the command has produced any output of its own:
+
+```console
+wip: [debug] still running (load 3.42 2.10 1.05 | mem 6.1G/15.6G | io read 12000KB/s write 400KB/s | top: wslc.exe(8842) cpu 61.0%/mem 3.2%, ...): running: wslc.exe exec -it -w /app app bin/rails c
+```
+
+The disk I/O figure is worth watching first if the host's CPU and memory look idle — a slow
+`bundle`/`rails` boot is often WSL2's bind-mounted (`.:/app`-style) volumes doing a lot of small
+reads, not the container starving for CPU.
+
+For commands that hand the real terminal to the child (`-it`, e.g. `rails c`), these periodic
+snapshots go to a log file instead of your terminal — wip prints the path once at the start —
+since writing into a terminal the child controls in raw mode would garble both outputs. Commands
+that don't need a TTY still get the snapshots printed live.
+
+Override that choice with `--debug-log`:
+
+- `--debug-log=-` forces snapshots inline even for `-it` commands (only useful if you know your
+  terminal/pager can tolerate the interleaving).
+- `--debug-log=PATH` always writes snapshots to `PATH`, including for non-TTY commands, e.g. to
+  keep every run's snapshots in one place: `wip rails c --debug --debug-log=/tmp/wip-debug.log`.
 
 ## doctor
 

data/lib/wip/cli.rb

@@ -9,6 +9,8 @@ module Wip
   # Thor-based command-line interface for wip.
   class CLI < Thor
     class_option :config, type: :string, desc: 'Path to wip.yml'
+    class_option :debug, type: :boolean, default: false, desc: 'Print progress and timing for each step'
+    class_option :debug_log, type: :string, desc: 'Where --debug snapshots go: a file path, or "-" for inline'
     default_task :dispatch
 
     def self.exit_on_failure? = true
@@ -119,19 +121,31 @@ module Wip
     def builder = CommandBuilder.new(wslc: resolver.resolve(load_config.wslc_command), config: load_config)
 
     def execute(command, interactive: false, exit_on_failure: true)
-      code = CommandRunner.new.run(command, interactive: interactive)
+      runner = CommandRunner.new(debug: debug?)
+      code = reporter.step("running: #{CommandDisplay.for_debug(command)}", live: !interactive) do
+        runner.run(command, interactive: interactive)
+      end
       exit(code) if exit_on_failure && !code.zero?
       code
     end
 
     def resource_exists?(find_command)
-      out = StringIO.new
-      code = CommandRunner.new(stdout: out, stderr: StringIO.new).run(find_command)
-      code.zero? && !JSON.parse(out.string).empty?
+      code, output = probe(find_command)
+      code.zero? && !JSON.parse(output).empty?
     rescue JSON::ParserError
       false
     end
 
+    def probe(command)
+      out = StringIO.new
+      runner = CommandRunner.new(stdout: out, stderr: StringIO.new, debug: debug?)
+      code = reporter.step("checking: #{CommandDisplay.for_debug(command)}") { runner.run(command) }
+      [code, out.string]
+    end
+
+    def debug? = options[:debug] || !ENV['WIP_DEBUG'].to_s.empty?
+    def reporter = @reporter ||= DebugReporter.new(enabled: debug?, log: options[:debug_log])
+
     def ensure_network
       network = load_config.network
       return unless network
@@ -142,11 +156,8 @@ module Wip
     end
 
     def network_exists?(network)
-      out = StringIO.new
-      code = CommandRunner.new(stdout: out, stderr: StringIO.new).run(builder.network_list)
-      return false unless code.zero?
-
-      JSON.parse(out.string).any? { |entry| entry['Name'] == network }
+      code, output = probe(builder.network_list)
+      code.zero? && JSON.parse(output).any? { |entry| entry['Name'] == network }
     rescue JSON::ParserError
       false
     end

data/lib/wip/command_display.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module Wip
+  # Renders a command array for debug output, masking `-e KEY=value` env values
+  # so secrets from wip.yml never reach logs.
+  module CommandDisplay
+    def self.for_debug(command)
+      masked = command.each_cons(2).with_index.each_with_object(command.dup) do |((flag, pair), index), result|
+        next unless flag == '-e'
+
+        key, = pair.split('=', 2)
+        result[index + 1] = "#{key}=***"
+      end
+      Shellwords.join(masked)
+    end
+  end
+end

data/lib/wip/command_runner.rb

@@ -1,20 +1,21 @@
 # frozen_string_literal: true
 
 require 'open3'
-require 'shellwords'
 
 module Wip
   # Executes a built command, pumping its I/O and returning the exit status.
   class CommandRunner
-    def initialize(stdin: $stdin, stdout: $stdout, stderr: $stderr, interpreter: ErrorInterpreter.new)
+    def initialize(stdin: $stdin, stdout: $stdout, stderr: $stderr, interpreter: ErrorInterpreter.new,
+                   debug: !ENV['WIP_DEBUG'].to_s.empty?)
       @stdin = stdin
       @stdout = stdout
       @stderr = stderr
       @interpreter = interpreter
+      @debug = debug
     end
 
     def run(command, env: {}, interactive: false)
-      @stderr.puts "+ #{Shellwords.join(command)}" if ENV['WIP_DEBUG']
+      @stderr.puts "+ #{CommandDisplay.for_debug(command)}" if @debug
       return run_attached(command, env) if interactive
 
       captured = +''

data/lib/wip/debug_reporter.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+
+module Wip
+  # Prints each step wip takes and how long it took, when debug mode is enabled.
+  class DebugReporter
+    # `log:` overrides where resource snapshots go, regardless of `live`:
+    #   nil  - automatic (see `step`'s `live:`)
+    #   '-'  - always print inline, even for interactive steps
+    #   path - always write to this file, even for non-interactive steps
+    def initialize(enabled:, out: $stderr, log: nil)
+      @enabled = enabled
+      @out = out
+      @log = log
+    end
+
+    # `live: false` is for steps that hand the real TTY to the child process
+    # (e.g. `wslc exec -it`). The child owns raw-mode cursor control there, so
+    # writing periodic snapshots straight into that same terminal races with
+    # it and garbles the output; those snapshots go to a log file instead,
+    # unless overridden by `log:` in the constructor.
+    def step(label, live: true)
+      return yield unless @enabled
+
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @out.puts "wip: [debug] #{label}"
+      file = log_file(live)
+      monitor = ResourceMonitor.new(out: file || @out)
+      monitor.start(label)
+      begin
+        yield
+      ensure
+        monitor.stop
+        file&.close
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+        @out.puts format('wip: [debug] done in %<elapsed>.2fs: %<label>s', elapsed: elapsed, label: label)
+      end
+    end
+
+    private
+
+    def log_file(live)
+      return nil if @log == '-'
+      return open_log(@log, "streaming resource snapshots to #{@log}") if @log
+      return nil if live
+
+      path = File.join(Dir.tmpdir, "wip-debug-#{Process.pid}-#{Time.now.to_i}.log")
+      open_log(path, "command owns the terminal; streaming resource snapshots to #{path}")
+    end
+
+    def open_log(path, notice)
+      @out.puts "wip: [debug] #{notice}"
+      file = File.open(path, 'a') # rubocop:disable Style/FileOpen -- closed by `step`'s ensure block
+      file.sync = true
+      file
+    end
+  end
+end

data/lib/wip/resource_monitor.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Wip
+  # Periodically prints host CPU/memory/disk-IO/process info while a debug step
+  # is still running, so a hung or slow step is visible even before it produces
+  # output of its own.
+  class ResourceMonitor
+    def initialize(interval: 5, out: $stderr)
+      @interval = interval
+      @out = out
+      @last_disk = disk_sectors
+      @last_sampled_at = monotonic
+    end
+
+    def start(label)
+      @thread = Thread.new do
+        loop do
+          sleep @interval
+          @out.puts "wip: [debug] still running (#{snapshot}): #{label}"
+        end
+      end
+    end
+
+    def stop
+      @thread&.kill
+      @thread&.join
+    end
+
+    private
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    def snapshot
+      [load_average, memory, disk_io, top_processes].join(' | ')
+    end
+
+    def load_average
+      "load #{File.read('/proc/loadavg').split[0..2].join(' ')}"
+    rescue Errno::ENOENT, IOError
+      'load n/a'
+    end
+
+    def memory
+      fields = File.read('/proc/meminfo').lines.to_h { |line| line.split(':', 2).then { |k, v| [k, v.to_i] } }
+      total_gb = fields.fetch('MemTotal', 0) / 1_048_576.0
+      used_gb = total_gb - (fields.fetch('MemAvailable', 0) / 1_048_576.0)
+      format('mem %<used>.1fG/%<total>.1fG', used: used_gb, total: total_gb)
+    rescue Errno::ENOENT, IOError
+      'mem n/a'
+    end
+
+    # WSL2's bind-mounted (9p) volumes are often the real bottleneck behind a
+    # slow `bundle`/`rails` boot, and that shows up here rather than in CPU.
+    def disk_io
+      now = monotonic
+      elapsed = [now - @last_sampled_at, 0.001].max
+      current = disk_sectors
+      read_kbps = (current[:read] - @last_disk[:read]) * 0.5 / elapsed
+      write_kbps = (current[:write] - @last_disk[:write]) * 0.5 / elapsed
+      @last_disk = current
+      @last_sampled_at = now
+      format('io read %<read>.0fKB/s write %<write>.0fKB/s', read: read_kbps, write: write_kbps)
+    rescue Errno::ENOENT, IOError
+      'io n/a'
+    end
+
+    def disk_sectors
+      totals = { read: 0, write: 0 }
+      File.readlines('/proc/diskstats').each do |line|
+        fields = line.split
+        next if fields[2].to_s.match?(/\A(loop|ram)/)
+
+        totals[:read] += fields[5].to_i
+        totals[:write] += fields[9].to_i
+      end
+      totals
+    rescue Errno::ENOENT, IOError
+      { read: 0, write: 0 }
+    end
+
+    def top_processes
+      lines = `ps -eo pid,pcpu,pmem,comm --sort=-pcpu 2>/dev/null`.lines.drop(1).first(3)
+      entries = lines.filter_map do |line|
+        pid, cpu, mem, comm = line.split(nil, 4)
+        next unless comm
+
+        "#{comm.strip}(#{pid}) cpu #{cpu}%/mem #{mem}%"
+      end
+      "top: #{entries.join(', ')}"
+    rescue StandardError
+      'top: n/a'
+    end
+  end
+end

data/lib/wip/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Wip
-  VERSION = '0.4.1'
+  VERSION = '0.4.3'
 end

data/lib/wip.rb

@@ -8,6 +8,9 @@ require_relative 'wip/environment'
 require_relative 'wip/command_resolver'
 require_relative 'wip/error_interpreter'
 require_relative 'wip/command_builder'
+require_relative 'wip/command_display'
 require_relative 'wip/command_runner'
+require_relative 'wip/resource_monitor'
+require_relative 'wip/debug_reporter'
 require_relative 'wip/doctor'
 require_relative 'wip/cli'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wslc-wip
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.3
 platform: ruby
 authors:
 - Wip contributors
@@ -35,20 +35,24 @@ files:
 - lib/wip.rb
 - lib/wip/cli.rb
 - lib/wip/command_builder.rb
+- lib/wip/command_display.rb
 - lib/wip/command_resolver.rb
 - lib/wip/command_runner.rb
 - lib/wip/config.rb
 - lib/wip/config_loader.rb
+- lib/wip/debug_reporter.rb
 - lib/wip/doctor.rb
 - lib/wip/environment.rb
 - lib/wip/error_interpreter.rb
 - lib/wip/errors.rb
+- lib/wip/resource_monitor.rb
 - lib/wip/version.rb
-homepage: https://github.com/slidict/wip
+homepage: https://wslc-wip.slidict.com/
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+  homepage_uri: https://wslc-wip.slidict.com/
   source_code_uri: https://github.com/slidict/wip
   changelog_uri: https://github.com/slidict/wip/releases
   bug_tracker_uri: https://github.com/slidict/wip/issues