space-architect 1.1.0

data/vendor/repo-tender/lib/space_architect/pristine/scm/git.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+require "space_architect/pristine/scm/client"
+require "space_architect/pristine/scm/status"
+require "space_architect/pristine/shell"
+
+module SpaceArchitect::Pristine
+  module SCM
+    # Git CLI implementation of SCM::Client. All subprocess work is
+    # delegated to Shell.run (which requires an ambient Async::Task).
+    class Git < Client
+      # Resolve the bare remote's HEAD. First try the local
+      # `origin/HEAD` symbolic ref; if missing/stale, do a one-shot
+      # `git remote set-head origin -a` (network) to refresh it, then
+      # re-read. This is the gotcha path from AGENTS.md: a plain
+      # `git fetch` does NOT update `origin/HEAD`.
+      def default_branch(path)
+        symbolic = read_origin_head(path)
+        return Dry::Monads::Success(symbolic) if symbolic
+
+        refresh = Shell.run("git", "remote", "set-head", "origin", "-a", chdir: path)
+        return refresh if refresh.failure?
+
+        resolved = read_origin_head(path)
+        if resolved
+          Dry::Monads::Success(resolved)
+        else
+          Dry::Monads::Failure({path: path, reason: "could not resolve origin/HEAD after set-head -a"})
+        end
+      end
+
+      def current_branch(path)
+        # `git symbolic-ref --short HEAD` exits non-zero on detached HEAD.
+        result = Shell.run("git", "symbolic-ref", "--short", "HEAD", chdir: path)
+        if result.success?
+          Dry::Monads::Success(result.success.strip)
+        else
+          # Detached HEAD is not a hard failure — report nil.
+          head = Shell.run("git", "rev-parse", "--verify", "HEAD", chdir: path)
+          if head.success?
+            Dry::Monads::Success(nil)
+          else
+            Dry::Monads::Failure({path: path, reason: "no HEAD", stderr: result.failure[:stderr]})
+          end
+        end
+      end
+
+      def last_fetch_at(path)
+        fetch_head = File.join(path, ".git", "FETCH_HEAD")
+        return Dry::Monads::Success(nil) unless File.exist?(fetch_head)
+        Dry::Monads::Success(Time.at(File.mtime(fetch_head).to_i))
+      end
+
+      def fetch(path)
+        Shell.run("git", "fetch", "--prune", "--no-tags", "origin", chdir: path)
+      end
+
+      # `merge --ff-only` refuses on divergence. We additionally check
+      # the rev-list left/right count first so we can surface a clean
+      # "diverged" failure with diagnostic info, not just a git error
+      # string.
+      def fast_forward(path, default_branch)
+        upstream = "origin/#{default_branch}"
+        counts = Shell.run("git", "rev-list", "--left-right", "--count", "HEAD...#{upstream}", chdir: path)
+        return counts if counts.failure?
+
+        left, right = counts.success.strip.split("\t").map(&:to_i)
+        if left > 0
+          return Dry::Monads::Failure({
+            path: path,
+            reason: "diverged: local is #{left} commit(s) ahead of #{upstream}; not auto-resolving",
+            local_ahead: left,
+            remote_ahead: right
+          })
+        end
+
+        if right == 0
+          return Dry::Monads::Success(0)
+        end
+
+        # Do the fetch (cheap; FETCH_HEAD mtime hint logic can skip this
+        # later, but Slice 1 always fetches when asked to fast-forward).
+        fetch_result = fetch(path)
+        return fetch_result if fetch_result.failure?
+
+        merge = Shell.run("git", "merge", "--ff-only", upstream, chdir: path)
+        if merge.success?
+          Dry::Monads::Success(right)
+        else
+          # On --ff-only failure, git leaves the working tree and local
+          # commits intact — the test asserts this.
+          Dry::Monads::Failure({
+            path: path,
+            reason: "fast-forward failed (likely raced divergence)",
+            stderr: merge.failure[:stderr]
+          })
+        end
+      end
+
+      def status(path)
+        result = Shell.run("git", "status", "--porcelain=v2", "--branch", "--untracked-files=normal", chdir: path)
+        return result if result.failure?
+
+        parsed = parse_porcelain_v2(result.success)
+        Dry::Monads::Success(parsed)
+      end
+
+      def clone(url, dest)
+        parent = File.dirname(dest)
+        FileUtils.mkdir_p(parent)
+        result = Shell.run("git", "clone", url, dest)
+        if result.success?
+          Dry::Monads::Success(dest)
+        else
+          Dry::Monads::Failure({url: url, dest: dest, stderr: result.failure[:stderr]})
+        end
+      end
+
+      # `git switch <branch>`. `git switch` aborts on a dirty tree by
+      # default (man git-switch: "The operation is aborted however if
+      # the operation leads to loss of local changes"), so a nonzero
+      # exit here most likely means the caller violated the engine's
+      # dirty-tree guard. We surface that as a Failure with the
+      # captured stderr so the engine / log can diagnose it.
+      def switch(path, branch)
+        result = Shell.run("git", "switch", branch, chdir: path)
+        if result.success?
+          Dry::Monads::Success(branch)
+        else
+          Dry::Monads::Failure({path: path, branch: branch, reason: "git switch refused", stderr: result.failure[:stderr]})
+        end
+      end
+
+      # Handle an unborn (empty) local clone. If the remote has no
+      # branches, the repo is already a valid empty clone — return
+      # Success(:empty) with no mutation. If the remote has gained
+      # commits, fetch and fast-forward the unborn branch into them.
+      #
+      # `git ls-remote --heads origin` is the authoritative
+      # empty-vs-error discriminator: exit 0 + empty stdout means the
+      # remote truly has no branches; exit 0 + output means it has
+      # commits; non-zero exit means a real network/probe error.
+      def sync_empty(path)
+        ls = Shell.run("git", "ls-remote", "--heads", "origin", chdir: path)
+        return ls if ls.failure?
+
+        return Dry::Monads::Success(:empty) if ls.success.strip.empty?
+
+        fetch_result = fetch(path)
+        return fetch_result if fetch_result.failure?
+
+        branch_result = default_branch(path)
+        return branch_result if branch_result.failure?
+
+        upstream = "origin/#{branch_result.success}"
+        merge = Shell.run("git", "merge", "--ff-only", upstream, chdir: path)
+        if merge.success?
+          Dry::Monads::Success(:fast_forwarded)
+        else
+          Dry::Monads::Failure({path: path, reason: "ff merge into unborn branch failed", stderr: merge.failure[:stderr]})
+        end
+      end
+
+      private
+
+      # `git symbolic-ref --short refs/remotes/origin/HEAD` returns
+      # `origin/<branch>` (the short form of `refs/remotes/origin/<branch>`);
+      # callers want the bare branch name. Returns nil when origin/HEAD
+      # is unset.
+      def read_origin_head(path)
+        result = Shell.run("git", "symbolic-ref", "--short", "refs/remotes/origin/HEAD", chdir: path)
+        return nil unless result.success?
+        line = result.success.strip
+        return nil if line.empty?
+        line.sub(%r{\Aorigin/}, "")
+      end
+
+      # Parse `git status --porcelain=v2 --branch --untracked-files=normal`.
+      # v2 grammar (from the git-status man page):
+      #   # branch.oid <commit-ish> | (initial)
+      #   # branch.head <name> | (detached)
+      #   # branch.upstream <upstream-branch>
+      #   # branch.ab +<ahead> -<behind>
+      #   1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
+      #   2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path><TAB><origPath>
+      #   u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>
+      #   ? <path>
+      #   ! <path>
+      def parse_porcelain_v2(output)
+        branch = nil
+        upstream = nil
+        ahead = 0
+        behind = 0
+        detached = false
+        unborn = false
+        entries = []
+
+        output.each_line do |raw|
+          line = raw.chomp
+          next if line.empty?
+          case line
+          when /\A# branch\.oid (.+)/
+            unborn = (Regexp.last_match(1) == "(initial)")
+          when /\A# branch\.head (.+)/
+            branch = Regexp.last_match(1)
+            detached = (branch == "(detached)")
+          when /\A# branch\.upstream (.+)/
+            upstream = Regexp.last_match(1)
+          when /\A# branch\.ab \+(\d+) -(\d+)/
+            ahead = Regexp.last_match(1).to_i
+            behind = Regexp.last_match(2).to_i
+          when /\A[12u?!]/
+            entries << line
+          end
+        end
+
+        Status.new(
+          clean: entries.empty?,
+          branch: branch,
+          upstream: upstream,
+          ahead: ahead,
+          behind: behind,
+          detached: detached,
+          entries: entries,
+          unborn: unborn
+        )
+      end
+    end
+  end
+end

data/vendor/repo-tender/lib/space_architect/pristine/scm/status.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SpaceArchitect::Pristine
+  module SCM
+    # Value object produced by parsing `git status --porcelain=v2
+    # --branch --untracked-files=normal`. v2 is mandatory (per
+    # AGENTS.md gotcha) so submodule state and rename detection are
+    # stable.
+    #
+    # A working tree is "clean" iff the only porcelain-v2 lines are the
+    # `# branch.*` header lines. Any `1`/`2`/`u`/`?`/`!` line is dirty.
+    Status = Data.define(:clean, :branch, :upstream, :ahead, :behind, :detached, :entries, :unborn) do
+      def initialize(clean:, branch: nil, upstream: nil, ahead: 0, behind: 0, detached: false, entries: [], unborn: false)
+        super
+      end
+
+      def clean? = clean
+
+      def detached? = detached
+
+      def unborn? = unborn
+    end
+  end
+end

data/vendor/repo-tender/lib/space_architect/pristine/shell.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "open3"
+require "async"
+require "dry/monads"
+
+module SpaceArchitect::Pristine
+  # Thin Open3.capture3 wrapper that:
+  #   * requires an ambient Async::Task (so subprocess I/O flows through
+  #     Ruby's Fiber scheduler → kqueue on macOS and is non-blocking);
+  #   * returns a Dry::Monads::Result — Success(stdout) on zero exit,
+  #     Failure({argv:, stderr:, status:}) otherwise.
+  #
+  # Per AGENTS.md: no `async-process`. Per PRD §2: boundaries return
+  # Result, exceptions are for programmer error only.
+  class Shell
+    extend Dry::Monads[:result]
+
+    @run_count = 0
+    @saved_roe = nil
+
+    def self.run(*argv, chdir: nil, env: nil)
+      raise ArgumentError, "Shell.run requires at least argv" if argv.empty?
+      raise "Shell.run must be called inside an ambient Async::Task" unless Async::Task.current?
+
+      full_env = env ? ENV.to_h.merge(env.transform_keys(&:to_s)) : nil
+      opts = {}
+      opts[:chdir] = chdir if chdir
+      # Open3.capture3: env is a leading hash positional arg, not a kwarg.
+      #
+      # Open3.capture3 spawns the child with two internal reader
+      # threads (one for stdout, one for stderr; see
+      # `rubylibdir/open3.rb` ~L644: `out_reader = Thread.new { o.read }`
+      # / `err_reader = Thread.new { e.read }`). When the `popen3`
+      # block exits via exception (e.g. the user ^C'd mid-Shell.run
+      # via SIGINT), `popen_run`'s ensure closes the read pipes from
+      # the main thread while those reader threads are still inside
+      # `o.read` / `e.read`. The mid-read close races with the reader
+      # and raises `IOError: stream closed in another thread` in the
+      # reader thread. With the default `Thread.report_on_exception
+      # = true` (since Ruby 2.5), Ruby prints a multi-line backtrace
+      # to stderr for that orphaned thread — exactly the noise
+      # Slice 6 G3 silences.
+      #
+      # We bracket the `Open3.capture3` call with a save/restore of
+      # `Thread.report_on_exception = false`. This is targeted
+      # because, at this code site, the ONLY threads in flight are:
+      #   * the main thread (this method's caller);
+      #   * Async's internal `io_select` thread
+      #     (`async/lib/async/scheduler.rb` L425) — which silences
+      #     its own report (`Thread.current.report_on_exception =
+      #     false` on that thread, not globally);
+      #   * the Open3 reader threads (the source of the noise).
+      # `lib/` has zero `Thread.new` calls; `dry-cli`, `dry-monads`,
+      # `dry-validation`, `dry-struct`, `dry-types`, `dry-schema`,
+      # `xdg` have none either (verified Slice 6 PHASE 0). So we are
+      # NOT hiding any app-owned worker-thread crashes — the only
+      # thread that can raise here is the Open3 reader thread, and
+      # the only thing it can raise is the IOError we explicitly
+      # want to silence. The original value is restored in `ensure`
+      # so we never leak the suppression past this call.
+      # Refcount the active Shell.run calls so the global flag is suppressed
+      # for the entire overlapping window, not just per-fiber. On 0→1: capture
+      # original and set false. On 1→0 (in ensure): restore the original.
+      # Safe without a Mutex: the reactor is single-threaded; fibers only yield
+      # at Open3.capture3's thread-join, never between these plain assignments.
+      if @run_count == 0
+        @saved_roe = Thread.report_on_exception
+        Thread.report_on_exception = false
+      end
+      @run_count += 1
+      begin
+        stdout, stderr, status = if full_env
+          Open3.capture3(full_env, *argv, **opts)
+        else
+          Open3.capture3(*argv, **opts)
+        end
+      ensure
+        @run_count -= 1
+        Thread.report_on_exception = @saved_roe if @run_count == 0
+      end
+
+      if status.success?
+        Success(stdout)
+      else
+        Failure({argv: argv, stderr: stderr, status: status.exitstatus})
+      end
+    end
+  end
+end

data/vendor/repo-tender/lib/space_architect/pristine/state/lock.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module SpaceArchitect::Pristine
+  module State
+    # Advisory process-level lock on a sidecar file derived from the
+    # state file path. Serializes overlapping `sync` runs so the
+    # later run bails cleanly rather than clobbering the in-flight
+    # run's state with a last-writer-wins atomic rename (CF10).
+    #
+    # The lockfile is a persistent zero-byte sentinel — never unlinked.
+    # Deleting a flock'd file while another fd holds it creates a race
+    # where both processes think they hold the lock on different inodes.
+    #
+    # `LOCK_NB` is for daemon safety, not reactor yielding: a blocking
+    # `LOCK_EX` would wedge a launchd tick forever behind a hung run.
+    # `flock` and the file I/O it guards are ordinary blocking syscalls
+    # with no Async scheduler hook — fine here, they're sub-millisecond
+    # on a local state dir, same as the rest of `State::Store`.
+    class Lock
+      NOT_ACQUIRED = :not_acquired
+
+      # Returns the sidecar lockfile path for a given state_file path.
+      def self.path_for(state_file)
+        "#{state_file}.lock"
+      end
+
+      # Acquires an exclusive non-blocking advisory lock on the sidecar
+      # lockfile. Creates the file (and its parent directory) if missing.
+      #
+      # Yields to the block and returns its value when the lock is
+      # acquired; releases the lock in an `ensure` so it is freed on
+      # normal return, explicit `return`, AND any escaping exception
+      # (including Interrupt / SignalException).
+      #
+      # Returns `NOT_ACQUIRED` *without* yielding when another process
+      # already holds the lock. The caller decides what to do (e.g.
+      # bail cleanly with a Success).
+      def self.acquire(state_file)
+        lock_path = path_for(state_file)
+        FileUtils.mkdir_p(File.dirname(lock_path))
+        f = File.open(lock_path, File::RDWR | File::CREAT)
+        # Everything that can raise — `flock` itself can (EINTR on a
+        # signal, ENOLCK on some filesystems) — runs inside the `begin`,
+        # so the `ensure` always closes the fd (no leak). Closing the fd
+        # releases the lock (it lives on the open file description), so
+        # no explicit LOCK_UN is needed — and `close` can't be skipped
+        # by a raising unlock.
+        begin
+          return NOT_ACQUIRED unless f.flock(File::LOCK_EX | File::LOCK_NB)
+          yield
+        ensure
+          f.close
+        end
+      end
+    end
+  end
+end

data/vendor/repo-tender/lib/space_architect/pristine/state/store.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+require "time"
+require "dry/monads"
+
+module SpaceArchitect::Pristine
+  module State
+    # Machine-managed state at $XDG_STATE_HOME/repo-tender/state.yaml.
+    # Never hand-edited (per PRD §3.2). Per-repo + per-org records with
+    # a fixed status enum; the store validates the enum and timestamp
+    # format on write.
+    class Store
+      extend Dry::Monads[:result]
+
+      STATUSES = %w[clean dirty diverged detached wrong_branch missing error].freeze
+
+      Repo = Data.define(:default_branch, :last_fetch_at, :last_synced_at, :status, :last_error) do
+        def initialize(default_branch: nil, last_fetch_at: nil, last_synced_at: nil, status: nil, last_error: nil)
+          super
+        end
+
+        def to_h_compact
+          {
+            "default_branch" => default_branch,
+            "last_fetch_at" => format_time(last_fetch_at),
+            "last_synced_at" => format_time(last_synced_at),
+            "status" => status,
+            "last_error" => last_error
+          }.compact
+        end
+
+        private
+
+        def format_time(t)
+          t.respond_to?(:iso8601) ? t.iso8601 : t
+        end
+      end
+
+      Org = Data.define(:last_listed_at, :repo_count, :last_error) do
+        def initialize(last_listed_at: nil, repo_count: 0, last_error: nil)
+          super
+        end
+
+        def to_h_compact
+          {
+            "last_listed_at" => format_time(last_listed_at),
+            "repo_count" => repo_count,
+            "last_error" => last_error
+          }.compact
+        end
+
+        private
+
+        # `last_listed_at` may arrive as a Time (fresh from the
+        # engine) or as a String (round-tripped from YAML, since
+        # `to_h_compact` always emits the iso8601 form on
+        # write). Both forms are written as the same string on
+        # the next emit; the helper accepts either.
+        def format_time(t)
+          return nil if t.nil?
+          t.respond_to?(:iso8601) ? t.iso8601 : t
+        end
+      end
+
+      def self.load(path)
+        raw = read_yaml(path)
+        Success(build_state(raw))
+      end
+
+      def self.write(path, state)
+        validation = validate(state)
+        return validation if validation.failure?
+
+        FileUtils.mkdir_p(File.dirname(path))
+        tmp = "#{path}.tmp.#{Process.pid}"
+        begin
+          File.write(tmp, emit(state))
+          File.rename(tmp, path)
+        ensure
+          File.delete(tmp) if File.exist?(tmp)
+        end
+        Success(state)
+      end
+
+      def self.validate(state)
+        state.repos.each do |key, repo|
+          unless STATUSES.include?(repo.status)
+            return Failure({repos: {key => {status: ["must be one of: #{STATUSES.join(", ")}"]}}})
+          end
+        end
+        Success(state)
+      end
+
+      def self.read_yaml(path)
+        return {} unless File.exist?(path)
+        # Time class permitted because state.yaml stores ISO8601
+        # timestamps; Psych will deserialize them as Time when the
+        # scalar is tagged. No other arbitrary classes allowed.
+        YAML.safe_load_file(path, permitted_classes: [Symbol, Time], aliases: false) || {}
+      end
+
+      def self.build_state(raw)
+        repos = (raw["repos"] || {}).each_with_object({}) do |(key, attrs), acc|
+          acc[key] = Repo.new(
+            default_branch: attrs["default_branch"],
+            last_fetch_at: attrs["last_fetch_at"],
+            last_synced_at: attrs["last_synced_at"],
+            status: attrs["status"],
+            last_error: attrs["last_error"]
+          )
+        end
+        orgs = (raw["orgs"] || {}).each_with_object({}) do |(key, attrs), acc|
+          acc[key] = Org.new(
+            last_listed_at: attrs["last_listed_at"],
+            repo_count: attrs["repo_count"] || 0,
+            last_error: attrs["last_error"]
+          )
+        end
+        State.new(repos: repos, orgs: orgs)
+      end
+
+      # State value object — top-level container.
+      State = Data.define(:repos, :orgs) do
+        def initialize(repos: {}, orgs: {})
+          super
+        end
+      end
+
+      def self.emit(state)
+        payload = {
+          "repos" => state.repos.each_with_object({}) { |(k, v), acc| acc[k] = v.to_h_compact },
+          "orgs" => state.orgs.each_with_object({}) { |(k, v), acc| acc[k] = v.to_h_compact }
+        }
+        YAML.dump(payload, line_width: -1)
+      end
+    end
+  end
+end