process-metrics 0.10.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 213edfd5fbe960b9a75ac7574f17828f6b9f24ec5328ebf8c6ee85dcafeae0c2
-  data.tar.gz: 8daf591b9691f058dbe87dd861c0d8ff2e2669edff94b098ad0de36440963b14
+  metadata.gz: 06e77d37339d28a6405332440e7049065b61defd68fb69c9b1e794f79aba8ac7
+  data.tar.gz: 6ac90b5a274be90958fb497fe2859807b21700dbd5a7a336278b5c7b2858e2d0
 SHA512:
-  metadata.gz: 7cfafb180bf9286f5eb35dd2d5393b77ca88fc86f8b93509aed2f30870255dbba5e617ceceb69c17607bc3e620b7599e8c11ab960323033a97087a2acc45340c
-  data.tar.gz: 78427458c5dd06674690a1fe3ffab4d1c85a6ce265defce5dc2191be874ee995c87299c86de9b83e88e84318425ca2b16361e69df4b9d26d4badca1dbb8078e7
+  metadata.gz: 04a5adc405715e2406a8601a58a65885f9026d0c5009822e23eb4c739e727265787eb5ed32218c1316f75a50eba4ac6e3dc6518176d539028bf00a18f9ccbbb9
+  data.tar.gz: dd436625c1ee3a6b3a8cb6424fb05ad35e5243adc961477632acd3ab9e006cd54435c7b662cc2698b06b6e5f4a61c4082c6957d67cb84306ae62d9f075f743c2

data/lib/process/metrics/host/memory/darwin.rb

@@ -38,7 +38,7 @@ module Process
 					used = [total - free, 0].max
 					swap_total, swap_used = capture_swap
 					
-					return Host::Memory.new(total, used, free, swap_total, swap_used)
+					return Host::Memory.new(total, used, swap_total, swap_used, nil)
 				end
 				
 				# Total physical RAM in bytes, from sysctl hw.memsize.

data/lib/process/metrics/host/memory/linux/cgroup_v1.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
+module Process
+	module Metrics
+		module Host
+			class Memory::Linux::CgroupV1
+				CGROUP_V1_UNLIMITED_THRESHOLD = 2**60
+				DEFAULT_CGROUP_ROOT = "/sys/fs/cgroup"
+				
+				def self.supported?(cgroup_root = DEFAULT_CGROUP_ROOT)
+					root = (cgroup_root || DEFAULT_CGROUP_ROOT).to_s.chomp("/")
+					
+					if File.exist?("#{root}/memory/memory.limit_in_bytes") && File.exist?("#{root}/memory/memory.usage_in_bytes")
+						return true
+					end
+					
+					return false
+				end
+				
+				def initialize(cgroup_root: nil)
+					@cgroup_root = (cgroup_root || DEFAULT_CGROUP_ROOT).to_s.chomp("/")
+				end
+				
+				def capture
+					total = read_total
+					return nil unless total && total.positive?
+					
+					used = read_used
+					return nil unless used
+					used = 0 if used.negative?
+					used = [used, total].min
+					
+					swap_total, swap_used = read_swap
+					reclaimable = read_reclaimable
+					
+					return Host::Memory.new(total, used, swap_total, swap_used, reclaimable)
+				end
+				
+				private
+				
+				def path(name)
+					"#{@cgroup_root}/memory/#{name}"
+				end
+				
+				def read_total
+					limit = File.read(path("memory.limit_in_bytes")).strip.to_i
+					
+					if limit <= 0 || limit >= CGROUP_V1_UNLIMITED_THRESHOLD
+						return nil
+					end
+					
+					return limit
+				end
+				
+				def read_used
+					File.read(path("memory.usage_in_bytes")).strip.to_i
+				end
+				
+				def read_reclaimable
+					unless content = (File.read(path("memory.stat")) rescue nil)
+						return nil
+					end
+					
+					match = content.match(/^cache\s+(\d+)/m)
+					
+					return match ? match[1].to_i : nil
+				end
+				
+				def read_swap
+					unless content = (File.read("/proc/meminfo") rescue nil)
+						return [nil, nil]
+					end
+					
+					swap_total_kb = content[/SwapTotal:\s*(\d+)\s*kB/, 1]&.to_i
+					swap_free_kb = content[/SwapFree:\s*(\d+)\s*kB/, 1]&.to_i
+					
+					unless swap_total_kb
+						return [nil, nil]
+					end
+					
+					swap_total = swap_total_kb * 1024
+					swap_used = (swap_total_kb - (swap_free_kb || 0)) * 1024
+					return swap_total, swap_used
+				end
+			end
+		end
+	end
+end

data/lib/process/metrics/host/memory/linux/cgroup_v2.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
+module Process
+	module Metrics
+		module Host
+			class Memory::Linux::CgroupV2
+				DEFAULT_CGROUP_ROOT = "/sys/fs/cgroup"
+				
+				def self.supported?(cgroup_root = DEFAULT_CGROUP_ROOT)
+					root = (cgroup_root || DEFAULT_CGROUP_ROOT).to_s.chomp("/")
+					
+					if File.exist?("#{root}/memory.current") && File.exist?("#{root}/memory.max")
+						return true
+					end
+					
+					return false
+				end
+				
+				def initialize(cgroup_root: nil)
+					@cgroup_root = (cgroup_root || DEFAULT_CGROUP_ROOT).to_s.chomp("/")
+				end
+				
+				def capture
+					total = read_total
+					return nil unless total && total.positive?
+					
+					used = read_used
+					used = 0 if used.nil? || used.negative?
+					used = [used, total].min
+					
+					swap_total, swap_used = read_swap
+					reclaimable = read_reclaimable
+					
+					return Host::Memory.new(total, used, swap_total, swap_used, reclaimable)
+				end
+				
+				private
+				
+				def path(name)
+					"#{@cgroup_root}/#{name}"
+				end
+				
+				def read_total
+					limit = File.read(path("memory.max")).strip
+					
+					if limit == "max"
+						return nil
+					end
+					
+					return limit.to_i
+				end
+				
+				def read_used
+					File.read(path("memory.current")).strip.to_i
+				end
+				
+				def read_reclaimable
+					unless content = (File.read(path("memory.stat")) rescue nil)
+						return nil
+					end
+					
+					match = content.match(/^file\s+(\d+)/m)
+					return match ? match[1].to_i : nil
+				end
+				
+				def read_swap
+					unless content = (File.read("/proc/meminfo") rescue nil)
+						return [nil, nil]
+					end
+					
+					swap_total_kb = content[/SwapTotal:\s*(\d+)\s*kB/, 1]&.to_i
+					swap_free_kb = content[/SwapFree:\s*(\d+)\s*kB/, 1]&.to_i
+					
+					unless swap_total_kb
+						return [nil, nil]
+					end
+					
+					swap_total = swap_total_kb * 1024
+					swap_used = (swap_total_kb - (swap_free_kb || 0)) * 1024
+					return swap_total, swap_used
+				end
+			end
+		end
+	end
+end

data/lib/process/metrics/host/memory/linux/meminfo.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
+module Process
+	module Metrics
+		module Host
+			class Memory::Linux::Meminfo
+				def self.supported?
+					File.exist?("/proc/meminfo")
+				end
+				
+				def capture
+					content = File.read("/proc/meminfo") rescue nil
+					return nil unless content
+					
+					total = read_total(content)
+					return nil unless total && total.positive?
+					
+					used = read_used(content, total)
+					used = 0 if used.nil? || used.negative?
+					used = [used, total].min
+					
+					swap_total, swap_used = read_swap(content)
+					reclaimable = read_reclaimable(content)
+					
+					return Host::Memory.new(total, used, swap_total, swap_used, reclaimable)
+				end
+				
+				private
+				
+				def read_total(content)
+					match = content.match(/MemTotal:\s*(?<total>\d+)\s*kB/m)
+					match ? match[:total].to_i * 1024 : nil
+				end
+				
+				def read_used(content, total)
+					available_kb = content[/MemAvailable:\s*(\d+)\s*kB/, 1]&.to_i
+					available_kb ||= content[/MemFree:\s*(\d+)\s*kB/, 1]&.to_i
+					
+					unless available_kb
+						return nil
+					end
+					
+					return [total - (available_kb * 1024), 0].max
+				end
+				
+				def read_reclaimable(content)
+					cached_kb = content[/Cached:\s*(\d+)\s*kB/, 1]&.to_i || 0
+					buffers_kb = content[/Buffers:\s*(\d+)\s*kB/, 1]&.to_i || 0
+					sreclaimable_kb = content[/SReclaimable:\s*(\d+)\s*kB/, 1]&.to_i || 0
+					
+					return (cached_kb + buffers_kb + sreclaimable_kb) * 1024
+				end
+				
+				def read_swap(content)
+					swap_total_kb = content[/SwapTotal:\s*(\d+)\s*kB/, 1]&.to_i
+					swap_free_kb = content[/SwapFree:\s*(\d+)\s*kB/, 1]&.to_i
+					
+					unless swap_total_kb
+						return [nil, nil]
+					end
+					
+					swap_total = swap_total_kb * 1024
+					swap_used = (swap_total_kb - (swap_free_kb || 0)) * 1024
+					return swap_total, swap_used
+				end
+			end
+		end
+	end
+end

data/lib/process/metrics/host/memory/linux.rb

@@ -6,124 +6,38 @@
 module Process
 	module Metrics
 		module Host
-			# Linux implementation of host memory metrics.
-			# Uses cgroups v2 (memory.max, memory.current) or cgroups v1 (memory.limit_in_bytes, memory.usage_in_bytes) when in a container;
-			# otherwise reads /proc/meminfo (MemTotal, MemAvailable/MemFree, SwapTotal/SwapFree). Parses meminfo once per capture and reuses it.
-			class Memory::Linux
-				# Threshold for distinguishing actual memory limits from "unlimited" sentinel values in cgroups v1.
-				# In cgroups v1, when memory.limit_in_bytes is set to unlimited (by writing -1), the kernel stores a very large sentinel near 2^63.
-				# Any value >= 2^60 (1 exabyte) is treated as unlimited and we fall back to /proc/meminfo.
-				# Reference: https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt
-				CGROUP_V1_UNLIMITED_THRESHOLD = 2**60
+			# Linux host memory: tries cgroup v2, then cgroup v1, then /proc/meminfo.
+			module Memory::Linux
+				DEFAULT_CGROUP_ROOT = "/sys/fs/cgroup"
 				
-				def initialize
-					@meminfo = false
-				end
-				
-				# Capture current host memory. Reads total and used (from cgroup or meminfo), computes free, and parses swap from meminfo.
-				# @returns [Host::Memory | Nil]
-				def capture
-					total = capture_total
-					return nil unless total && total.positive?
-					
-					used = capture_used(total)
-					used = 0 if used.nil? || used.negative?
-					used = [used, total].min
-					free = total - used
-					
-					swap_total, swap_used = capture_swap
-					
-					return Host::Memory.new(total, used, free, swap_total, swap_used)
-				end
-				
-				private
-				
-				# Memoized /proc/meminfo contents. Used for total (MemTotal), used (via MemAvailable), and swap when not in a cgroup.
-				# @returns [String | Nil]
-				def meminfo
-					if @meminfo == false
-						@meminfo = File.read("/proc/meminfo") rescue nil
-					end
-					
-					return @meminfo
-				end
-				
-				# Total memory in bytes: cgroups v2 memory.max, cgroups v1 memory.limit_in_bytes (if < threshold), else MemTotal from meminfo.
-				# @returns [Integer | Nil]
-				def capture_total
-					if File.exist?("/sys/fs/cgroup/memory.max")
-						limit = File.read("/sys/fs/cgroup/memory.max").strip
-						return limit.to_i if limit != "max"
-					end
-					
-					if File.exist?("/sys/fs/cgroup/memory/memory.limit_in_bytes")
-						limit = File.read("/sys/fs/cgroup/memory/memory.limit_in_bytes").strip.to_i
-						return limit if limit > 0 && limit < CGROUP_V1_UNLIMITED_THRESHOLD
-					end
-					
-					unless meminfo_content = self.meminfo
-						return nil
-					end
-					
-					meminfo_content.each_line do |line|
-						if /MemTotal:\s*(?<total>\d+)\s*kB/ =~ line
-							return $~[:total].to_i * 1024
+				def self.capture(cgroup_root: DEFAULT_CGROUP_ROOT)
+					if Memory::Linux::CgroupV2.supported?(cgroup_root)
+						if capture = Memory::Linux::CgroupV2.new(cgroup_root: cgroup_root).capture
+							return capture
 						end
 					end
 					
-					return nil
-				end
-				
-				# Current memory usage in bytes: cgroups v2 memory.current, cgroups v1 memory.usage_in_bytes, or total - MemAvailable from meminfo.
-				# @parameter total [Integer] Total memory (used to compute used from MemAvailable when not in cgroup).
-				# @returns [Integer | Nil]
-				def capture_used(total)
-					if File.exist?("/sys/fs/cgroup/memory.current")
-						current = File.read("/sys/fs/cgroup/memory.current").strip.to_i
-						return current
-					end
-					
-					if File.exist?("/sys/fs/cgroup/memory/memory.usage_in_bytes")
-						limit = File.read("/sys/fs/cgroup/memory/memory.limit_in_bytes").strip.to_i
-						if limit > 0 && limit < CGROUP_V1_UNLIMITED_THRESHOLD
-							return File.read("/sys/fs/cgroup/memory/memory.usage_in_bytes").strip.to_i
+					if Memory::Linux::CgroupV1.supported?(cgroup_root)
+						if capture = Memory::Linux::CgroupV1.new(cgroup_root: cgroup_root).capture
+							return capture
 						end
 					end
 					
-					unless meminfo_content = self.meminfo
-						return nil
-					end
-					
-					available_kilobytes = meminfo_content[/MemAvailable:\s*(\d+)\s*kB/, 1]&.to_i
-					available_kilobytes ||= meminfo_content[/MemFree:\s*(\d+)\s*kB/, 1]&.to_i
-					return nil unless available_kilobytes
-					
-					return [total - (available_kilobytes * 1024), 0].max
-				end
-				
-				# Swap total and used in bytes from meminfo (SwapTotal, SwapFree).
-				# @returns [Array(Integer, Integer)] [swap_total_bytes, swap_used_bytes], or [nil, nil] if no swap.
-				def capture_swap
-					return [nil, nil] unless meminfo_content = self.meminfo
-					swap_total_kilobytes = meminfo_content[/SwapTotal:\s*(\d+)\s*kB/, 1]&.to_i
-					swap_free_kilobytes = meminfo_content[/SwapFree:\s*(\d+)\s*kB/, 1]&.to_i
-					
-					return [nil, nil] unless swap_total_kilobytes
-					
-					swap_total_bytes = swap_total_kilobytes * 1024
-					swap_used_bytes = (swap_total_kilobytes - (swap_free_kilobytes || 0)) * 1024
-					
-					return swap_total_bytes, swap_used_bytes
+					return Memory::Linux::Meminfo.new.capture if Memory::Linux::Meminfo.supported?
 				end
 			end
 		end
 	end
 end
 
+require_relative "linux/cgroup_v2"
+require_relative "linux/cgroup_v1"
+require_relative "linux/meminfo"
+
 # Wire Host::Memory to this implementation on Linux.
 class << Process::Metrics::Host::Memory
 	def capture
-		Process::Metrics::Host::Memory::Linux.new.capture
+		Process::Metrics::Host::Memory::Linux.capture
 	end
 	
 	def supported?

data/lib/process/metrics/host/memory.rb

@@ -8,22 +8,37 @@ module Process
 		# Per-host (system-wide) memory metrics. Use Host::Memory for total/used/free and swap; use Process::Metrics::Memory for per-process metrics.
 		module Host
 			# Struct for host memory snapshot. All sizes in bytes.
+			# Stored: total_size, used_size, swap_*, reclaimable_size. free_size and available_size are derived.
 			# @attribute total_size [Integer] Total memory (cgroup limit when in a container, else physical RAM).
-			# @attribute used_size [Integer] Memory in use (total_size - free_size).
-			# @attribute free_size [Integer] Available memory (MemAvailable-style: free + reclaimable).
+			# @attribute used_size [Integer] Memory in use (kernel/cgroup view; on Linux includes reclaimable e.g. page cache).
 			# @attribute swap_total_size [Integer, nil] Total swap, or nil if not available.
 			# @attribute swap_used_size [Integer, nil] Swap in use, or nil if not available.
-			Memory = Struct.new(:total_size, :used_size, :free_size, :swap_total_size, :swap_used_size) do
+			# @attribute reclaimable_size [Integer, nil] Reclaimable memory (e.g. page cache, slab), or nil. Included in used_size.
+			Memory = Struct.new(:total_size, :used_size, :swap_total_size, :swap_used_size, :reclaimable_size) do
+				def to_h
+					super.merge(free_size: free_size, available_size: available_size)
+				end
+				
 				alias as_json to_h
 				
 				def to_json(*arguments)
 					as_json.to_json(*arguments)
 				end
 				
+				# Complement of used: total_size - used_size. Same meaning on all platforms.
+				def free_size
+					total_size - used_size
+				end
+				
+				# Memory that could be used: free_size plus reclaimable. Use this for "available" when reclaimable_size is set; otherwise equals free_size.
+				def available_size
+					free_size + (reclaimable_size || 0)
+				end
+				
 				# Create a zero-initialized Host::Memory instance.
 				# @returns [Memory]
 				def self.zero
-					self.new(0, 0, 0, nil, nil)
+					self.new(0, 0, nil, nil, nil)
 				end
 				
 				# Whether host memory capture is supported on this platform.

data/lib/process/metrics/host.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
+require_relative "host/memory"
+
+module Process
+	module Metrics
+		module Host
+			# System name from uname -a (kernel name, nodename, release, etc.). Returns nil if uname is not available.
+			# @returns [String, nil]
+			def self.name
+				IO.popen(["uname", "-a"], "r", &:read)&.strip
+			rescue Errno::ENOENT
+				nil
+			end
+		end
+	end
+end

data/lib/process/metrics/memory.rb

@@ -4,7 +4,7 @@
 # Copyright, 2019-2026, by Samuel Williams.
 
 require "json"
-require_relative "host/memory"
+require_relative "host"
 
 module Process
 	module Metrics

data/lib/process/metrics/version.rb

@@ -7,6 +7,6 @@
 module Process
 	# @namespace
 	module Metrics
-		VERSION = "0.10.2"
+		VERSION = "0.11.0"
 	end
 end

data/readme.md

@@ -16,6 +16,10 @@ Please see the [project documentation](https://socketry.github.io/process-metric
 
 Please see the [project releases](https://socketry.github.io/process-metrics/releases/index) for all releases.
 
+### v0.11.0
+
+  - `process-metrics` command is removed, replaced with `bake process:metrics`.
+
 ### v0.10.2
 
   - Add `Process::Metrics::Memory#private_size` for the sum of private (unshared) pages (Private\_Clean + Private\_Dirty); `#unique_size` is now an alias for `#private_size`.
@@ -56,12 +60,6 @@ Please see the [project releases](https://socketry.github.io/process-metrics/rel
 
   - Fixed Linux memory usage capture to correctly read memory statistics.
 
-### v0.5.0
-
-  - Added `--total-memory` option for scaling memory usage graphs, allowing users to set custom total memory values.
-  - Improved support for proportional memory usage (PSS).
-  - Exposed total system memory information.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.11.0
+
+  - `process-metrics` command is removed, replaced with `bake process:metrics`.
+
 ## v0.10.2
 
   - Add `Process::Metrics::Memory#private_size` for the sum of private (unshared) pages (Private\_Clean + Private\_Dirty); `#unique_size` is now an alias for `#private_size`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: process-metrics
 version: !ruby/object:Gem::Version
-  version: 0.10.2
+  version: 0.11.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -67,38 +67,23 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2'
-- !ruby/object:Gem::Dependency
-  name: samovar
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
-executables:
-- process-metrics
+executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- bin/process-metrics
 - context/getting-started.md
 - context/index.yaml
 - lib/process/metrics.rb
-- lib/process/metrics/command.rb
-- lib/process/metrics/command/summary.rb
-- lib/process/metrics/command/top.rb
 - lib/process/metrics/general.rb
 - lib/process/metrics/general/linux.rb
 - lib/process/metrics/general/process_status.rb
+- lib/process/metrics/host.rb
 - lib/process/metrics/host/memory.rb
 - lib/process/metrics/host/memory/darwin.rb
 - lib/process/metrics/host/memory/linux.rb
+- lib/process/metrics/host/memory/linux/cgroup_v1.rb
+- lib/process/metrics/host/memory/linux/cgroup_v2.rb
+- lib/process/metrics/host/memory/linux/meminfo.rb
 - lib/process/metrics/memory.rb
 - lib/process/metrics/memory/darwin.rb
 - lib/process/metrics/memory/linux.rb

data/bin/process-metrics

@@ -1,29 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
-# 
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-# 
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-# 
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-# THE SOFTWARE.
-
-require_relative "../lib/process/metrics/command"
-
-begin
-	Process::Metrics::Command.call
-rescue Interrupt
-end

data/lib/process/metrics/command/summary.rb

@@ -1,217 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2020-2026, by Samuel Williams.
-
-require "samovar"
-
-require_relative "../general"
-
-require "console/terminal"
-
-module Process
-	module Metrics
-		module Command
-			# Helper module for rendering horizontal progress bars using Unicode block characters.
-			module Bar
-				BLOCK = [
-					" ",
-					"▏",
-					"▎",
-					"▍",
-					"▌",
-					"▋",
-					"▊",
-					"▉",
-					"█",
-				]
-				
-				# Format a fractional value as a horizontal bar.
-				# @parameter value [Float] A value between 0.0 and 1.0 representing the fill level.
-				# @parameter width [Integer] The width of the bar in characters.
-				# @returns [String] A string of Unicode block characters representing the filled bar.
-				def self.format(value, width)
-					blocks = width * value
-					full_blocks = blocks.floor
-					partial_block = ((blocks - full_blocks) * BLOCK.size).floor
-					
-					if partial_block.zero?
-						BLOCK.last * full_blocks
-					else
-						"#{BLOCK.last * full_blocks}#{BLOCK[partial_block]}"
-					end.ljust(width)
-				end
-			end
-			
-			# Command that displays a formatted summary of memory usage statistics for processes.
-			class Summary < Samovar::Command
-				self.description = "Display a summary of memory usage statistics."
-				
-				options do
-					option "--pid <integer>", "Report on a single process id.", type: Integer
-					option "-p/--ppid <integer>", "Report on all children of this process id.", type: Integer
-					
-					option "--total-memory <integer>", "Set the total memory relative to the usage (MiB).", type: Integer
-				end
-				
-				# Get the configured terminal for styled output.
-				# @returns [Console::Terminal] A terminal object with color/style definitions.
-				def terminal
-					terminal = Console::Terminal.for($stdout)
-					
-					# terminal[:pid] = terminal.style(:blue)
-					terminal[:command] = terminal.style(nil, nil, :bold)
-					terminal[:key] = terminal.style(:cyan)
-					
-					terminal[:low] = terminal.style(:green)
-					terminal[:medium] = terminal.style(:yellow)
-					terminal[:high] = terminal.style(:red)
-					
-					return terminal
-				end
-				
-				# Format a processor utilization percentage with color-coded bar.
-				# @parameter value [Float] The CPU utilization percentage (0.0-100.0).
-				# @parameter terminal [Console::Terminal] The terminal to output styled text.
-				def format_processor_utilization(value, terminal)
-					if value > 80.0
-						intensity = :high
-					elsif value > 50.0
-						intensity = :medium
-					else
-						intensity = :low
-					end
-					
-					formatted = "%5.1f%% " % value
-					
-					terminal.print(formatted.rjust(10), intensity, "[", Bar.format(value / 100.0, 60), "]", :reset)
-				end
-				
-				UNITS = ["KiB", "MiB", "GiB"]
-				
-				# Format a memory size value in human-readable units.
-				# @parameter value [Numeric] The size value in bytes.
-				# @parameter units [Array(String)] The unit labels to use for scaling.
-				# @returns [String] A formatted string with value and unit (e.g., "512KiB", "1.5MiB").
-				def format_size(value, units: UNITS)
-					unit = -1
-					
-					while value >= 1024.0 && unit < units.size - 1
-						value /= 1024.0
-						unit += 1
-					end
-					
-					if unit < 0
-						# Value is less than 1 KiB, show in bytes
-						return "#{value.round(0)}B"
-					else
-						return "#{value.round(unit)}#{units[unit]}"
-					end
-				end
-				
-				# Format a memory value with a horizontal bar showing utilization relative to total.
-				# @parameter value [Numeric] The memory value in bytes.
-				# @parameter total [Numeric] The total memory available in bytes.
-				# @parameter terminal [Console::Terminal] The terminal to output styled text.
-				def format_memory(value, total, terminal)
-					if value > (total * 0.8)
-						intensity = :high
-					elsif value > (total * 0.5)
-						intensity = :medium
-					else
-						intensity = :low
-					end
-					
-					formatted = (format_size(value) + " ").rjust(10)
-					
-					terminal.print(formatted, intensity, "[", Bar.format(value / total.to_f, 60), "]", :reset)
-				end
-				
-				# Get the total memory to use for percentage calculations.
-				# @returns [Integer] Total memory in bytes.
-				def total_memory
-					if total_memory = @options[:total_memory]
-						# Convert from MiB to bytes
-						return total_memory * 1024 * 1024
-					else
-						return Process::Metrics::Memory.total_size
-					end
-				end
-				
-				# Execute the summary command, capturing and displaying process metrics.
-				def call
-					# Validate required arguments: at least one of --pid or --ppid must be provided:
-					unless @options[:pid] || @options[:ppid]
-						raise Samovar::MissingValueError.new(self, "pid or ppid")
-					end
-					
-					terminal = self.terminal
-					
-					summary = Process::Metrics::General.capture(pid: @options[:pid], ppid: @options[:ppid])
-					
-					format_memory = self.method(:format_memory).curry
-					shared_memory = 0
-					private_memory = 0
-					total_memory = self.total_memory
-					
-					proportional = true
-					
-					summary.each do |pid, general|
-						terminal.print_line(:pid, pid, :reset, " ", :command, general[:command])
-						
-						terminal.print(:key, "Processor Usage: ".rjust(20), :reset)
-						format_processor_utilization(general.processor_utilization, terminal)
-						terminal.print_line
-						
-						if memory = general.memory
-							shared_memory += memory.proportional_size
-							private_memory += memory.unique_size
-							
-							terminal.print_line(
-								:key, "Memory: ".rjust(20), :reset,
-								format_memory[memory.proportional_size, total_memory]
-							)
-							
-							terminal.print_line(
-								:key, "Private Memory: ".rjust(20), :reset,
-								format_memory[memory.unique_size, total_memory]
-							)
-						else
-							shared_memory += general.resident_size
-							proportional = false
-							
-							terminal.print_line(
-								:key, "Memory: ".rjust(20), :reset,
-								format_memory[general.resident_size, total_memory]
-							)
-						end
-					end
-					
-					terminal.print_line("Summary")
-					
-					if proportional
-						terminal.print_line(
-							:key, "Memory: ".rjust(20), :reset,
-							format_memory[shared_memory, total_memory]
-						)
-						
-						terminal.print_line(
-							:key, "Private Memory: ".rjust(20), :reset,
-							format_memory[private_memory, total_memory]
-						)
-					else
-						terminal.print_line(
-							:key, "Memory: ".rjust(20), :reset,
-							format_memory[memory, total_memory]
-						)
-					end
-					
-					terminal.print_line(
-						:key, "Memory (Total): ".rjust(20), :reset,
-						format_memory[shared_memory + private_memory, total_memory]
-					)
-				end
-			end
-		end
-	end
-end

data/lib/process/metrics/command/top.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
-
-require "samovar"
-
-require_relative "summary"
-require_relative "../version"
-
-module Process
-	module Metrics
-		module Command
-			# Top-level command entry point for the process-metrics CLI.
-			class Top < Samovar::Command
-				self.description = "Collect memory usage statistics."
-				
-				options do
-					option "-h/--help", "Print out help information."
-					option "-v/--version", "Print out the application version."
-				end
-				
-				nested :command, {
-					"summary" => Summary,
-				}, default: "summary"
-				
-				# Execute the top command, dispatching to nested commands.
-				def call
-					if @options[:version]
-						puts "#{self.name} v#{VERSION}"
-					elsif @options[:help]
-						self.print_usage
-					else
-						@command.call
-					end
-				end
-			end
-		end
-	end
-end

data/lib/process/metrics/command.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
-
-require_relative "command/top"
-
-module Process
-	module Metrics
-		# @namespace
-		module Command
-			# Call the default command (Top).
-			# @parameter arguments [Array] Command-line arguments to pass through.
-			def self.call(*arguments)
-				Top.call(*arguments)
-			end
-		end
-	end
-end