ace-lab 0.13.1 → 0.14.1

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require "fileutils"
+require "pathname"
+
+module Ace
+  module Lab
+    module Molecules
+      # Shared extension-projection primitives (task 8xs.t.pu0.0): the
+      # ONE place that knows how the installed gem's handbook/extensions
+      # tree is located, enumerated, and projected safely — used by both
+      # ExtensionProvisioner (convergence) and Verify (readiness), so
+      # the two can never drift.
+      module ExtensionProjection
+        RECEIPT_NAME = ".ace-lab-extension-projection.json"
+
+        module_function
+
+        # The installed gem's own tree at the EXACT declared version.
+        # @return [String, nil] the handbook/extensions directory or nil
+        #   when the gem (or its extensions tree) is not installed
+        def gem_source_root(gem_home, name, version)
+          candidate = File.join(gem_home, "gems", "#{name}-#{version}")
+          extensions = File.join(candidate, "handbook", "extensions")
+          File.directory?(extensions) ? extensions : nil
+        end
+
+        # Relative path → absolute source file for every file under the
+        # gem's handbook/extensions tree (e.g. "ace-wake/index.js").
+        # @return [Hash<String, String>]
+        def source_files(source_root)
+          Dir.glob(File.join(source_root, "**", "*")).select { |path| File.file?(path) }
+            .to_h { |path| [path.delete_prefix("#{source_root}/"), path] }
+        end
+
+        # Resolve and fully validate a projection destination before
+        # anything is written or verified (the provider_syncer
+        # validate_projection_destination posture): every path
+        # component under the projection directory must be a directory
+        # or creatable — a symlinked component could redirect the
+        # write outside the extensions directory, so it is refused.
+        # @param output_dir [String] manifest-declared extension dir
+        # @param relative_path [String] receipt-relative file path
+        # @return [String] the validated absolute destination
+        # @raise [Ace::Lab::Error] invalid or escaping destination
+        def validate_destination!(output_dir, relative_path)
+          segments = relative_path.to_s.split(File::SEPARATOR)
+          if segments.empty? || segments.any? { |segment| segment.empty? || segment == "." || segment == ".." }
+            raise Ace::Lab::Error, "cannot project #{relative_path.inspect}: invalid destination path"
+          end
+
+          begin
+            current = Pathname.new(File.realpath(output_dir))
+          rescue Errno::ENOENT
+            # the projection directory itself does not exist yet — no
+            # component below it can escape
+            return File.join(output_dir, *segments)
+          end
+          segments.each_with_index do |segment, index|
+            current = current.join(segment)
+            if File.symlink?(current.to_s)
+              raise Ace::Lab::Error,
+                "cannot project #{relative_path} into #{output_dir}: a symlinked path component " \
+                  "would escape the projection directory"
+            end
+            # The FINAL segment is the file itself — only intermediate
+            # components must be directories (compare by position, not
+            # value: "a/a/index.js" repeats "a" legitimately).
+            next if index == segments.size - 1
+
+            if !current.directory? && File.exist?(current.to_s)
+              raise Ace::Lab::Error,
+                "cannot project #{relative_path} into #{output_dir}: #{current} exists and is not a directory"
+            end
+          end
+          if File.directory?(current.to_s)
+            # Receipt ownership of a path never authorizes writing
+            # through a directory planted at that path — cp would
+            # reinterpret the destination as a container.
+            raise Ace::Lab::Error,
+              "cannot project #{relative_path} into #{output_dir}: #{current} exists and is a directory"
+          end
+          current.to_s
+        rescue Errno::ENOENT
+          raise Ace::Lab::Error, "cannot project #{relative_path} into #{output_dir}: projection directory vanished"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "extension_projection"
+require "etc"
+require "fileutils"
+require "json"
+
+module Ace
+  module Lab
+    module Molecules
+      # Projects harness extension assets from an INSTALLED gem's exact
+      # declared version into the manifest-declared extension directory
+      # (task 8xs.t.pu0.0): the manual host-lane copy of the ace-wake
+      # extension is replaced by a converged, repeatable projection.
+      #
+      # Source of truth is the installed gem tree itself —
+      # `<gem_home>/gems/<name>-<version>/handbook/extensions` — so the
+      # projection always matches the exact version the manifest
+      # declared (never the checkout, never a newer gem beside it).
+      # Each target directory carries a receipt
+      # (`.ace-lab-extension-projection.json`) recording the producing
+      # gem, version and file list; ONLY receipt-listed files are ever
+      # removed, so user-authored extensions in the same directory are
+      # never touched. The report names the version that WAS loaded
+      # before this run (`loaded_version`) and whether the projection
+      # changed (`restart_required`) — a changed projection means the
+      # running harness processes still hold the OLD extension; the
+      # installer REPORTS the restart need, it never restarts an
+      # executor on its own.
+      class ExtensionProvisioner
+        RECEIPT_NAME = ExtensionProjection::RECEIPT_NAME
+        FILE_MODE = 0o644
+        DIR_MODE = 0o755
+
+        # @param gem_home [String] target runtime the gems were
+        #   converged into
+        # @param dry_run [Boolean] predict without writing
+        # @param account_lookup [Proc, nil] passwd lookup seam for the
+        #   declared accounts (projection ownership convergence)
+        def initialize(gem_home:, dry_run: false, account_lookup: nil)
+          @gem_home = gem_home
+          @dry_run = dry_run
+          @account_lookup = account_lookup || method(:lookup_passwd)
+        end
+
+        # @param extensions [Array<Hash>] normalized manifest gemset
+        #   extensions entries ({"gem" =>, "path" =>, "account" =>})
+        # @param gems [Array<Hash>] declared gem set (name/version)
+        # @return [Array<Hash>] one report per entry:
+        #   {extension:, gem:, version:, path:, account:, status:,
+        #    loaded_version:, restart_required:, files:, message:}
+        def call(extensions:, gems:)
+          extensions.map do |entry|
+            converge(entry, gems)
+          end
+        end
+
+        private
+
+        def converge(entry, gems)
+          declared = gems.find { |gem| gem["name"] == entry["gem"] }
+          version = declared && declared["version"]
+          source = version && ExtensionProjection.gem_source_root(@gem_home, entry["gem"], version)
+
+          if source.nil?
+            # Fresh-lab dry run (the gem phase predicts would_install
+            # for the same missing gem): predict the projection the
+            # converged gem would feed instead of reporting a failure
+            # the wet run would not produce.
+            if @dry_run
+              return entry_report(entry, version, "would_project", nil, true, [])
+            end
+            return failed(entry, version,
+              "gem '#{entry["gem"]}' is not installed in runtime '#{@gem_home}' at declared " \
+                "version '#{version}'; converge the gemset first (ace-lab install)")
+          end
+
+          expected = ExtensionProjection.source_files(source)
+          if expected.empty?
+            return failed(entry, version,
+              "gem '#{entry["gem"]}' #{version} carries no handbook/extensions tree")
+          end
+
+          output_dir = entry["path"]
+          escape = projection_escape_reason(output_dir, expected.keys)
+          return failed(entry, version, escape) if escape
+
+          receipt = read_receipt(output_dir)
+          loaded_version = receipt && receipt["gem"] == entry["gem"] ? receipt["version"] : nil
+
+          changed = projection_changed?(output_dir, expected, receipt, version)
+          if !changed
+            converge_modes(output_dir, expected, entry)
+            return entry_report(entry, version, "unchanged", loaded_version, false,
+              receipt ? receipt.fetch("files") : expected.keys)
+          end
+          # dry-run predicts the projection (restart needed) without
+          # writing anything
+          return entry_report(entry, version, "projected", loaded_version, true, expected.keys) if @dry_run
+
+          project(output_dir, expected, entry, version)
+          entry_report(entry, version, "projected", loaded_version, true, expected.keys)
+        rescue SystemCallError => e
+          failed(entry, version,
+            "extension projection into '#{output_dir}' failed (#{e.class.name}); " \
+              "rerun ace-lab prepare with sudo or adjust ownership manually")
+        end
+
+        def failed(entry, version, message)
+          entry_report(entry, version, "failed", nil, false, [])
+            .merge("message" => message)
+        end
+
+        def entry_report(entry, version, status, loaded_version, restart_required, files)
+          {"extension" => entry["gem"], "gem" => entry["gem"], "version" => version,
+           "path" => entry["path"], "account" => entry["account"], "status" => status,
+           "loaded_version" => loaded_version, "restart_required" => restart_required,
+           "files" => files, "message" => nil}
+        end
+
+        # Refuse a destination that escapes the projection directory
+        # through a symlinked component BEFORE anything is written (the
+        # provider_syncer validate_projection_destination posture).
+        def projection_escape_reason(output_dir, relative_paths)
+          relative_paths.each { |relative| ExtensionProjection.validate_destination!(output_dir, relative) }
+          nil
+        rescue Ace::Lab::Error => e
+          e.message
+        end
+
+        # A projection changed when the receipt is absent, names a
+        # different version, lists a different file set, or any
+        # expected file's content differs on disk.
+        def projection_changed?(output_dir, expected, receipt, version)
+          return true if receipt.nil?
+          return true if receipt["version"] != version
+          return true unless receipt.fetch("files", []).sort == expected.keys.sort
+
+          expected.any? do |relative, source|
+            target = File.join(output_dir, relative)
+            !File.file?(target) || !FileUtils.compare_file(source, target)
+          end
+        end
+
+        def project(output_dir, expected, entry, version)
+          FileUtils.mkdir_p(output_dir)
+          expected.each do |relative, source|
+            target = File.join(output_dir, relative)
+            FileUtils.mkdir_p(File.dirname(target))
+            FileUtils.cp(source, target)
+          end
+
+          # Only receipt-owned files no longer in the projection are
+          # removed; a removal that fails keeps its receipt entry so a
+          # later run retries it (user-authored extensions are never
+          # touched).
+          previous = read_receipt(output_dir)&.fetch("files", []) || []
+          retained = previous.filter_map do |relative|
+            target = File.join(output_dir, relative)
+            next relative if expected.key?(relative)
+
+            FileUtils.rm_f(target)
+            File.exist?(target) ? relative : nil
+          end
+
+          write_receipt(output_dir, entry, version, (expected.keys + retained).sort)
+          converge_modes(output_dir, expected, entry)
+        end
+
+        # Mode/ownership convergence (the key-provisioner posture):
+        # projected files carry owner read/write plus world read
+        # (0644), projection directories 0755, and both are owned by
+        # the declared account whenever the passwd lookup resolves it —
+        # so the target executor can always read its extensions.
+        def converge_modes(output_dir, expected, entry)
+          account = @account_lookup.call(entry["account"])
+          targets = expected.keys.map { |relative| File.join(output_dir, relative) }
+          targets << File.join(output_dir, RECEIPT_NAME)
+          targets.each do |target|
+            next unless File.file?(target)
+
+            FileUtils.chmod(FILE_MODE, target)
+            FileUtils.chown(account.uid, account.gid, target) if account
+          end
+          root = File.realpath(output_dir)
+          dirs = expected.keys.filter_map do |relative|
+            File.dirname(File.join(root, relative)) if relative.include?(File::SEPARATOR)
+          end.uniq
+          until dirs.empty?
+            dir = dirs.pop
+            FileUtils.chmod(DIR_MODE, dir)
+            FileUtils.chown(account.uid, account.gid, dir) if account
+            parent = File.dirname(dir)
+            dirs << parent if dir != root && parent.start_with?("#{root}/") && !dirs.include?(parent) && parent != root
+          end
+        end
+
+        def write_receipt(output_dir, entry, version, files)
+          document = {
+            "gem" => entry["gem"], "version" => version,
+            "projected_at" => Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "files" => files.sort
+          }
+          File.write(File.join(output_dir, RECEIPT_NAME), JSON.pretty_generate(document))
+        end
+
+        def read_receipt(output_dir)
+          path = File.join(output_dir, RECEIPT_NAME)
+          return nil unless File.file?(path)
+
+          document = JSON.parse(File.read(path))
+          document.is_a?(Hash) ? document : nil
+        rescue JSON::ParserError, Errno::EACCES
+          nil
+        end
+
+        def lookup_passwd(username)
+          Etc.getpwnam(username)
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "rbconfig"
+require "find"
+
+module Ace
+  module Lab
+    module Molecules
+      # Installed specifications select identity; cached gem archives own payload
+      # membership (installed gemspecs omit files). No recursive runtime sweep.
+      class GemPayloadPermissions
+        class Error < StandardError; end
+        INVENTORY = <<~'CODE'
+          require 'json'
+          require 'rubygems'
+          require 'rubygems/package'
+          home = ARGV.shift
+          Gem.use_paths(home)
+          queue = [Gem::Specification.find_by_name(ARGV.shift, ARGV.shift)]
+          dry_run = ARGV.shift == "dry-run"
+          seen = {}; rows = []
+          until queue.empty?
+            spec = queue.shift
+            next if seen[spec.full_name]
+            seen[spec.full_name] = true
+            unless spec.default_gem?
+              cache = File.join(home, "cache", "#{spec.full_name}.gem")
+              unless File.file?(cache) && !File.symlink?(cache) && !File.symlink?(File.dirname(cache))
+                puts JSON.generate(error: "installed gem payload cache missing or symlinked: #{cache}")
+                exit 1
+              end
+              package = Gem::Package.new(cache)
+              package.verify
+              unless package.spec.full_name == spec.full_name
+                puts JSON.generate(error: "installed gem payload cache identity mismatch: #{cache}")
+                exit 1
+              end
+              rows << {root: spec.full_gem_path, spec: spec.loaded_from,
+                files: package.contents, executables: spec.executables,
+                bindir: spec.bindir, extension: spec.extensions.empty? ? nil : spec.extension_dir}
+            end
+            spec.runtime_dependencies.each do |dep|
+              begin
+                queue << dep.to_spec
+              rescue Gem::MissingSpecError
+                # Convergence already predicts installing absent dependencies.
+                # Validate the existing payload; do not invent future files.
+                raise unless dry_run
+              end
+            end
+          end
+          puts JSON.generate(rows)
+        CODE
+
+        def initialize(gem_home:, dry_run:, privileged:)
+          @declared_home = File.expand_path(gem_home)
+          raise Error, "gem runtime is a symlink" if File.symlink?(@declared_home)
+          @home = File.realpath(@declared_home)
+          @dry_run, @privileged = dry_run, privileged
+        end
+
+        def call(name:, version:)
+          # Default Ruby gems need no mutation in this runtime. With no local
+          # specifications there cannot be any owned installed payload here.
+          return [] unless File.directory?(File.join(@home, "specifications"))
+
+          env = ENV.keys.grep(/\ABUNDLE/).to_h { |key| [key, nil] }
+          env.merge!("RUBYOPT" => nil, "RUBYLIB" => nil, "GEM_HOME" => @home, "GEM_PATH" => @home)
+          out, _err, status = Open3.capture3(env, RbConfig.ruby, "-e", INVENTORY, @home, name, version, @dry_run ? "dry-run" : "apply")
+          unless status.success?
+            detail = begin
+              JSON.parse(out)["error"]
+            rescue JSON::ParserError
+              nil
+            end
+            raise Error, detail || "could not inventory installed gem payload #{name} #{version}"
+          end
+
+          converge(JSON.parse(out))
+        rescue SystemCallError, JSON::ParserError => e
+          raise Error, "gem payload permission convergence failed (#{e.class})"
+        end
+
+        def converge(rows)
+          paths = {}
+          executables = []
+          rows.each do |row|
+            root = validate(row.fetch("root"))
+            raise Error, "invalid installed gem root" unless File.dirname(root) == File.join(@home, "gems")
+            spec = validate(row.fetch("spec"))
+            raise Error, "invalid installed gem specification" unless File.dirname(spec) == File.join(@home, "specifications")
+            add(paths, spec)
+            row.fetch("files").each { |file| add(paths, payload_path(root, file)) }
+            row.fetch("executables").each do |exe|
+              raise Error, "invalid gem executable" unless File.basename(exe) == exe && !%w[. ..].include?(exe)
+              [payload_path(root, File.join(row.fetch("bindir"), exe)), File.join(@home, "bin", exe)].each do |path|
+                add(paths, path)
+                executables << validate(path)
+              end
+            end
+            if (extension = row["extension"])
+              extension = validate(extension)
+              raise Error, "invalid gem extension directory" unless
+                extension.start_with?(File.join(@home, "extensions") + "/") &&
+                File.basename(extension) == File.basename(root)
+              Find.find(extension) do |path|
+                validate(path)
+                add(paths, path)
+              end
+            end
+          end
+          changes = paths.filter_map do |path, stat|
+            desired = stat.directory? || executables.include?(path) || (stat.mode & 0o111).positive? ? 0o755 : 0o644
+            owner_change = @privileged && (stat.uid != 0 || stat.gid != 0)
+            next if (stat.mode & 0o7777) == desired && !owner_change
+            {"path" => path, "mode" => desired, "owner_change" => owner_change,
+             "status" => @dry_run ? "would_normalize" : "normalized"}
+          end
+          # Inventory validation is complete before the first mutation.
+          unless @dry_run
+            changes.each do |change|
+              path = validate(change.fetch("path"))
+              current = File.lstat(path)
+              original = paths.fetch(path)
+              raise Error, "gem payload changed during permission convergence: #{path}" unless
+                current.ino == original.ino && current.dev == original.dev && !current.symlink?
+              File.chown(0, 0, path) if change["owner_change"]
+              File.chmod(change.fetch("mode"), path)
+            end
+          end
+          changes
+        end
+
+        private
+
+        def payload_path(root, relative)
+          path = File.expand_path(relative, root)
+          raise Error, "gem payload escapes specification root" unless path.start_with?(root + "/")
+          path
+        end
+
+        def validate(path)
+          path = File.expand_path(path)
+          if path == @declared_home || path.start_with?(@declared_home + "/")
+            path = @home + path.delete_prefix(@declared_home)
+          end
+          raise Error, "gem payload escapes declared runtime: #{path}" unless path == @home || path.start_with?(@home + "/")
+          cursor = path
+          loop do
+            stat = File.lstat(cursor)
+            raise Error, "gem payload symlink refused: #{cursor}" if stat.symlink?
+            raise Error, "unsupported gem payload: #{cursor}" unless stat.file? || stat.directory?
+            break if cursor == @home
+            cursor = File.dirname(cursor)
+          end
+          path
+        end
+
+        def add(paths, path)
+          path = validate(path)
+          loop do
+            stat = File.lstat(path)
+            raise Error, "hardlinked gem payload refused: #{path}" if stat.file? && stat.nlink > 1
+            paths[path] = stat
+            break if path == @home
+            path = File.dirname(path)
+          end
+        end
+      end
+    end
+  end
+end