ace-lab 0.9.0 → 0.13.0

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lab
+    module Molecules
+      # Read-only scan of the file-based lab state-owner locations
+      # (ADR-034). Every location reports presence and — unless it is
+      # private or reserved — an entry count; a per-location read failure
+      # becomes that location's :error and never masks its siblings
+      # (task 8xg.t.sbz.6.0: a source failure is shown alongside
+      # available results).
+      class LabStateScanner
+        # presence_only locations are never enumerated: _overseer is the
+        # private task list, coworker is reserved L3 configuration.
+        LOCATIONS = [
+          {key: "tasks", path: ".ace-tasks", note: nil},
+          {key: "overseer", path: ".ace-tasks/_overseer", note: "private; not listed"},
+          {key: "assignments", path: ".ace-local/assign", note: nil},
+          {key: "hitl", path: ".ace-local/hitl", note: nil},
+          {key: "worktrees", path: ".ace-wt", note: "enriched view: ace-git-worktree list"},
+          {key: "coworker", path: ".ace-local/coworker", note: "reserved L3; informational"}
+        ].freeze
+
+        PRESENCE_ONLY = %w[overseer coworker].freeze
+
+        class << self
+          # @param root [String] project root to scan
+          # @return [Array<Hash>] {key, path, state, entries, note} per
+          #   location; state is :present, :absent, or :error
+          def scan(root: Dir.pwd)
+            LOCATIONS.map do |location|
+              absolute = File.join(root, location[:path])
+              entry = {key: location[:key], path: location[:path], note: location[:note]}
+              begin
+                if File.directory?(absolute)
+                  entry[:state] = :present
+                  entry[:entries] = PRESENCE_ONLY.include?(location[:key]) ? nil : Dir.children(absolute).length
+                  entry[:state] = :prepared if PRESENCE_ONLY.include?(location[:key])
+                else
+                  entry[:state] = :absent
+                  entry[:entries] = nil
+                end
+              rescue SystemCallError => e
+                entry[:state] = :error
+                entry[:entries] = nil
+                entry[:note] = e.message
+              end
+              entry
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require "open3"
+
+module Ace
+  module Lab
+    module Molecules
+      # Idempotently prepares the project's private overseer folder
+      # (ADR-034): the ordinary, gitignored `.ace-tasks/_overseer/`
+      # directory plus its `.gitignore` entry. Existing content is never
+      # inspected or modified — the folder is private to the overseer that
+      # owns it; this provisioner only ensures the folder and the ignore
+      # rule exist. Re-running reports ok without rewriting anything.
+      #
+      # Whether the folder is ACTUALLY ignored is decided by real Git
+      # evaluation (`git check-ignore`), never by scanning `.gitignore`
+      # lines: a later negation (`!.ace-tasks/_overseer/`) un-ignores an
+      # earlier positive line, so line matching would report a private
+      # folder as ignored while Git would commit it (LAB-5). When Git
+      # reports the folder as not effectively ignored, the effective rule
+      # is appended (append-only — the project's own content survives)
+      # and the decision is re-evaluated to confirm.
+      #
+      # The provisioner runs with installer privileges on a freshly
+      # cloned repository whose contents are NOT root-trusted: every
+      # write is preceded by lstat checks refusing symbolic links under
+      # the project root (a committed `.gitignore` or `.ace-tasks`
+      # symlink must never redirect a privileged write outside the
+      # project — LAB-1).
+      class OverseerProvisioner
+        OVERSEER_PATH = File.join(".ace-tasks", "_overseer")
+        OVERSEER_IGNORE_PATH = ".ace-tasks/_overseer"
+
+        attr_reader :dry_run
+
+        # @param runner [Proc, nil] argv runner seam (git check-ignore)
+        def initialize(runner: nil, dry_run: false)
+          @runner = runner || method(:run_argv)
+          @dry_run = dry_run
+        end
+
+        # @param root [String] absolute project root
+        # @return [Hash] {dir:, gitignore:, status:, message:} where
+        #   status is created / exists / would_create / failed
+        def call(root:)
+          directory = File.join(root, OVERSEER_PATH)
+          gitignore = File.join(root, ".gitignore")
+
+          unsafe = unsafe_symlink_reason(root)
+          return failed(unsafe) if unsafe
+
+          # A repo-controlled symlink at the ignore path is refused up
+          # front — no privileged read-through either (git check-ignore
+          # would follow the link): same trust posture as the LAB-1
+          # write refusals.
+          gitignore_stat = begin
+            File.lstat(gitignore)
+          rescue Errno::ENOENT, Errno::ENOTDIR
+            nil
+          end
+          if gitignore_stat&.symlink?
+            return failed("'#{gitignore}' is a symbolic link; refusing to follow it with " \
+              "installer privileges (remove the link and rerun)")
+          end
+
+          # Dry-run prediction for a repository the clone step would
+          # create: no work tree exists to evaluate yet — predict the
+          # rule the wet run appends.
+          ignore = if dry_run && !File.directory?(root)
+            {"status" => "ok", "ignored" => false, "message" => nil}
+          else
+            ignore_decision(root)
+          end
+          return failed(ignore["message"]) if ignore["status"] == "failed"
+
+          dir_present = File.directory?(directory)
+          if dir_present && ignore["ignored"]
+            return {"dir" => OVERSEER_PATH, "gitignore" => ".gitignore",
+                    "status" => "exists", "message" => nil}
+          end
+          return {"dir" => OVERSEER_PATH, "gitignore" => ".gitignore",
+                  "status" => "would_create", "message" => nil} if dry_run
+
+          begin
+            require "fileutils"
+            FileUtils.mkdir_p(directory) unless dir_present
+            append_ignore_entry(gitignore) unless ignore["ignored"]
+          rescue SystemCallError => e
+            return failed("preparing _overseer failed: #{e.message}")
+          end
+
+          unless ignore["ignored"]
+            confirmed = ignore_decision(root)
+            if confirmed["status"] == "failed"
+              return failed(confirmed["message"])
+            end
+            unless confirmed["ignored"]
+              return failed("'#{OVERSEER_IGNORE_PATH}' is still not ignored by Git after " \
+                "appending the rule to '#{gitignore}'; fix the project's ignore rules manually")
+            end
+          end
+
+          {"dir" => OVERSEER_PATH, "gitignore" => ".gitignore",
+           "status" => "created", "message" => nil}
+        end
+
+        private
+
+        # A repository-controlled symlink under the project root must
+        # never be followed by a privileged read or write: refuse before
+        # any mutation. Applies to the `.ace-tasks` component of the
+        # private folder path (a symlinked `.gitignore` is refused below
+        # before it is read or appended).
+        def unsafe_symlink_reason(root)
+          %w[.ace-tasks .ace-tasks/_overseer].each do |component|
+            path = File.join(root, component)
+            stat = File.lstat(path)
+            if stat.symlink?
+              return "'#{path}' is a symbolic link; refusing to follow it with installer " \
+                "privileges (remove the link and rerun)"
+            end
+          rescue Errno::ENOENT, Errno::ENOTDIR
+            nil
+          end
+          nil
+        end
+
+        # Real Git ignore evaluation: ok means ignored, exit 1 means not
+        # ignored, anything else (dubious ownership, missing git, not a
+        # repository) is a concrete failure — a decision this molecule
+        # cannot make must never be guessed.
+        def ignore_decision(root)
+          result = @runner.call(["git", "-C", root, "check-ignore", "--", OVERSEER_IGNORE_PATH])
+          case result["status"]
+          when "ok"
+            {"status" => "ok", "ignored" => true, "message" => nil}
+          when 1, "1" # exit 1: evaluated and NOT ignored
+            {"status" => "ok", "ignored" => false, "message" => nil}
+          else
+            detail = result["err"].to_s.lines.map(&:strip).reject(&:empty?).first
+            {"status" => "failed", "ignored" => nil,
+             "message" => "cannot evaluate Git ignore rules for '#{root}' " \
+               "(git check-ignore exited with #{result['status']}#{": #{detail}" if detail})"}
+          end
+        end
+
+        # Append only — an existing .gitignore is the project's own
+        # content and must survive a re-add untouched. A symlinked
+        # .gitignore (checked again here, immediately before the open)
+        # is refused rather than followed.
+        def append_ignore_entry(gitignore)
+          stat = begin
+            File.lstat(gitignore)
+          rescue Errno::ENOENT, Errno::ENOTDIR
+            nil
+          end
+          if stat&.symlink?
+            raise SystemCallError.new(
+              "'#{gitignore}' is a symbolic link; refusing to follow it with installer privileges", 0)
+          end
+
+          entry = "#{OVERSEER_IGNORE_PATH}/"
+          if stat && !File.read(gitignore).end_with?("\n")
+            File.open(gitignore, "a") { |file| file.write("\n#{entry}\n") }
+          else
+            File.open(gitignore, "a") { |file| file.write("#{entry}\n") }
+          end
+        end
+
+        def failed(message)
+          {"dir" => OVERSEER_PATH, "gitignore" => ".gitignore",
+           "status" => "failed", "message" => message}
+        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/project_registry.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../atoms/topology_schema"
+
+module Ace
+  module Lab
+    module Molecules
+      # Reads and updates the project registry: the project-tier lab
+      # configuration at `<project>/.ace/lab/config.yml` (task
+      # 8xg.t.sbz.7.1). This is the same ADR-022 cascade document every
+      # consumer already reads (`ace-lab status`, `ace-lab projects`,
+      # `ace-overseer projects`), so registering a project here makes it
+      # visible to the whole chain — no second registry exists.
+      #
+      # Project entries carry the deployment facts the installer owns:
+      # id, label, absolute path and origin remote. `TopologySchema`
+      # ignores unknown keys, so the query surface (PublicProjection)
+      # is unchanged. The molecule is idempotent and refuses before any
+      # overwrite: a contradictory registration (same id, different
+      # path/remote), a location conflict (same path, different id), an
+      # unparseable or foreign document — all fail without writing.
+      class ProjectRegistry
+        REGISTRY_PATH = File.join(".ace", "lab", "config.yml")
+        SCHEMA_VERSION = 1
+
+        # @param root [String] absolute project root
+        # @return [Hash, nil] parsed registry document, nil when absent
+        # @raise [Ace::Lab::InvalidConfigurationError] unparseable or
+        #   non-mapping document
+        def load(root:)
+          path = registry_path(root)
+          return nil unless File.file?(path)
+
+          require "yaml"
+          document = YAML.safe_load_file(path, permitted_classes: [Date], aliases: true)
+          unless document.nil? || document.is_a?(Hash)
+            raise Ace::Lab::InvalidConfigurationError,
+              "#{path} must contain a YAML mapping"
+          end
+          document || {}
+        end
+
+        # @param root [String] absolute project root
+        # @return [String] absolute registry path
+        def registry_path(root)
+          File.join(root, REGISTRY_PATH)
+        end
+
+        # Idempotently register a project.
+        #
+        # @param root [String] absolute project root
+        # @param project [Hash] {"id" =>, "label" =>, "path" =>,
+        #   "remote" =>} — path is the absolute project path, remote the
+        #   origin URL (nil allowed for an offline repository)
+        # @param dry_run [Boolean]
+        # @return [Hash] {path:, status:, message:} where status is
+        #   created / exists / would_create / failed
+        def register(root:, project:, dry_run: false)
+          path = registry_path(root)
+          document = begin
+            load(root: root)
+          rescue StandardError
+            return failure(path, "#{path} could not be read as the lab registry; refusing to overwrite")
+          end
+
+          if document.nil?
+            document = {"schema_version" => SCHEMA_VERSION,
+              "topology" => {"projects" => [], "agents" => [], "services" => []}}
+            return write(path, document, project, dry_run)
+          end
+
+          if document.empty?
+            return failure(path, "#{path} exists but is empty; " \
+              "it is not this lab's registry — refusing to overwrite")
+          end
+
+          version = document["schema_version"]
+          unless version == SCHEMA_VERSION
+            return failure(path, "#{path} has schema_version #{version.inspect}; " \
+              "it is not this lab's registry — refusing to overwrite")
+          end
+
+          # Pre-validate the loaded document (review 8xikzhvi): a
+          # malformed entry (e.g. a non-mapping topology.projects item)
+          # is a foreign document and must fail classification here,
+          # never crash with a TypeError mid-iteration.
+          begin
+            Atoms::TopologySchema.normalize!(deep_copy(document))
+          rescue Ace::Lab::InvalidConfigurationError
+            return failure(path, "#{path} is not this lab's registry " \
+              "(invalid lab configuration); refusing to overwrite")
+          end
+
+          conflict = conflicting_registration(document, project)
+          return failure(path, conflict) if conflict
+
+          existing = projects_in(document).find { |entry| entry["id"] == project["id"] }
+          if existing
+            # `label` is display data, not identity: a changed label on
+            # re-add updates it in place (review 8xikzhvl). An absent
+            # label leaves the recorded one untouched.
+            return {"path" => path, "status" => "exists", "message" => nil} if !project["label"] || project["label"] == existing["label"]
+
+            return relabel(path, document, project, dry_run)
+          end
+
+          write(path, document, project, dry_run)
+        end
+
+        private
+
+        def write(path, document, project, dry_run)
+          updated = deep_copy(document)
+          updated["topology"] ||= {}
+          updated["topology"]["projects"] ||= []
+          entry = {"id" => project["id"]}
+          entry["label"] = project["label"] if project["label"]
+          entry["path"] = project["path"]
+          entry["remote"] = project["remote"] if project["remote"]
+          updated["topology"]["projects"] << entry
+          persist(path, updated, project, dry_run, "would_create", "created")
+        end
+
+        def relabel(path, document, project, dry_run)
+          updated = deep_copy(document)
+          entry = projects_in(updated).find { |candidate| candidate["id"] == project["id"] }
+          entry["label"] = project["label"]
+          persist(path, updated, project, dry_run, "would_update", "updated")
+        end
+
+        # Validate the updated document BEFORE the dry-run branch
+        # (review 8xikzhvj): a dry run predicts the wet run's
+        # validation failures instead of a success the wet run cannot
+        # deliver.
+        def persist(path, updated, project, dry_run, dry_status, wet_status)
+          begin
+            Atoms::TopologySchema.normalize!(updated)
+          rescue Ace::Lab::InvalidConfigurationError => e
+            return failure(path,
+              "registering project '#{project['id']}' would produce an invalid lab configuration: #{e.message}")
+          end
+          return {"path" => path, "status" => dry_status, "message" => nil} if dry_run
+
+          begin
+            require "fileutils"
+            dir = File.dirname(path)
+            unsafe = unsafe_symlink_reason(path)
+            return failure(path, unsafe) if unsafe
+
+            FileUtils.mkdir_p(dir)
+            # Atomic write (review 8xikzhvk): a crash mid-write must
+            # never leave a truncated cascade document behind. The
+            # temporary file is created EXCLUSIVELY (O_CREAT|O_EXCL)
+            # under an unguessable name: a pre-planted symlink at a
+            # predictable `.tmp.<PID>` path must never redirect the
+            # privileged write outside the project (LAB-1/F3) —
+            # O_EXCL refuses to follow an existing symlink, and a
+            # unique random name leaves nothing predictable to plant.
+            tmp = write_exclusive(dir, YAML.dump(updated))
+            File.rename(tmp, path)
+          rescue SystemCallError, IOError => e
+            File.delete(tmp) if defined?(tmp) && tmp && File.exist?(tmp)
+            return failure(path, "writing #{path} failed: #{e.message}")
+          end
+
+          {"path" => path, "status" => wet_status, "message" => nil}
+        end
+
+        # A repository-controlled symlink among the registry's ancestor
+        # directories (`.ace`, `.ace/lab`) must never be followed by a
+        # privileged mkdir/write: refuse before any mutation.
+        def unsafe_symlink_reason(registry_path)
+          [File.dirname(registry_path), File.dirname(File.dirname(registry_path))].each do |ancestor|
+            stat = File.lstat(ancestor)
+            if stat.symlink?
+              return "'#{ancestor}' is a symbolic link; refusing to follow it with installer " \
+                "privileges (remove the link and rerun)"
+            end
+          rescue Errno::ENOENT, Errno::ENOTDIR
+            nil
+          end
+          nil
+        end
+
+        # Create the temp file exclusively (never following a symlink),
+        # write the payload, close, and return the path. Raises
+        # SystemCallError/IOError on failure so the caller classifies.
+        def write_exclusive(dir, payload)
+          require "securerandom"
+          100.times do
+            candidate = File.join(dir, ".config.yml.tmp.#{Process.pid}.#{SecureRandom.hex(8)}")
+            next if File.exist?(candidate) # includes symlinks (lstat)
+
+            begin
+              file = File.open(candidate, File::RDWR | File::CREAT | File::EXCL, 0o600)
+            rescue Errno::EEXIST
+              next
+            end
+            begin
+              file.write(payload)
+            ensure
+              file.close
+            end
+            return candidate
+          end
+          raise SystemCallError.new("could not create an exclusive temporary file in '#{dir}'", 0)
+        end
+
+        # Contradiction and location-conflict detection, checked before
+        # any write: same id with a different path or remote, or the same
+        # absolute path registered under a different id.
+        def conflicting_registration(document, project)
+          projects_in(document).each do |entry|
+            next unless entry.is_a?(Hash)
+
+            if entry["id"] == project["id"]
+              if entry["path"] && entry["path"] != project["path"]
+                return "project '#{project['id']}' is registered at '#{entry['path']}' " \
+                  "but the request declares '#{project['path']}'"
+              end
+              if entry["remote"] && project["remote"] && entry["remote"] != project["remote"]
+                return "project '#{project['id']}' is registered with remote '#{entry['remote']}' " \
+                  "but the request declares '#{project['remote']}'"
+              end
+            elsif entry["path"] && entry["path"] == project["path"]
+              return "path '#{project['path']}' is already registered as project '#{entry['id']}'"
+            end
+          end
+          nil
+        end
+
+        def projects_in(document)
+          topology = document["topology"]
+          return [] unless topology.is_a?(Hash) && topology["projects"].is_a?(Array)
+
+          topology["projects"]
+        end
+
+        def deep_copy(document)
+          require "yaml"
+          YAML.safe_load(YAML.dump(document), permitted_classes: [Date], aliases: true)
+        end
+
+        def failure(path, message)
+          {"path" => path, "status" => "failed", "message" => message}
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require "open3"
+
+module Ace
+  module Lab
+    module Molecules
+      # Idempotently ensures a Git repository exists at the project path
+      # with the declared origin remote (task 8xg.t.sbz.7.1). A missing or
+      # empty target is cloned from the remote; an existing repository is
+      # verified against the declared remote — a different origin is a
+      # contradictory registration that is refused, never overwritten.
+      # All Git access goes through argv arrays (ADR-031); failures
+      # surface the exit status and the first stderr line only.
+      class RepositoryProvisioner
+        attr_reader :runner, :dry_run
+
+        def initialize(runner: nil, dry_run: false)
+          @runner = runner || method(:run_argv)
+          @dry_run = dry_run
+        end
+
+        # @param path [String] absolute target directory
+        # @param remote [String, nil] declared origin remote URL
+        # @return [Hash] {path:, remote:, status:, message:} where status
+        #   is created / exists / would_create / failed
+        def call(path:, remote:)
+          if repository?(path)
+            converge_existing(path, remote)
+          elsif foreign_directory?(path)
+            failure(path, remote,
+              "'#{path}' exists and is not an empty directory or a Git repository; " \
+              "refusing to take over a foreign location")
+          elsif remote.nil?
+            failure(path, remote,
+              "'#{path}' has no repository and no --remote was given; " \
+              "nothing to prepare the project from")
+          elsif dry_run
+            {"path" => path, "remote" => remote, "status" => "would_create", "message" => nil}
+          else
+            clone(path, remote)
+          end
+        end
+
+        private
+
+        def converge_existing(path, remote)
+          origin = origin_url(path)
+          return {"path" => path, "remote" => origin || remote, "status" => "exists", "message" => nil} if remote.nil?
+          return {"path" => path, "remote" => origin, "status" => "exists", "message" => nil} if origin == remote
+
+          if origin
+            failure(path, remote,
+              "'#{path}' is a Git repository with origin '#{origin}' but the request " \
+              "declares '#{remote}'; refusing to overwrite an existing registration")
+          elsif dry_run
+            {"path" => path, "remote" => remote, "status" => "would_create",
+             "message" => "would set origin to '#{remote}'"}
+          else
+            result = runner.call(["git", "-C", path, "remote", "add", "origin", remote])
+            return failure(path, remote, "setting origin on '#{path}' failed: #{git_error(result)}") unless success?(result)
+
+            {"path" => path, "remote" => remote, "status" => "created", "message" => nil}
+          end
+        end
+
+        def clone(path, remote)
+          result = runner.call(["git", "clone", remote, path])
+          return failure(path, remote, "cloning '#{remote}' into '#{path}' failed: #{git_error(result)}") unless success?(result)
+
+          {"path" => path, "remote" => remote, "status" => "created", "message" => nil}
+        end
+
+        # Read-only probes: safe in dry-run (the prediction contract from
+        # ace-lab prepare applies — predictions use read-only filesystem
+        # and Git queries, effects are suppressed).
+        # The path must BE the repository toplevel, not merely sit inside
+        # one: a subdirectory of a parent work tree also answers
+        # `--is-inside-work-tree` with true, which would let a foreign
+        # directory bypass the takeover refusal and mutate the parent
+        # repository's origin (review 8xikzhvh).
+        def repository?(path)
+          return false unless File.directory?(path)
+
+          result = runner.call(["git", "-C", path, "rev-parse", "--show-toplevel"])
+          success?(result) && same_location?(result["out"].to_s.strip, path)
+        end
+
+        # Git prints the physical toplevel (symlinks resolved), so the
+        # comparison resolves both sides; a path that cannot be
+        # resolved falls back to the lexical spelling.
+        def same_location?(reported, path)
+          File.realpath(reported) == File.realpath(path)
+        rescue Errno::ENOENT, Errno::ENOTDIR, Errno::EACCES
+          File.expand_path(reported) == File.expand_path(path)
+        end
+
+        def foreign_directory?(path)
+          File.exist?(path) && !(File.directory?(path) && Dir.children(path).empty?)
+        end
+
+        # Raw stored remote URL: `git remote get-url` applies
+        # url.<base>.insteadOf rewrites from the invoking user's git
+        # config, so an identical project would false-fail the
+        # idempotent reuse check under a common SSH rewrite (LAB-7).
+        # Connection rewriting is Git transport policy, not a changed
+        # project identity — compare the stored URL the same way the
+        # final verifier does.
+        def origin_url(path)
+          result = runner.call(["git", "-C", path, "config", "--get", "remote.origin.url"])
+          success?(result) ? result["out"].to_s.strip : nil
+        end
+
+        def success?(result)
+          result["status"] == "ok"
+        end
+
+        def git_error(result)
+          first_line = result["err"].to_s.lines.map(&:strip).reject(&:empty?).first
+          detail = first_line ? " #{first_line}" : ""
+          "git exited with status #{result['status']}#{detail}"
+        end
+
+        def failure(path, remote, message)
+          {"path" => path, "remote" => remote, "status" => "failed", "message" => message}
+        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