ace-lab 0.9.0 → 0.13.1

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

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require "open3"
+require "etc"
+require "securerandom"
+
+module Ace
+  module Lab
+    module Molecules
+      # Idempotently ensures a lab account exists, per the trusted install
+      # manifest. Existing accounts are reported with their uid; missing
+      # accounts either fail with an actionable message (create: false, or
+      # creation without administrator privileges) or are created through
+      # the platform's own account tooling (darwin dscl / linux useradd),
+      # always with argv arrays (ADR-031) — never a shell string. Every
+      # failure message names the account and the remedy; command failures
+      # surface only the exit status and the first stderr line, never file
+      # content.
+      class AccountProvisioner
+        DEFAULT_SHELL = "/bin/zsh"
+        DARWIN_PRIMARY_GROUP = 20
+
+        attr_reader :runner, :account_lookup, :privileged, :platform, :dry_run
+
+        def initialize(runner: nil, account_lookup: nil, privileged: nil, platform: nil, dry_run: false)
+          @runner = runner || method(:run_argv)
+          @account_lookup = account_lookup || method(:lookup_passwd)
+          @privileged = privileged || -> { Process.euid.zero? }
+          @platform = platform || Ace::Lab.host_platform
+          @dry_run = dry_run
+        end
+
+        # @param account [Hash] normalized manifest account entry
+        # @return [Hash] {username:, status:, uid:, message:}
+        def call(account:)
+          username = account["username"]
+          existing = account_lookup.call(username)
+          if existing
+            return {"username" => username, "status" => "exists", "uid" => existing.uid,
+              "message" => nil} if existing.dir == account["home"]
+
+            # Drift is reported, not repaired: the manifest home stays
+            # authoritative (key default paths derive from it).
+            {"username" => username, "status" => "exists", "uid" => existing.uid,
+             "message" => "account '#{username}' home is '#{existing.dir}' but the manifest " \
+              "declares '#{account["home"]}'; the manifest home is authoritative for key paths"}
+          else
+
+            unless account["create"]
+              return failure(username,
+                "account '#{username}' does not exist; create it manually (administrator action) " \
+                "or set create: true in the install manifest")
+            end
+
+            unless privileged.call
+              return failure(username,
+                "creating account '#{username}' requires administrator privileges; rerun ace-lab prepare " \
+                "with sudo or create the account manually")
+            end
+
+            # Platform support is classified BEFORE the dry-run
+            # prediction: --dry-run must predict the wet failure on an
+            # unsupported platform, not would_create.
+            creation = case platform
+                       when "darwin" then :create_darwin
+                       when "linux" then :create_linux
+                       end
+            if creation.nil?
+              return failure(username,
+                "unsupported platform '#{platform}' for account creation; create account '#{username}' " \
+                "manually and set create: false in the install manifest")
+            end
+
+            if dry_run
+              return {"username" => username, "status" => "would_create", "uid" => nil, "message" => nil}
+            end
+
+            send(creation, account)
+          end
+        end
+
+        private
+
+        def failure(username, message)
+          {"username" => username, "status" => "failed", "uid" => nil, "message" => message}
+        end
+
+        def created(username, uid)
+          {"username" => username, "status" => "created", "uid" => uid, "message" => nil}
+        end
+
+        def create_darwin(account)
+          username = account["username"]
+          listing = invoke(["dscl", ".", "-list", "/Users", "UniqueID"])
+          return failure(username, listing["message"]) unless listing["ok"]
+
+          uid = next_darwin_uid(listing["out"])
+          steps = [
+            ["dscl", ".", "-create", "/Users/#{username}", "RealName", username],
+            ["dscl", ".", "-create", "/Users/#{username}", "UniqueID", uid.to_s],
+            ["dscl", ".", "-create", "/Users/#{username}", "PrimaryGroupID", DARWIN_PRIMARY_GROUP.to_s],
+            ["dscl", ".", "-create", "/Users/#{username}", "UserShell", DEFAULT_SHELL],
+            ["dscl", ".", "-create", "/Users/#{username}", "NFSHomeDirectory", account["home"]],
+            ["dscl", ".", "-create", "/Users/#{username}", "GeneratedUID", SecureRandom.uuid],
+            ["dscl", ".", "-create", "/Users/#{username}", "Password", "*"],
+            ["createhomedir", "-c", "-u", username]
+          ]
+          steps.each do |argv|
+            result = invoke(argv)
+            return failure(username, result["message"]) unless result["ok"]
+          end
+
+          created(username, uid)
+        end
+
+        # Allocate the next free UniqueID above the current maximum,
+        # ignoring the reserved high sentinel values (darwin's `nobody`
+        # reports 4294967294). Parse only the trailing UniqueID column
+        # of each `dscl -list` line — digits inside account names such
+        # as `deploy-2026` must never be taken for a UID. Deliberately
+        # simple: dscl owns the directory; concurrent creation is
+        # reconciled by the idempotent re-run.
+        def next_darwin_uid(out)
+          ids = out.lines.filter_map { |line| line[/\s(\d+)\s*\z/, 1] }
+            .map(&:to_i).reject { |id| id >= 2**31 }
+          return 501 if ids.empty?
+
+          [ids.max + 1, 501].max
+        end
+
+        def create_linux(account)
+          username = account["username"]
+          result = invoke([
+            "useradd", "-m", "-s", DEFAULT_SHELL, "-d", account["home"], username
+          ])
+          return failure(username, result["message"]) unless result["ok"]
+
+          entry = account_lookup.call(username)
+          if entry
+            created(username, entry.uid)
+          else
+            {"username" => username, "status" => "created", "uid" => nil,
+             "message" => "account '#{username}' was created but its uid could not be " \
+               "resolved yet; rerun ace-lab prepare to report it"}
+          end
+        end
+
+        # @return [Hash] {ok:, out:, message:} — failure message carries
+        #   the exit status and the first stderr line only, never command
+        #   output bodies or file content.
+        def invoke(argv)
+          result = runner.call(argv)
+          if result["status"] == "ok"
+            {"ok" => true, "out" => result["out"], "message" => nil}
+          elsif result["status"] == "enoent"
+            {"ok" => false, "out" => result["out"],
+             "message" => "#{argv.first} not found in PATH; install it and rerun ace-lab prepare"}
+          elsif result["status"] == "exec_failed"
+            # Exec-level SystemCallError, not a subprocess exit status —
+            # render the errno class so the message never says "exit failed".
+            {"ok" => false, "out" => result["out"],
+             "message" => "command could not be executed (#{argv.first}, #{result['err']})"}
+          else
+            first_line = result["err"].to_s.lines.map(&:strip).reject(&:empty?).first
+            # Round 5 (C2): a signal-killed child has no exitstatus —
+            # the runner renders "signal <termsig>" instead of nil.
+            message = "command failed (#{argv.first}, #{exit_detail(result['status'])})"
+            message += ": #{first_line}" if first_line
+            {"ok" => false, "out" => result["out"], "message" => message}
+          end
+        end
+
+        def exit_detail(status)
+          status.is_a?(Integer) ? "exit #{status}" : status.to_s
+        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
+
+        def lookup_passwd(username)
+          Etc.getpwnam(username)
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lab
+    module Molecules
+      # Classifies the lab configuration namespace into exactly three
+      # distinguished states (task 8xg.t.sbz.6.0): a valid empty set, missing
+      # configuration, and a source error are never conflated.
+      #
+      #   :defaults_only — no overlay exists (gem defaults only) ⇒ missing
+      #                    configuration; informational, exit-eligible success
+      #   :configured    — at least one overlay present and valid; carries
+      #                    topology counts (0/0/0 is a valid empty set)
+      #   :invalid       — any cascade document unparsable/non-mapping or a
+      #                    schema violation; carries the path-bearing message
+      #
+      # Also echoes runtime *configuration files* (project, user, ACE_RUNTIME
+      # env): presence + the configured runtime value. No runtime detection
+      # and no ace-runtime dependency — live runtime availability is
+      # ace-herdr status's dimension.
+      class ConfigStateClassifier
+        RUNTIME_PATTERNS = %w[runtime/config.yml runtime/config.yaml].freeze
+
+        class << self
+          # @param documents [Array<Hash>, nil] cascade_documents output;
+          #   nil means the cascade itself raised before documents existed
+          # @param cascade_error [String, nil] path-bearing message from the
+          #   InvalidConfigurationError raised while reading the cascade
+          # @param root [String] project root for runtime config reads
+          # @return [Hash] classified configuration section
+          def classify(documents:, cascade_error: nil, root: Dir.pwd)
+            return invalid_config(cascade_error) if cascade_error
+
+            documents ||= []
+            # No cascade documents at all (not even gem defaults): nothing
+            # is broken, the lab is simply unconfigured.
+            return missing_config if documents.empty?
+
+            overlays = documents.reject { |document| document[:defaults] }
+            user_overlay_dir = File.join(Dir.home, ".ace")
+            project = overlays.find { |document| !document[:path].start_with?(user_overlay_dir) }
+            user = overlays.find { |document| document[:path].start_with?(user_overlay_dir) }
+
+            merged = deep_merge_documents(documents)
+            begin
+              topology = Atoms::TopologySchema.normalize!(merged).fetch("topology", {})
+              {
+                state: overlays.empty? ? :defaults_only : :configured,
+                overlays: {project: project&.dig(:path), user: user&.dig(:path)},
+                source_path: overlays.first&.dig(:path),
+                error: nil,
+                topology: {
+                  projects: topology.fetch("projects", []).length,
+                  agents: topology.fetch("agents", []).length,
+                  services: topology.fetch("services", []).length
+                }
+              }
+            rescue Ace::Lab::InvalidConfigurationError => e
+              invalid_config(e.message)
+            end
+          end
+
+          # Runtime configuration echo: files first (project, then user),
+          # then the ACE_RUNTIME environment variable. Presence and value
+          # only — never liveness.
+          #
+          # @param root [String] project root
+          # @return [Hash] runtime configuration section
+          def runtime_config(root: Dir.pwd)
+            candidates = [
+              {source: "project", paths: RUNTIME_PATTERNS.map { |pattern| File.join(root, ".ace", pattern) }},
+              {source: "user", paths: RUNTIME_PATTERNS.map { |pattern| File.join(Dir.home, ".ace", pattern) }}
+            ]
+            found = candidates.find do |candidate|
+              candidate[:paths].any? { |candidate_path| File.exist?(candidate_path) }
+            end
+            if found
+              path = found[:paths].find { |candidate_path| File.exist?(candidate_path) }
+              document = begin
+                require "yaml"
+                YAML.safe_load_file(path, permitted_classes: [Date], aliases: true)
+              rescue StandardError
+                nil
+              end
+              if document.is_a?(Hash)
+                return {state: :valid, source: found[:source], path: path, runtime: document["runtime"]}
+              end
+
+              return {state: :invalid, source: found[:source], path: path, runtime: nil,
+                      error: "#{path} could not be parsed as a YAML mapping"}
+            end
+            return runtime_from_env if ENV["ACE_RUNTIME"] && !ENV["ACE_RUNTIME"].empty?
+
+            {state: :absent, source: nil, path: nil, runtime: nil}
+          end
+
+          private
+
+          def runtime_from_env
+            {state: :valid, source: "env", path: nil, runtime: ENV["ACE_RUNTIME"]}
+          end
+
+          def invalid_config(message)
+            {
+              state: :invalid,
+              overlays: {},
+              source_path: nil,
+              error: message,
+              topology: {projects: 0, agents: 0, services: 0}
+            }
+          end
+
+          def missing_config
+            {
+              state: :defaults_only,
+              overlays: {},
+              source_path: nil,
+              error: nil,
+              topology: {projects: 0, agents: 0, services: 0}
+            }
+          end
+
+          # Cascade merge mirroring the canonical ADR-22 resolver:
+          # cascade_documents lists documents highest-priority-first, so
+          # reduce in reverse (defaults first, nearest overlay last — later
+          # wins). Arrays replace (they are topology inventories, not
+          # additive sets).
+          def deep_merge_documents(documents)
+            documents.reverse.reduce({}) { |merged, document| deep_merge(merged, document[:document]) }
+          end
+
+          def deep_merge(base, overlay)
+            base.merge(overlay) do |_key, base_value, overlay_value|
+              if base_value.is_a?(Hash) && overlay_value.is_a?(Hash)
+                deep_merge(base_value, overlay_value)
+              else
+                overlay_value
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require "etc"
+require "fileutils"
+
+module Ace
+  module Lab
+    module Molecules
+      # Idempotently ensures a manifest-declared directory exists with the
+      # declared mode and ownership. Pre-existing directories are never
+      # silently taken over: a symlink at the path, a non-directory, or a
+      # directory owned by a different account than declared is refused
+      # with a resolve-manually message; only mode drift on an
+      # owner-matching directory is repaired. Permission failures
+      # (EPERM/EACCES) classify as actionable missing-permission reports.
+      class DirectoryProvisioner
+        attr_reader :account_lookup, :dry_run
+
+        # available_accounts [Enumerable<String>, nil] usernames the
+        # account phase will have (exists/created/would_create) — the
+        # orchestrator's already-computed set, threaded in so dry-run
+        # can predict the wet run's owner_unavailable failure for a
+        # directory whose owner account failed permanently (mirroring
+        # keys/roles dependency prediction). nil = predict from live
+        # passwd only (standalone use).
+        def initialize(account_lookup: nil, dry_run: false, available_accounts: nil)
+          @account_lookup = account_lookup || method(:lookup_passwd)
+          @dry_run = dry_run
+          @available_accounts = available_accounts
+        end
+
+        # @param directory [Hash] normalized manifest directory entry
+        # @return [Hash] {path:, owner:, mode:, status:, message:}
+        def call(directory:)
+          path = directory["path"]
+          mode = directory["mode"].to_i(8)
+          stat = begin
+            File.lstat(path)
+          rescue Errno::ENOENT
+            nil
+          end
+
+          if stat.nil?
+            create_missing(path, directory, mode)
+          elsif stat.symlink?
+            refuse_symlink(path, directory)
+          elsif !stat.directory?
+            failure(path, "path '#{path}' is occupied by a non-directory; refusing", directory)
+          else
+            ensure_existing(path, directory, stat, mode)
+          end
+        rescue Errno::EPERM, Errno::EACCES
+          failure(path,
+            "insufficient permissions while preparing '#{path}'; rerun ace-lab prepare with sudo " \
+            "or adjust ownership manually", directory)
+        rescue SystemCallError => e
+          failure(path, "path '#{path}' could not be prepared (#{e.class.name})", directory)
+        end
+
+        private
+
+        def base(path, directory)
+          {"path" => path, "owner" => directory["owner"], "mode" => directory["mode"]}
+        end
+
+        # Every failed entry carries the full {path, owner, mode} shape —
+        # JSON consumers must see one shape per section, including
+        # rescue-path failures.
+        def failure(path, message, directory)
+          base(path, directory).merge("status" => "failed", "message" => message)
+        end
+
+        def refuse_symlink(path, directory)
+          failure(path, "path '#{path}' is a symbolic link; refusing", directory)
+        end
+
+        # Ownership an existing directory must match: the declared owner
+        # account's uid, or the installer's euid when no owner is declared.
+        # Returns nil when the declared owner account is not resolvable on
+        # this machine (account phase not yet green).
+        def expected_owner_uid(directory)
+          return Process.euid unless directory["owner"]
+
+          entry = account_lookup.call(directory["owner"])
+          entry && entry.uid
+        end
+
+        def create_missing(path, directory, mode)
+          if dry_run
+            # A declared owner whose account phase failed permanently
+            # (not merely would_create) makes the wet run fail with
+            # owner_unavailable — the prediction must say so instead of
+            # would_create.
+            if directory["owner"] && @available_accounts &&
+                !@available_accounts.include?(directory["owner"])
+              return owner_unavailable(path, directory, "fix the account phase first")
+            end
+
+            return base(path, directory).merge("status" => "would_create", "message" => nil)
+          end
+
+          missing = chown_target(directory)
+          return owner_unavailable(path, directory) if directory["owner"] && missing.nil?
+
+          refusal = create_leaf(path, directory)
+          return refusal if refusal
+
+          FileUtils.chmod(mode, path)
+          chown_to_owner(path, directory, missing)
+          base(path, directory).merge("status" => "created", "message" => nil)
+        end
+
+        # Close the create-time TOCTOU window as far as stdlib allows:
+        # intermediate components are created per the documented policy
+        # (mkdir_p follows existing components — the manifest is
+        # root-owned and only the leaf carries declared values), but the
+        # leaf uses Dir.mkdir, whose EEXIST on a planted symlink never
+        # follows it, and the leaf is re-lstat'd before any chmod/chown:
+        # a leaf that is not a real directory this process just created
+        # is refused instead of mutated. The window between this
+        # re-lstat and the chmod/chown that follow is a documented
+        # accepted residual (usage.md).
+        def create_leaf(path, directory)
+          FileUtils.mkdir_p(File.dirname(path))
+          Dir.mkdir(path)
+          post = lstat(path)
+          return nil if post && post.directory? && post.uid == Process.euid
+
+          failure(path, "path '#{path}' changed while preparing; refusing — rerun ace-lab prepare",
+            directory)
+        rescue Errno::EEXIST
+          failure(path, "path '#{path}' appeared or was replaced while preparing; " \
+            "refusing — rerun ace-lab prepare", directory)
+        rescue Errno::ENOENT, Errno::ENOTDIR
+          failure(path, "path '#{path}' could not be created; rerun ace-lab prepare", directory)
+        end
+
+        def ensure_existing(path, directory, stat, mode)
+          expected_uid = expected_owner_uid(directory)
+          if directory["owner"] && expected_uid.nil?
+            return owner_unavailable(path, directory)
+          end
+
+          if stat.uid != expected_uid
+            owner = directory["owner"] || "installer"
+            return failure(path,
+              "directory '#{path}' exists but is owned by uid #{stat.uid} " \
+              "(expected account '#{owner}'); refusing takeover — resolve ownership manually " \
+              "or rerun ace-lab prepare with sudo", directory)
+          end
+
+          if (stat.mode & 0o7777) == mode
+            return base(path, directory).merge("status" => "exists", "message" => nil)
+          end
+
+          return base(path, directory).merge("status" => "would_fix_mode", "message" => nil) if dry_run
+
+          # Stale-stat re-check: the owner-matching lstat above may be
+          # outdated by the time chmod runs; re-lstat and refuse unless
+          # the leaf is still a real, owner-matching directory.
+          fresh = lstat(path)
+          unless fresh && fresh.directory? && fresh.uid == expected_uid
+            return failure(path,
+              "directory '#{path}' changed while preparing; refusing — rerun ace-lab prepare", directory)
+          end
+
+          FileUtils.chmod(mode, path)
+          base(path, directory).merge("status" => "mode_fixed", "message" => nil)
+        end
+
+        def lstat(path)
+          File.lstat(path)
+        rescue Errno::ENOENT, Errno::ENOTDIR
+          nil
+        end
+
+        def owner_unavailable(path, directory, remedy = nil)
+          remedy ||= if dry_run
+            "the account phase would create it; ownership of existing '#{path}' cannot be " \
+              "predicted before the account exists — rerun prepare --dry-run after the account phase"
+          else
+            "fix the account phase first"
+          end
+          failure(path,
+            "owner account '#{directory["owner"]}' is not available on this machine; " \
+            "#{remedy}", directory)
+        end
+
+        def chown_target(directory)
+          return nil unless directory["owner"]
+
+          account_lookup.call(directory["owner"])
+        end
+
+        def chown_to_owner(path, directory, entry)
+          FileUtils.chown(entry.uid, entry.gid, path) if entry
+        end
+
+        def lookup_passwd(username)
+          Etc.getpwnam(username)
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end