proscenium 0.25.3 → 0.26.0

data/lib/proscenium/cli/project_lock.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require_relative '../context_map'
+
+module Proscenium
+  module CLI
+    # One install at a time per project, and a marker while one is under way (#154).
+    #
+    # The lock is `flock` on `.proscenium/lock`, so the operating system releases it when its
+    # holder dies and there is nothing stale to reclaim. The marker,
+    # `.proscenium/installing`, outlives an interrupted install: the engine refuses to build while
+    # it exists, and the next install removes it once it has finished.
+    #
+    # The holder's name goes in `.proscenium/holder`, not in the lock file: Windows locks are
+    # mandatory, so a second install could not read a locked file to say who holds it.
+    #
+    # The lock is not handed to the manager: every process the manager starts would inherit it, so
+    # a daemon a lifecycle script left running would hold it. So a killed CLI releases the lock
+    # while its manager runs on; the manager's pid goes in `.proscenium/manager` while it runs, and
+    # an install that finds that process alive is refused as if the lock were held.
+    class ProjectLock
+      DIR = '.proscenium'
+
+      NOFOLLOW = File.const_defined?(:NOFOLLOW) ? File::NOFOLLOW : 0
+
+      # Writes one of install's own files, never through a link: a checkout could point one at any
+      # file the user can write. The open refuses a link itself where the OS can (O_NOFOLLOW), so
+      # one swapped in after the check is refused too.
+      def self.write(path, text)
+        raise Error.new('PSM-E-OWNED-LINK', paths: path) if File.symlink?(path)
+
+        File.open(path, File::WRONLY | File::CREAT | File::TRUNC | NOFOLLOW, 0o644) { it.write(text) }
+      rescue Errno::ELOOP, Errno::EMLINK
+        raise Error.new('PSM-E-OWNED-LINK', paths: path)
+      end
+
+      def initialize(root)
+        @root = root
+        @dir = File.join(root, DIR)
+      end
+
+      # The engine probes these two to refuse builds during an install, so both sides share them.
+      def lock_path = File.join(@root, ContextMap::LOCK)
+      def marker_path = File.join(@root, ContextMap::INSTALLING)
+      def holder_path = File.join(@dir, 'holder')
+      def manager_path = File.join(@dir, 'manager')
+
+      # Takes the lock for the block, or raises PSM-E-BUSY naming the install that holds it.
+      def synchronize(command)
+        FileUtils.mkdir_p(@dir)
+        @io = File.open(lock_path, File::RDWR | File::CREAT, 0o644)
+        unless acquired? && !(manager = running_manager)
+          holder = File.exist?(holder_path) ? File.read(holder_path).strip : ''
+          holder = "the package manager (pid #{manager}) of a stopped #{holder}" if manager
+          @io.close
+          raise Error.new('PSM-E-BUSY', holder: holder.empty? ? 'another install' : holder)
+        end
+
+        self.class.write(holder_path, "#{command} (pid #{Process.pid})\n")
+        yield self
+      ensure
+        @io&.close unless @io&.closed?
+      end
+
+      # The lock, retried for a second: a running Rails app probes it with a shared lock for a few
+      # microseconds at a time, and that must not read as another install.
+      def acquired?
+        20.times do
+          return true if @io.flock(File::LOCK_EX | File::LOCK_NB)
+
+          sleep 0.05
+        end
+        false
+      end
+
+      # The pid of a manager an earlier install started that is still running, or nil.
+      # ponytail: a reused pid reads as busy until that process exits; a process start time would
+      # tell them apart.
+      def running_manager
+        return unless File.exist?(manager_path)
+
+        pid = File.read(manager_path).to_i
+        return unless pid.positive?
+
+        Process.kill(0, pid)
+        pid
+      rescue Errno::ESRCH
+        nil
+      rescue Errno::EPERM
+        pid
+      end
+
+      def manager_started(pid) = self.class.write(manager_path, "#{pid}\n")
+
+      def manager_finished = FileUtils.rm_f(manager_path)
+
+      # Whether an earlier install was interrupted before it finished.
+      def interrupted? = File.exist?(marker_path)
+
+      def mark! = self.class.write(marker_path, "#{Process.pid}\n")
+
+      def unmark! = FileUtils.rm_f(marker_path)
+    end
+  end
+end

data/lib/proscenium/cli/registration.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../context_map'
+require_relative 'bun_linker'
+require_relative 'brackets'
+require_relative 'gitignore'
+require_relative 'pnpm_workspace'
+require_relative 'manager'
+
+module Proscenium
+  module CLI
+    # The one-time edits that register `.proscenium/packages/*` with the app's package manager, and
+    # the `.gitignore` lines for Proscenium's own state (#154, Gitignore). Each is a textual
+    # splice, so the file's other settings, order and comments survive; each is computed without
+    # writing, so `install` can print it as a diff first.
+    module Registration
+      PATTERN = ContextMap::REGISTRATION
+
+      module_function
+
+      # The edits the project at `root` needs: [path, current text, new text] for each file that
+      # changes. Empty once registered.
+      def edits(root, manager)
+        file = manager == 'bun' ? 'package.json' : 'pnpm-workspace.yaml'
+        registration = if manager == 'bun' then method(:splice_package_json)
+                       else PnpmWorkspace.method(:splice)
+                       end
+        splices = [[file, registration],
+                   ['.gitignore', Gitignore.method(:splice)]]
+        if manager == 'bun' && !Manager.new('bun', root).bun_linker
+          linker = BunLinker.current(root)
+          splices << ['bunfig.toml', ->(text) { BunLinker.splice(text, linker) }]
+        end
+        splices.filter_map do |name, splice|
+          path = File.join(root, name)
+          text = File.exist?(path) ? File.read(path) : ''
+          spliced = splice.call(text)
+          next if spliced == text
+          # Writing through a link could change a file outside the app.
+          raise Error.new('PSM-E-OWNED-LINK', paths: name) if File.symlink?(path)
+
+          [path, text, spliced]
+        end
+      end
+
+      # Whether the app has adopted RubyGem NPM dependencies: its committed registration names the
+      # contexts.
+      def registered?(root, manager)
+        ContextMap.registers?(root, manager == 'bun' ? 'package.json' : 'pnpm-workspace.yaml')
+      end
+
+      def refused(file) = Error.new('PSM-E-REGISTRATION', file:)
+
+      # Adds the pattern to package.json's `workspaces`, as an array or an object's `packages`,
+      # or adds the key. Refuses rather than guess at JSON it cannot splice. A byte order mark is
+      # kept.
+      def splice_package_json(text)
+        return text if ContextMap.registered_in?('package.json', text, strict: true)
+
+        bom = text.start_with?("\uFEFF") ? "\uFEFF" : ''
+        spliced = splice_json(text.delete_prefix(bom))
+        if ContextMap.excludes?(ContextMap.json_workspaces(spliced))
+          raise Error.new('PSM-E-REGISTRATION-EXCLUDED', file: 'package.json')
+        end
+
+        "#{bom}#{spliced}"
+      end
+
+      def splice_json(text)
+        json = text.empty? ? {} : JSON.parse(text)
+        raise refused('package.json') unless json.is_a?(Hash)
+
+        current = json['workspaces']
+        spliced = if current.nil?
+                    add_key(text, json)
+                  elsif current.is_a?(Array)
+                    insert_into_array(text, key_end(text, /"workspaces"\s*:\s*\[/, 1))
+                  elsif current.is_a?(Hash) && current['packages'].is_a?(Array)
+                    object = key_end(text, /"workspaces"\s*:\s*\{/, 1)
+                    insert_into_array(text, key_end(text, /"packages"\s*:\s*\[/, 2, object))
+                  else
+                    raise refused('package.json')
+                  end
+        verify_json(json, spliced)
+        spliced
+      rescue JSON::ParserError
+        raise refused('package.json')
+      end
+
+      def key_end(...) = Brackets.key_end(...) || raise(refused('package.json'))
+
+      def verify_json(before, spliced)
+        after = JSON.parse(spliced)
+        expected = expected_workspaces(before)
+        actual = after['workspaces']
+        actual = actual['packages'] if actual.is_a?(Hash)
+        same = after.except('workspaces') == before.except('workspaces')
+        raise refused('package.json') unless actual == expected && same
+      end
+
+      def expected_workspaces(json)
+        current = json['workspaces']
+        current = current['packages'] if current.is_a?(Hash)
+        (current || []) + [PATTERN]
+      end
+
+      # Appends the pattern as the last element of the array whose `[` ends at `start`.
+      def insert_into_array(text, start)
+        close = Brackets.array_end(text, start) or raise refused('package.json')
+        body = text[start...close]
+        if body.strip.empty?
+          "#{text[0...start]}\"#{PATTERN}\"#{text[close..]}"
+        else
+          last = start + body.rstrip.length
+          indent = body[/\n([ \t]*)\S/, 1]
+          separator = indent ? ",#{eol(text)}#{indent}" : ', '
+          "#{text[0...last]}#{separator}\"#{PATTERN}\"#{text[last..]}"
+        end
+      end
+
+      # Adds `"workspaces": [pattern]` as the first key, in the file's own indentation.
+      def add_key(text, json)
+        return "#{JSON.pretty_generate('workspaces' => [PATTERN])}\n" if text.strip.empty?
+
+        open = text.index('{') + 1
+        indent = text[/\{\s*\n([ \t]+)/, 1]
+        if indent
+          "#{text[0...open]}#{eol(text)}#{indent}\"workspaces\": [\"#{PATTERN}\"]" \
+            "#{',' unless json.empty?}#{text[open..]}"
+        else
+          "#{text[0...open]}\"workspaces\": [\"#{PATTERN}\"]#{', ' unless json.empty?}" \
+            "#{text[open..]}"
+        end
+      end
+
+      def eol(text) = text.include?("\r\n") ? "\r\n" : "\n"
+    end
+  end
+end

data/lib/proscenium/cli/reporter.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Proscenium
+  module CLI
+    # Writes what the CLI tells the user: human text, or with `--json` newline-delimited,
+    # schema-versioned events on stdout. Errors go to stderr as text, or to stdout as an event.
+    # Human text is coloured only on a terminal, and never with NO_COLOR set or TERM=dumb.
+    class Reporter
+      SCHEMA = 1
+      STYLES = { bold: 1, dim: 2, red: 31, green: 32, yellow: 33, cyan: 36 }.freeze
+      DIFF_STYLES = { '---' => [:bold], '+++' => [:bold], '@@' => [:cyan], '+' => [:green],
+                      '-' => [:red] }.freeze
+
+      # "1 gem", "2 gems".
+      def self.count(number, one, many = "#{one}s") = "#{number} #{number == 1 ? one : many}"
+
+      def initialize(out:, err:, json: false, quiet: false)
+        @out = out
+        @err = err
+        @json = json
+        @quiet = quiet
+      end
+
+      def json? = @json
+
+      # `text` in `styles` for stdout, or as it is when stdout is not a terminal or is JSON.
+      def paint(text, *styles) = @json ? text : style(@out, text, *styles)
+
+      # A unified diff with removed lines red, added lines green and hunk headers cyan.
+      def paint_diff(diff)
+        diff.lines(chomp: true).map do |line|
+          prefix = DIFF_STYLES.keys.find { line.start_with?(it) }
+          prefix ? paint(line, *DIFF_STYLES[prefix]) : line
+        end.join("\n") + (diff.end_with?("\n") ? "\n" : '')
+      end
+
+      # A line of the human summary, or an event in JSON mode.
+      def info(message, event: 'info', phase: nil, **details)
+        if @json
+          emit(event:, phase:, status: 'ok', message:, details:)
+        elsif !@quiet
+          @out.puts message
+        end
+      end
+
+      # A command's result rather than its progress (the version, the usage, inspect's report):
+      # printed even with --quiet, which would otherwise leave such a command saying nothing.
+      def result(message, event:, **details)
+        @json ? emit(event:, status: 'ok', message:, details:) : @out.puts(message)
+      end
+
+      # One JSON document on stdout, for a command whose output is a report (`inspect --json`).
+      def document(hash) = @out.puts(JSON.generate(hash))
+
+      # A problem that does not stop the command.
+      def warning(error, phase: nil)
+        if @json
+          emit(event: 'warning', phase:, status: 'warning', code: error.code,
+               message: error.message, fix: error.fix, details: error.details)
+        else
+          problem('Warning:', :yellow, error)
+        end
+      end
+
+      def error(error, phase: nil, manager: nil)
+        if @json
+          emit(event: 'error', phase:, status: 'error', code: error.code, message: error.message,
+               fix: error.fix, manager:, details: error.details)
+        else
+          problem('Error:', :red, error)
+        end
+      end
+
+      private
+
+      # A problem for a person: what happened, a blank line, what to do, and the code to search
+      # the docs for. A blank line ends it, apart from whatever follows.
+      def problem(label, colour, error)
+        @err.puts "#{style(@err, label, :bold, colour)} #{error.message}"
+        @err.puts
+        @err.puts "#{style(@err, 'To fix:', :bold)} #{error.fix}"
+        @err.puts style(@err, "(#{error.code})", :dim)
+        @err.puts
+      end
+
+      def style(io, text, *styles)
+        return text if styles.empty? || !colour?(io)
+
+        "\e[#{styles.map { STYLES.fetch(it) }.join(';')}m#{text}\e[0m"
+      end
+
+      def colour?(io)
+        io.respond_to?(:tty?) && io.tty? && ENV['NO_COLOR'].to_s.empty? && ENV['TERM'] != 'dumb'
+      end
+
+      def emit(**event)
+        @out.puts JSON.generate({ schema: SCHEMA }.merge(event.compact.reject { |_, v| v == {} }))
+      end
+    end
+  end
+end

data/lib/proscenium/cli/rules.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Proscenium
+  module CLI
+    # The author contract for a participating gem's package.json (#154): what `gem check` and
+    # `install` refuse. Each rule yields a problem as [error code, format arguments]; the caller
+    # decides whether a problem is fatal and how to word the escape.
+    module Rules
+      DEPENDENCY_FIELDS = %w[dependencies peerDependencies optionalDependencies].freeze
+      HOOKS = %w[preinstall install postinstall prepare].freeze
+      REACT = %w[react react-dom].freeze
+      # Problems install reports as warnings: the gem still gets its context.
+      WARNINGS = %w[PSM-E-REACT].freeze
+
+      # npm's rules for a package name, as `@rubygems/<gem>` must satisfy them: lowercase, so no two
+      # contexts can differ only in case, and at most 214 characters.
+      VALID_NAME = %r{\A@rubygems/[a-z0-9][a-z0-9._~-]*\z}
+      NAME_LIMIT = 214
+
+      # Names Windows reserves for devices, with or without an extension: COM1-COM9 and LPT1-LPT9,
+      # not COM0 or LPT0. A context directory so named cannot exist there, so the gem is refused on
+      # every host alike (C27).
+      RESERVED = /\A(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?\z/
+
+      # URL specs Proscenium accepts. With RANGE_OR_TAG and npm: aliases, these are the only specs
+      # accepted; anything else is refused.
+      GIT_URL = %r{\A(?:github:[\w.-]+/[\w.-]+|git\+(?:https|ssh)://\S+)(?:#\S+)?\z}
+      TARBALL = %r{\Ahttps://\S+\z}
+      # A `user:password` before the host of any URL, anything before the host of an http(s) URL
+      # (a token), or a token-like query parameter. `git+ssh://git@host` names the SSH user, not a
+      # credential.
+      CREDENTIAL = Regexp.union(%r{://[^/@\s]*:[^/@\s]*@}, %r{https?://[^/@\s]*@}i,
+                                /[?&][^=&#]*(?:token|key|auth|pass|secret|sig)[^=&#]*=/i)
+      # A semver range or a dist-tag. Everything else a manager would read as a path, a Git
+      # repository or a protocol, so it is refused.
+      RANGE_OR_TAG = /\A(?:[\w*^~<>=|+.-]|(?<=\S) (?=\S))*\z/
+      # `npm:<package>[@<range or tag>]`: a registry package by npm's name rules, never a path,
+      # link or URL.
+      ALIAS = %r{\Anpm:(?<name>(?:@[a-z0-9][\w.~-]*/)?[a-z0-9][\w.~-]*)(?:@(?<range>.*))?\z}mi
+
+      module_function
+
+      # Problems with the manifest of `gem`, rooted at `root` (where binding.gyp would be), and
+      # named `path` in errors. `binding_gyp` says a built gem, which has no root on disk, ships
+      # one.
+      def check(gem, manifest, root: nil, path: 'package.json', binding_gyp: false)
+        shape = shape_problem(manifest)
+        return [['PSM-E-MANIFEST', { gem:, path:, cause: shape }]] if shape
+
+        problems = []
+        problems << ['PSM-E-NAME', { gem: }] unless valid_name?(gem)
+        problems << ['PSM-E-WORKSPACES', { gem: }] if manifest.key?('workspaces')
+
+        hooks = HOOKS & (manifest['scripts'] || {}).keys
+        binding_gyp ||= root && File.exist?(File.join(root, 'binding.gyp'))
+        hooks << 'binding.gyp' if binding_gyp
+        problems << ['PSM-E-HOOK', { gem:, hooks: hooks.join(', ') }] if hooks.any?
+
+        DEPENDENCY_FIELDS.each do |field|
+          (manifest[field] || {}).each do |name, spec|
+            problem = spec_problem(gem, name, spec)
+            problems << problem if problem
+          end
+        end
+
+        # An optional dependency is the gem's own copy too, and so is React under an alias.
+        react = REACT & %w[dependencies optionalDependencies].flat_map do |field|
+          (manifest[field] || {}).flat_map { |name, spec| [name, ALIAS.match(spec)&.[](:name)] }
+        end
+        problems << ['PSM-E-REACT', { gem:, packages: react.join(' and ') }] if react.any?
+        problems
+      end
+
+      # Why a field every rule reads is the wrong type, or nil. Checked first, so nothing after it
+      # meets a string where it expects an object.
+      def shape_problem(manifest)
+        %w[scripts peerDependenciesMeta].each do |field|
+          return "#{field} is not an object" unless [Hash, NilClass].include?(manifest[field].class)
+        end
+        DEPENDENCY_FIELDS.each do |field|
+          deps = manifest[field]
+          next if deps.nil?
+          return "#{field} is not an object" unless deps.is_a?(Hash)
+
+          name = deps.find { |_, spec| !spec.is_a?(String) }&.first
+          return "#{field}.#{name} is not a string" if name
+        end
+        nil
+      end
+
+      # Each "<gem>: <name> (<spec>)" whose name the app trusts but whose spec is not that registry
+      # package: Git, a URL, or an alias to another package. Bun trusts a dependency by name,
+      # whatever its source (probed on Bun 1.4.2), so a gem could run its own install script under
+      # the app's trust. `manifests` is each gem's parsed context.
+      def trusted_substitutions(trusted, manifests)
+        substitutions(manifests).filter_map do |gem, name, spec|
+          "#{gem}: #{name} (#{spec})" if trusted == :all || trusted.include?(name)
+        end
+      end
+
+      # Each [gem, name, spec] that is not that registry package: Git, a URL, or an alias to
+      # another package.
+      def substitutions(manifests)
+        manifests.flat_map do |gem, manifest|
+          DEPENDENCY_FIELDS.flat_map { (manifest[it] || {}).to_a }.filter_map do |name, spec|
+            [gem, name, spec] if substitutes?(name, spec)
+          end
+        end
+      end
+
+      def substitutes?(name, spec)
+        target = ALIAS.match(spec)&.[](:name)
+        GIT_URL.match?(spec) || TARBALL.match?(spec) || (target && target.downcase != name.downcase)
+      end
+
+      def valid_name?(gem)
+        name = "@rubygems/#{gem}"
+        VALID_NAME.match?(name) && name.length <= NAME_LIMIT && !RESERVED.match?(gem) &&
+          !gem.end_with?('.')
+      end
+
+      # Larger than any real package.json, small enough to read without a second thought.
+      MANIFEST_LIMIT = 1024 * 1024
+
+      # Why the package.json at `path`, in a gem rooted at `gem_root`, cannot be read safely, or
+      # nil (C29): it must be a regular file, inside the gem once links are followed, and no larger
+      # than MANIFEST_LIMIT. A FIFO or device would block or never end, and a link out of the gem
+      # would read a file the gem does not ship.
+      def manifest_file_problem(path, gem_root)
+        return 'it is not a regular file' unless File.file?(path)
+
+        real = File.realpath(path)
+        return 'it links outside the gem' unless real.start_with?("#{File.realpath(gem_root)}/")
+        return 'it is larger than 1 MB' if File.size(real) > MANIFEST_LIMIT
+
+        nil
+      end
+
+      # Why `spec` for dependency `name` is refused, or nil. A gem-to-gem reference
+      # (`@rubygems/<other>`) is checked against the bundle at install time, not here.
+      def spec_problem(gem, name, spec)
+        return nil if name.start_with?('@rubygems/')
+
+        # A credential in a URL would be committed with the context (C31). A server decodes
+        # percent-escapes, so `%74oken=` is `token=`.
+        if [spec, unescape(spec)].any? { CREDENTIAL.match?(it) }
+          return ['PSM-E-CREDENTIAL', { gem:, name: }]
+        end
+
+        if spec.start_with?('npm:')
+          return ['PSM-E-ALIAS', { gem:, name:, spec: }] if spec.start_with?('npm:@rubygems/')
+
+          target = ALIAS.match(spec)
+          return if target && range_or_tag?(target[:range].to_s)
+
+          return ['PSM-E-SPEC', { gem:, name:, spec: }]
+        end
+        return nil if GIT_URL.match?(spec) || TARBALL.match?(spec) || range_or_tag?(spec)
+
+        ['PSM-E-SPEC', { gem:, name:, spec: }]
+      end
+
+      def unescape(spec) = spec.gsub(/%(\h\h)/) { ::Regexp.last_match(1).hex.chr }
+
+      # A leading dot is a path to every manager, though the characters are a range's.
+      def range_or_tag?(spec) = RANGE_OR_TAG.match?(spec) && !spec.start_with?('.')
+    end
+  end
+end

data/lib/proscenium/cli/runner.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'bundler'
+
+module Proscenium
+  module CLI
+    # Runs the package manager (#154): an argument array, never a shell, so no package name is ever
+    # interpreted; in the project root; with the environment a direct native install would have,
+    # not Bundler's (as the Rakefile does for `gem build`), so a dependency's lifecycle script that
+    # runs Ruby sees the app's own setup. The project lock is not passed down: every process the
+    # manager starts would inherit it, so a daemon a lifecycle script left behind would hold it.
+    # The manager's pid record keeps a manager that outlives a killed CLI from being joined.
+    module Runner
+      SIGNALS = %w[INT TERM].freeze
+
+      module_function
+
+      # Runs `executable` with `args` in `root` and returns when it exits. Options: `on_spawn`
+      # (called with the manager's pid), `out` (default: stderr, so stdout stays the CLI's
+      # summary), and `manager` (its name in errors).
+      # Raises PSM-E-INTERRUPTED if a signal stopped it, PSM-E-NATIVE if it failed.
+      # Its output is also kept, the last TAIL bytes of it, so a failure can say which gem it
+      # involves; the error carries it as `output`.
+      def run(executable, args, root:, **opts)
+        reader, writer = IO.pipe
+        spawn = { chdir: root, out: writer, err: writer, in: File::NULL }
+        pid = Bundler.with_unbundled_env { Process.spawn(ENV.to_h, executable, *args, **spawn) }
+        writer.close
+        record(pid, opts[:on_spawn])
+        kept = +''
+        relaying = relay(reader, opts.fetch(:out, $stderr), kept)
+        interrupted = []
+        previous = forward_signals(pid, interrupted)
+        _, status = Process.wait2(pid)
+        await_interrupt(status, interrupted)
+        # A process the manager left running may hold its output open: once the manager has
+        # exited, its output gets a moment to drain, and no more.
+        relaying.kill unless relaying.join(DRAIN)
+        check(status, opts.fetch(:manager) { File.basename(executable) }, args, kept.dup,
+              interrupted.first)
+      ensure
+        previous&.each { |signal, handler| Signal.trap(signal, handler) }
+        reader&.close unless reader&.closed?
+      end
+
+      # Hands the manager's pid to `on_spawn`, which records it. A manager whose pid was not
+      # recorded is stopped: the install is failing and releasing its lock, and a manager left
+      # running unrecorded would run beside the next install.
+      def record(pid, on_spawn)
+        recorded = false
+        on_spawn&.call(pid)
+        recorded = true
+      ensure
+        unless recorded
+          begin
+            Process.kill(:KILL, pid)
+          rescue Errno::ESRCH
+            nil
+          end
+          Process.wait(pid)
+        end
+      end
+
+      TAIL = 64 * 1024
+      # Seconds the manager's output may keep draining after it exits.
+      DRAIN = 1
+
+      # Copies the manager's output to `destination` as it arrives, keeping its tail. A destination
+      # that fails, such as a closed `| head`, is dropped but the pipe is still drained: a manager
+      # left blocked on a full pipe would never exit, and the lock would stay held.
+      def relay(reader, destination, kept)
+        Thread.new do
+          loop do
+            chunk = reader.readpartial(4096)
+            destination = write(destination, chunk)
+            kept << chunk
+            kept.replace(kept.byteslice(-TAIL, TAIL)) if kept.bytesize > TAIL
+          end
+        rescue IOError # EOFError included: the manager closed its output
+          nil
+        end
+      end
+
+      # Writes `chunk` to `destination`, returning it, or nil once it has failed.
+      def write(destination, chunk)
+        destination&.write(chunk)
+        destination
+      rescue IOError, SystemCallError
+        nil
+      end
+
+      # INT and TERM reach the child, and the CLI waits for it rather than leaving it orphaned. On
+      # Windows the console already delivers Ctrl-C to the manager, and Process.kill cannot send
+      # it, so there the CLI only notes the interruption and waits. Ctrl-Break ends the CLI
+      # outright: Ruby has no SIGBREAK to trap. The marker and the manager's pid record then
+      # keep the next install and the engine safe, as after any killed install.
+      def forward_signals(pid, interrupted)
+        SIGNALS.to_h do |signal|
+          handler = Signal.trap(signal) do
+            interrupted << signal
+            Process.kill(signal, pid) unless Gem.win_platform?
+          rescue Errno::ESRCH
+            nil
+          end
+          [signal, handler]
+        end
+      end
+
+      # Seconds a failed manager waits, on Windows, for the CLI's Ctrl-C handler.
+      GRACE = 0.5
+
+      # On Windows Ctrl-C reaches the manager and the CLI alike, and the manager can exit before the
+      # CLI's handler has run, so a failed manager waits a moment for it: an interrupted install is
+      # then reported as one, not as a failed manager. A sleep lets a pending handler run.
+      def await_interrupt(status, interrupted)
+        return if status.success? || !interrupted.empty? || !Gem.win_platform?
+
+        deadline = now + GRACE
+        sleep 0.01 while interrupted.empty? && now < deadline
+      end
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      # An interrupted install stops, however the manager ended: on Windows it exits with a status,
+      # not a signal, and may even exit 0, and Ctrl-C still means stop before verifying anything.
+      def check(status, manager, args, output, interrupted = nil)
+        return status if status.success? && !interrupted
+
+        command = [manager, *args].join(' ')
+        error = if status.signaled? || interrupted
+                  Error.new('PSM-E-INTERRUPTED', command:,
+                                                 details: { signal: status.termsig || interrupted })
+                else
+                  Error.new('PSM-E-NATIVE', command:, status: status.exitstatus,
+                                            details: { exitStatus: status.exitstatus })
+                end
+        error.output = output
+        raise error
+      end
+    end
+  end
+end