ace-lab 0.9.0 → 0.13.1

data/lib/ace/lab/molecules/gemset_provisioner.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require "open3"
+require "fileutils"
+
+module Ace
+  module Lab
+    module Molecules
+      # Idempotently converges the install manifest's declared gem set
+      # into the declared target runtime (GEM_HOME; gad.2 gap #1, owner
+      # spec 8xg.t.sbz.7): a gem whose exact declared version is already
+      # present is a no-op (`exists`), a missing gem is installed
+      # (`installed`), a gem present at a different version is updated
+      # (the declared version installed alongside — RubyGems keeps
+      # versions side by side; verify judges the declared set). Probes
+      # and installs run the `gem` executable with GEM_HOME/GEM_PATH
+      # pinned to the target runtime through the SAME argv runner seam
+      # the other prepare molecules use (POSIX `env`, never a shell
+      # string, ADR-031) — so the lab runtime stays isolated from the
+      # installer's own gems and the runner stays injectable for
+      # dry-run and tests. The runtime directory itself is created only
+      # with administrator privileges (the same seam
+      # AccountProvisioner gates creation with) and a symlink or
+      # non-directory at the declared path is refused (the
+      # DirectoryProvisioner takeover posture). Every failure is a
+      # classified per-gem item with an actionable message; command
+      # failures surface only the exit status and the first stderr line.
+      class GemsetProvisioner
+        attr_reader :runner, :privileged, :dry_run
+
+        def initialize(runner: nil, privileged: nil, dry_run: false)
+          @runner = runner || method(:run_argv)
+          @privileged = privileged || -> { Process.euid.zero? }
+          @dry_run = dry_run
+        end
+
+        # @param runtime [Hash] normalized manifest gemset section
+        #   ({"gem_home" => path, "gems" => [{"name" =>, "version" =>}]})
+        # @return [Array<Hash>] one report per declared gem:
+        #   {name:, version:, gem_home:, status:, message:}
+        def call(runtime:)
+          gems = runtime["gems"]
+          return [] if gems.empty?
+
+          gem_home = runtime["gem_home"]
+          runtime_failure = ensure_runtime(gem_home)
+          gems.map do |gem|
+            if runtime_failure
+              base(gem, gem_home).merge("status" => "failed", "message" => runtime_failure)
+            else
+              converge(base(gem, gem_home), gem, gem_home)
+            end
+          end
+        end
+
+        # Public READ-ONLY probe (L8.5): the local versions of `name`
+        # inside the target runtime — the exact probe convergence runs,
+        # exposed so the readiness verifier reuses the same logic
+        # instead of reimplementing it (the two can never drift).
+        # @param name [String] gem name
+        # @param gem_home [String] target runtime (GEM_HOME)
+        # @return [Array(Symbol, Object)] [:ok, versions],
+        #   [:unknown, message] (no `gem` executable — offline posture)
+        #   or [:failed, message]
+        def runtime_versions(name:, gem_home:)
+          result = @runner.call(runtime_argv(gem_home,
+            ["gem", "list", name, "--exact", "--local"]))
+          return [:unknown, "gem not found in PATH; install RubyGems and rerun ace-lab prepare"] if result["status"] == "enoent"
+          return [:failed, command_failure("gem list", result)] unless result["status"] == "ok"
+
+          versions = parse_versions(result["out"], name)
+          if versions.nil?
+            return [:failed, "could not determine installed versions of gem '#{name}' from " \
+              "'gem list' output; rerun ace-lab prepare"]
+          end
+
+          [:ok, versions]
+        end
+
+        private
+
+        def base(gem, gem_home)
+          {"name" => gem["name"], "version" => gem["version"], "gem_home" => gem_home}
+        end
+
+        # One runtime failure fails every declared gem as a dependency
+        # (the keys-need-accounts posture): convergence is never
+        # attempted against a runtime that did not prepare.
+        def ensure_runtime(gem_home)
+          stat = lstat(gem_home)
+          return "gem runtime '#{gem_home}' is a symbolic link; refusing" if stat&.symlink?
+          return "gem runtime '#{gem_home}' exists but is not a directory; refusing" if stat && !stat.directory?
+          return nil if stat
+
+          unless @privileged.call
+            return "creating gem runtime '#{gem_home}' requires administrator privileges; " \
+              "rerun ace-lab prepare with sudo or create the directory manually"
+          end
+          return nil if @dry_run # prediction: creation would succeed
+
+          FileUtils.mkdir_p(gem_home)
+          nil
+        rescue Errno::EPERM, Errno::EACCES
+          "insufficient permissions while preparing gem runtime '#{gem_home}'; " \
+            "rerun ace-lab prepare with sudo or adjust ownership manually"
+        rescue SystemCallError => e
+          "gem runtime '#{gem_home}' could not be created (#{e.class.name}); rerun ace-lab prepare"
+        end
+
+        def converge(base, gem, gem_home)
+          kind, versions_or_message = runtime_versions(name: gem["name"], gem_home: gem_home)
+          # Prepare's fail-closed posture: an unprobeable runtime (no
+          # `gem` executable — the :unknown probe kind) fails the item in
+          # wet AND dry runs, exactly as the wet run would fail; verify
+          # maps the same probe kind to its offline `unknown` posture.
+          return base.merge("status" => "failed", "message" => versions_or_message) if kind != :ok
+
+          versions = versions_or_message
+          return base.merge("status" => "exists", "message" => nil) if versions.include?(gem["version"])
+
+          status = versions.empty? ? "install" : "update"
+          return base.merge("status" => "would_#{status}", "message" => nil) if @dry_run
+
+          failure = install(gem, gem_home)
+          return base.merge("status" => "failed", "message" => failure) if failure
+
+          if status == "install"
+            base.merge("status" => "installed", "message" => nil)
+          else
+            base.merge("status" => "updated", "message" => nil)
+          end
+        end
+
+        # Installs the EXACT declared version into the runtime. Sources
+        # are the gem command's own defaults — fetching from the
+        # configured gem source is provisioning network access, the same
+        # envelope as cloning a declared repository remote.
+        # @return [String, nil] the classified failure, nil on success
+        def install(gem, gem_home)
+          result = @runner.call(runtime_argv(gem_home,
+            ["gem", "install", gem["name"], "--version", gem["version"], "--no-document"]))
+          return nil if result["status"] == "ok"
+
+          command_failure("gem install", result)
+        end
+
+        # Environment variables that would drag the INVOKING process's
+        # bundler context into the gem subprocess: RUBYOPT carries
+        # `-rbundler/setup` under `bundle exec ace-lab` (the documented
+        # invocation), RubyGems auto-requires ENV["BUNDLER_SETUP"]
+        # (rubygems.rb), and the BUNDLE_*/BUNDLER_* vars re-bind bundler
+        # when it loads — any of which overrides the pinned paths with
+        # the invoking bundle's load paths. The lab runtime must stay
+        # isolated from the installer's gems, its bundle included.
+        BUNDLER_ENV_KEYS = %w[RUBYOPT RUBYLIB BUNDLER_SETUP BUNDLE_BIN_PATH
+          BUNDLE_GEMFILE BUNDLER_VERSION BUNDLE_BUNDLER_VERSION].freeze
+
+        private_constant :BUNDLER_ENV_KEYS
+
+        # GEM_HOME/GEM_PATH are pinned through the POSIX `env` command so
+        # the argv-array runner seam stays unchanged and the subprocess
+        # sees ONLY the target runtime.
+        def runtime_argv(gem_home, argv)
+          ["env"] +
+            BUNDLER_ENV_KEYS.flat_map { |key| ["-u", key] } +
+            ["GEM_HOME=#{gem_home}", "GEM_PATH=#{gem_home}"] + argv
+        end
+
+        # `gem list <name> --exact --local` prints one `name (v1, v2)`
+        # line when the name is present in the runtime and nothing when
+        # it is absent. A present-but-unparseable line is a failed probe
+        # (nil, fail closed), never a guessed empty list.
+        def parse_versions(out, name)
+          line = out.lines.find { |candidate| candidate.start_with?("#{name} ") }
+          return [] if line.nil?
+
+          match = line.chomp.match(/\A#{Regexp.escape(name)} \((.*)\)\z/)
+          return nil if match.nil?
+
+          match[1].split(",").map(&:strip)
+        end
+
+        # Classified one-line command failure: status plus the first
+        # stderr line only — never command output bodies.
+        def command_failure(command, result)
+          case result["status"]
+          when "enoent"
+            return "#{command} failed: gem not found in PATH; install RubyGems and rerun ace-lab prepare"
+          when "exec_failed"
+            return "#{command} failed: could not be executed (#{result["err"]}); rerun ace-lab prepare"
+          end
+
+          message = "#{command} failed (#{exit_detail(result["status"])})"
+          line = result["err"].to_s.lines.map(&:strip).reject(&:empty?).first
+          message = "#{message}: #{line}" if line
+          "#{message}; rerun ace-lab prepare (with sudo when the runtime is not writable)"
+        end
+
+        def exit_detail(status)
+          status.is_a?(Integer) ? "exit #{status}" : status.to_s
+        end
+
+        def lstat(path)
+          File.lstat(path)
+        rescue Errno::ENOENT, Errno::ENOTDIR
+          nil
+        end
+
+        def run_argv(argv)
+          out, err, status = Open3.capture3(*argv)
+          {"status" => status.success? ? "ok" : (status.exitstatus || "signal #{status.termsig}"),
+           "out" => out, "err" => err}
+        rescue Errno::ENOENT
+          {"status" => "enoent", "out" => "", "err" => ""}
+        rescue SystemCallError => e
+          {"status" => "exec_failed", "out" => "", "err" => e.class.name}
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/grant_provisioner.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "grant_resolver"
+require "yaml"
+require "date"
+require "fileutils"
+
+module Ace
+  module Lab
+    module Molecules
+      # Writes the trusted-tier principal grants (task 8xg.t.sbz.7.2,
+      # L8.3): the `principals` section of the deployment-owned
+      # authorization document at the fixed AUTHORIZATION_PATH — the only
+      # place GrantResolver reads grants from, so `ace-lab projects` /
+      # `ace-overseer projects` see the installed projects with no
+      # read-side change.
+      #
+      # The installer owns this configuration, but never overwrites a
+      # foreign lab: a document whose principals grant projects outside
+      # the manifest's declared set is foreign (`foreign_grants?`, used
+      # by the installer as a before-any-mutation guard), and a manifest
+      # that would REMOVE an existing grant is refused — grants only
+      # grow. All other sections of the document are preserved
+      # untouched. Writes are atomic (temp file + rename) with mode
+      # 0644, mirroring the registry's write discipline.
+      class GrantProvisioner
+        STATUS_DRY = {"created" => "would_create", "updated" => "would_update"}.freeze
+
+        # @param resolver [Object] trusted-read seam (defaults to
+        #   GrantResolver; injected in tests)
+        # @param authorization_path [String] trusted grants location
+        def initialize(resolver: GrantResolver, authorization_path: Ace::Lab.authorization_path)
+          @resolver = resolver
+          @authorization_path = authorization_path
+        end
+
+        # @return [String] the trusted grants location this molecule
+        #   converges — install threads it into the final Verify stage.
+        attr_reader :authorization_path
+
+        # Foreign-lab detection: an existing trusted document that grants
+        # projects outside the manifest's declared set belongs to a
+        # different lab and must never be overwritten by this install.
+        #
+        # @param declared_projects [Array<String>] project ids declared
+        #   by the install manifest
+        # @return [String, nil] conflict message, nil when compatible
+        # @raise [Ace::Lab::InvalidConfigurationError] the trusted
+        #   document exists but fails verification or parsing — a lab
+        #   the installer cannot reason about is treated as foreign
+        def foreign_grants?(declared_projects)
+          document = read_document
+          return nil if document.nil?
+
+          (document["principals"] || {}).each do |principal, policy|
+            foreign = granted_projects(policy) - declared_projects
+            next if foreign.empty?
+
+            return "trusted authorization file #{@authorization_path} already grants " \
+              "project(s) #{foreign.sort.join(', ')} to principal '#{principal}' — this lab's " \
+              "manifest does not declare them; refusing to overwrite a foreign lab"
+          end
+          nil
+        end
+
+        # Idempotently converge the principal grants.
+        #
+        # @param desired [Hash] principal => project ids (normalized
+        #   manifest grants)
+        # @param declared_projects [Array<String>] manifest project ids
+        # @param dry_run [Boolean]
+        # @return [Hash] {path:, status:, principals:, message:} where
+        #   status is created / updated / exists / would_create /
+        #   would_update / failed and principals carries one entry per
+        #   desired principal
+        def call(desired:, declared_projects:, dry_run: false)
+          # Exposed on every report/failure so the grants section of the
+          # install JSON has one uniform schema (the top-level report
+          # also carries it; consumers may read either).
+          @dry_run = dry_run
+          document = begin
+            read_document
+          rescue Ace::Lab::InvalidConfigurationError => e
+            return failure(e.message)
+          end
+          existing = document ? (document["principals"] || {}) : {}
+
+          removal = desired.filter_map do |principal, projects|
+            granted = existing.key?(principal) ? granted_projects(existing[principal]) : []
+            next if (granted - projects).empty?
+
+            "principal '#{principal}' is already granted project(s) " \
+              "#{(granted - projects).sort.join(', ')} which this manifest does not grant; " \
+              "refusing to remove trusted grants — edit #{@authorization_path} manually"
+          end
+          return failure(removal.join("; ")) unless removal.empty?
+
+          merged, statuses = merge_principals(existing, desired)
+
+          # An empty grants manifest over an absent document is a no-op
+          # (review r1): nothing is granted, so no empty authorization
+          # document is created.
+          if document.nil? && merged.empty?
+            return report("skipped", {}, "no grants declared and no trusted document present; " \
+              "nothing to write", existing, desired)
+          end
+
+          aggregate = if statuses.values.include?("created") && existing.empty?
+            "created"
+          elsif statuses.values.any? { |status| %w[created updated].include?(status) }
+            "updated"
+          else
+            "exists"
+          end
+
+          # Dry-run parity: per-principal predictions mirror the wet
+          # statuses (an already-converged principal stays `exists`).
+          statuses = statuses.transform_values { |status| STATUS_DRY.fetch(status, status) } if dry_run
+
+          return report(STATUS_DRY.fetch(aggregate, aggregate), statuses, nil, existing,
+            desired) if dry_run
+
+          # Converged: the merged principals deep-equal the parsed
+          # existing mapping, so the write is skipped — the trusted
+          # document (admin-authored comments included) stays
+          # byte-identical instead of being round-tripped through YAML
+          # (review r1). An absent document is always created.
+          if document && merged == existing
+            return report(aggregate, statuses, nil, existing, desired)
+          end
+
+          write_failure = persist(document, merged)
+          return write_failure if write_failure
+
+          report(aggregate, statuses, nil, existing, desired)
+        rescue Ace::Lab::InvalidConfigurationError => e
+          failure(e.message)
+        end
+
+        private
+
+        # Per-principal convergence: a principal with no grants yet is
+        # `created`, one gaining projects is `updated`, an already
+        # fully-granted one is `exists`. Principals absent from the
+        # manifest are carried over unchanged (never removed).
+        def merge_principals(existing, desired)
+          merged = existing.each_with_object({}) do |(principal, policy), acc|
+            acc[principal] = {"projects" => granted_projects(policy)}
+          end
+          statuses = desired.each_with_object({}) do |(principal, projects), acc|
+            granted = merged.key?(principal) ? merged[principal]["projects"] : []
+            acc[principal] = if granted.empty?
+              "created"
+            elsif (projects - granted).empty?
+              "exists"
+            else
+              "updated"
+            end
+            merged[principal] = {"projects" => (granted | projects).sort}
+          end
+          [merged, statuses]
+        end
+
+        # Atomic write preserving every other section of the document.
+        # Returns nil on success, a failed report otherwise.
+        def persist(document, merged)
+          updated = document ? deep_copy(document) : {}
+          updated["principals"] = merged
+
+          dir = File.dirname(@authorization_path)
+          tmp = File.join(dir, ".authorization.yml.tmp.#{Process.pid}")
+          begin
+            FileUtils.mkdir_p(dir)
+            File.write(tmp, YAML.dump(updated))
+            File.chmod(0o644, tmp)
+            File.rename(tmp, @authorization_path)
+          rescue SystemCallError, IOError => e
+            File.delete(tmp) if File.exist?(tmp)
+            return failure("writing #{@authorization_path} failed: #{e.message}")
+          end
+          nil
+        end
+
+        def report(status, statuses, message, existing, desired)
+          {
+            "path" => @authorization_path,
+            "status" => status,
+            "principals" => statuses,
+            "message" => message,
+            # Always present (empty when nothing is carried over) so
+            # JSON consumers see a stable schema (review r1).
+            "kept" => existing.keys - desired.keys,
+            # Same key set as the gated grants failure in the install
+            # report — one uniform grants-section schema (review L8.4).
+            "dry_run" => @dry_run ? true : false
+          }
+        end
+
+        def failure(message)
+          # `kept` is present (empty) like in every report so JSON
+          # consumers see one stable schema — a failure merges
+          # nothing, so nothing is carried over (resume/verification
+          # readers, tasks 8xg.t.sbz.7.3/.7.4).
+          {"path" => @authorization_path, "status" => "failed", "principals" => {},
+            "message" => message, "kept" => [], "dry_run" => @dry_run ? true : false}
+        end
+
+        # Read and parse the trusted document through the same
+        # fail-closed verification every grant reader uses.
+        # @return [Hash, nil] parsed document, nil when absent
+        # @raise [Ace::Lab::InvalidConfigurationError]
+        def read_document
+          content = @resolver.read_verified(@authorization_path)
+          return nil if content.nil?
+
+          document = begin
+            YAML.safe_load(content, permitted_classes: [Date], aliases: true)
+          rescue Psych::Exception
+            raise Ace::Lab::InvalidConfigurationError,
+              "#{@authorization_path} could not be parsed as YAML; refusing to overwrite"
+          end
+          unless document.is_a?(Hash)
+            raise Ace::Lab::InvalidConfigurationError,
+              "#{@authorization_path} must contain a YAML mapping; refusing to overwrite"
+          end
+          principals = document["principals"]
+          return document if principals.nil?
+
+          # Per-principal validation identical to the read side
+          # (GrantResolver.parse_grants): a malformed policy is refused
+          # with the classified error instead of silently rewritten,
+          # and principal names are stripped so a whitespace-padded
+          # existing principal cannot coexist with its stripped twin
+          # after a write (review r1).
+          document.merge("principals" =>
+            GrantResolver.validate_principals(principals, @authorization_path))
+        end
+
+        def granted_projects(policy)
+          policy.is_a?(Hash) && policy["projects"].is_a?(Array) ? policy["projects"] : []
+        end
+
+        def deep_copy(document)
+          YAML.safe_load(YAML.dump(document), permitted_classes: [Date], aliases: true)
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/grant_resolver.rb

@@ -113,6 +113,39 @@ module Ace
             end
           end
 
+          # Shared per-principal validation so the read side
+          # (`parse_grants`) and the installer's writer
+          # (`Molecules::GrantProvisioner`) cannot drift (review r1):
+          # principal names are stripped and each policy must be a
+          # mapping with a `projects` array of non-empty strings.
+          # Messages are value-free.
+          # @param principals [Object] parsed principals mapping
+          # @param path [String] trusted file location for messages
+          # @return [Hash] principal => {"projects" => stripped, uniq ids}
+          # @raise [Ace::Lab::InvalidConfigurationError]
+          def validate_principals(principals, path)
+            unless principals.is_a?(Hash)
+              raise Ace::Lab::InvalidConfigurationError,
+                "invalid lab configuration: trusted authorization file #{path} principals must be a mapping"
+            end
+
+            principals.map do |identity, policy|
+              unless identity.is_a?(String) && !identity.strip.empty?
+                raise Ace::Lab::InvalidConfigurationError,
+                  "invalid lab configuration: trusted authorization file #{path} principal name " \
+                  "must be a non-empty string"
+              end
+              unless policy.is_a?(Hash) && policy["projects"].is_a?(Array) &&
+                  policy["projects"].all? { |project| project.is_a?(String) && !project.strip.empty? }
+                raise Ace::Lab::InvalidConfigurationError,
+                  "invalid lab configuration: trusted authorization file #{path} principal projects " \
+                  "must be an array of non-empty strings"
+              end
+
+              [identity.strip, {"projects" => policy["projects"].map(&:strip).uniq}]
+            end.to_h
+          end
+
           private
 
           def verify_error(path)
@@ -183,29 +216,7 @@ module Ace
                 "invalid lab configuration: trusted authorization file #{path} must contain a YAML mapping"
             end
 
-            principals = document["principals"] || {}
-            unless principals.is_a?(Hash)
-              raise Ace::Lab::InvalidConfigurationError,
-                "invalid lab configuration: trusted authorization file #{path} principals must be a mapping"
-            end
-
-            validated = principals.map do |identity, policy|
-              unless identity.is_a?(String) && !identity.strip.empty?
-                raise Ace::Lab::InvalidConfigurationError,
-                  "invalid lab configuration: trusted authorization file #{path} principal name " \
-                  "must be a non-empty string"
-              end
-              unless policy.is_a?(Hash) && policy["projects"].is_a?(Array) &&
-                  policy["projects"].all? { |project| project.is_a?(String) && !project.strip.empty? }
-                raise Ace::Lab::InvalidConfigurationError,
-                  "invalid lab configuration: trusted authorization file #{path} principal projects " \
-                  "must be an array of non-empty strings"
-              end
-
-              [identity.strip, {"projects" => policy["projects"].map(&:strip).uniq}]
-            end
-
-            {"principals" => validated.to_h}
+            {"principals" => validate_principals(document["principals"] || {}, path)}
           rescue Psych::Exception
             raise Ace::Lab::InvalidConfigurationError,
               "invalid lab configuration: trusted authorization file #{path} could not be parsed as YAML"