space-cadet 9.0.0

data/lib/space_core/repo_resolver.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Space::Core
+  class RepoResolver
+    SCP_LIKE_PATTERN = /\A(?:[^@\/]+@)?(?<provider>[^:\/]+):(?<path>.+)\z/
+    URL_PATTERN = %r{\A[A-Za-z][A-Za-z0-9+\-.]*://}
+
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+    end
+
+    def resolve(spec)
+      value = spec.to_s.strip
+      raise RepoResolutionError, "Repo cannot be blank" if value.empty?
+
+      if url_like?(value)
+        resolve_url(value)
+      elsif (match = value.match(SCP_LIKE_PATTERN))
+        reference_from_parts(
+          provider: match[:provider],
+          path_parts: split_repo_path(match[:path]),
+          clone_url: value,
+          source: value
+        )
+      else
+        resolve_shorthand(value)
+      end
+    end
+
+    private
+
+    def resolve_url(value)
+      uri = URI.parse(value)
+      provider = uri.host
+      path = uri.path.to_s.delete_prefix("/")
+      raise RepoResolutionError, "Could not determine provider from '#{value}'" if provider.to_s.empty?
+
+      reference_from_parts(
+        provider: provider,
+        path_parts: split_repo_path(path),
+        clone_url: value,
+        source: value
+      )
+    rescue URI::InvalidURIError
+      raise RepoResolutionError, "Could not parse repo URL '#{value}'"
+    end
+
+    def resolve_shorthand(value)
+      parts = split_repo_path(value)
+
+      if parts.length == 1
+        resolve_default_organization_repo(parts.first, value)
+      elsif provider_like?(parts.first) && parts.length >= 3
+        reference_from_parts(
+          provider: parts.first,
+          path_parts: parts[1..],
+          clone_url: nil,
+          source: value
+        )
+      else
+        resolve_default_provider_repo(parts, value)
+      end
+    end
+
+    def resolve_default_organization_repo(name, source)
+      provider = require_default_provider(source)
+      owner = config.default_organization
+      unless owner
+        raise RepoResolutionError,
+              "Repo '#{source}' needs an organization. Set one with: space config set default_organization ORG"
+      end
+
+      reference(provider:, owner:, name:, clone_url: nil, source:)
+    end
+
+    def resolve_default_provider_repo(parts, source)
+      provider = require_default_provider(source)
+      reference_from_parts(provider:, path_parts: parts, clone_url: nil, source:)
+    end
+
+    def reference_from_parts(provider:, path_parts:, clone_url:, source:)
+      if path_parts.length < 2
+        raise RepoResolutionError, "Repo '#{source}' must include an organization and repo name"
+      end
+
+      name = path_parts.last
+      owner = path_parts[0...-1].join("/")
+      reference(provider:, owner:, name:, clone_url:, source:)
+    end
+
+    def reference(provider:, owner:, name:, clone_url:, source:)
+      normalized_provider = normalize_provider(provider)
+      normalized_owner = normalize_path_part(owner)
+      normalized_name = normalize_repo_name(name)
+
+      RepoReference.new(
+        provider: normalized_provider,
+        owner: normalized_owner,
+        name: normalized_name,
+        clone_url: clone_url || clone_url_for(normalized_provider, normalized_owner, normalized_name),
+        source: source
+      )
+    end
+
+    def clone_url_for(provider, owner, name)
+      case config.git_clone_protocol
+      when "ssh"
+        "git@#{provider}:#{owner}/#{name}.git"
+      when "https"
+        "https://#{provider}/#{owner}/#{name}.git"
+      end
+    end
+
+    def split_repo_path(value)
+      normalized = value.to_s.strip.delete_prefix("/").delete_suffix("/")
+      normalized = normalized.delete_suffix(".git")
+      parts = normalized.split("/").reject(&:empty?)
+      raise RepoResolutionError, "Repo '#{value}' must include a repo name" if parts.empty?
+
+      parts
+    end
+
+    def require_default_provider(source)
+      config.default_provider || raise(
+        RepoResolutionError,
+        "Repo '#{source}' needs a provider. Set one with: space config set default_provider PROVIDER"
+      )
+    end
+
+    def normalize_provider(value)
+      normalized = value.to_s.strip
+      normalized = normalized.delete_prefix("https://")
+      normalized = normalized.delete_prefix("http://")
+      normalized = normalized.delete_prefix("ssh://")
+      normalized = normalized.delete_suffix("/")
+      raise RepoResolutionError, "Provider cannot be blank" if normalized.empty?
+
+      normalized
+    end
+
+    def normalize_path_part(value)
+      normalized = value.to_s.strip.delete_prefix("/").delete_suffix("/")
+      raise RepoResolutionError, "Organization cannot be blank" if normalized.empty?
+
+      normalized
+    end
+
+    def normalize_repo_name(value)
+      normalized = value.to_s.strip.delete_suffix(".git")
+      raise RepoResolutionError, "Repo name cannot be blank" if normalized.empty?
+
+      normalized
+    end
+
+    def url_like?(value)
+      value.match?(URL_PATTERN)
+    end
+
+    def provider_like?(value)
+      value.include?(".") || value.include?(":") || value == "localhost"
+    end
+  end
+end

data/lib/space_core/scm/client.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+
+module Space::Core
+  module SCM
+    # Abstract SCM interface. The git CLI is the only implementation for
+    # now (per AGENTS.md / PRD §1), but the sync engine + tests must
+    # code to this interface so a future SCM is a drop-in.
+    #
+    # Every method returns a Dry::Monads::Result. Programmer error
+    # (e.g. nil path) is a raise; expected failures (no .git, non-fast-
+    # forward, network down) are Failure.
+    class Client
+      extend Dry::Monads[:result]
+
+      # Parse the working-tree status of a repo on disk. Implementation
+      # must read porcelain v2 (per AGENTS.md gotcha) and report a
+      # `SCM::Status` value object.
+      def status(path)
+        raise NotImplementedError
+      end
+
+      # Returns the current branch name, or nil if HEAD is detached.
+      def current_branch(path)
+        raise NotImplementedError
+      end
+
+      # Returns the bare remote's HEAD (e.g. "main" or "trunk"). Must
+      # work even when the default branch is not "main". May do a
+      # one-shot network call (`git remote set-head origin -a`) to
+      # refresh a stale `origin/HEAD`.
+      def default_branch(path)
+        raise NotImplementedError
+      end
+
+      # Returns the mtime of .git/FETCH_HEAD, or nil if absent. Treated
+      # as a freshness hint (PRD §3.3 step 4 + gate G5).
+      def last_fetch_at(path)
+        raise NotImplementedError
+      end
+
+      # `git fetch --prune --no-tags origin`.
+      def fetch(path)
+        raise NotImplementedError
+      end
+
+      # `git merge --ff-only origin/<default>`. Returns Failure if the
+      # local branch has diverged (left count > 0) — never resets.
+      # On Success: returns Integer commit count pulled.
+      #   0  → already up to date (no merge performed)
+      #   N  → fast-forwarded N commits
+      def fast_forward(path, default_branch)
+        raise NotImplementedError
+      end
+
+      # `git clone <url> <path>`.
+      def clone(url, path)
+        raise NotImplementedError
+      end
+
+      # `git switch <branch>`. Switches the local repo to the given
+      # branch. By default `git switch` refuses to clobber a dirty
+      # working tree (the operation is aborted on local-change loss
+      # per `man git-switch`); the engine treats that as a Failure.
+      # The engine is responsible for the upstream dirty-tree guard
+      # (per Slice 2 gate G5 / PHASE-0 ruling): the plan returns
+      # `:report_wrong_branch` / `:report_detached` for a dirty tree,
+      # so this method is only called on clean trees.
+      def switch(path, branch)
+        raise NotImplementedError
+      end
+
+      # Sync an unborn (empty) local clone. Called when the repo has no
+      # commits (`status.unborn? == true`) and the working tree is clean.
+      # Returns Success(:empty) when the remote has no branches (valid
+      # empty clone; no mutation). Returns Success(:fast_forwarded) when
+      # the remote has gained commits and the local clone was advanced to
+      # them. Returns Failure on a real network/probe error (the
+      # empty-vs-error distinction is made via `git ls-remote --heads
+      # origin`: exit 0 = definitive answer; non-zero = real error).
+      def sync_empty(path)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/space_core/scm/git.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+require "space_core/scm/client"
+require "space_core/scm/status"
+require "space_core/shell"
+
+module Space::Core
+  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/lib/space_core/scm/status.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Space::Core
+  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/lib/space_core/shell.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "open3"
+require "async"
+require "dry/monads"
+
+module Space::Core
+  # 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