space-architect 1.1.0

data/vendor/repo-tender/lib/space_architect/pristine/launchd/agent.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require "async"
+require "space_architect/pristine/shell"
+require "space_architect/pristine/launchd/plist"
+
+module SpaceArchitect::Pristine
+  module Launchd
+    # launchctl wrapper. Holds an injected command runner (the
+    # real default goes through `SpaceArchitect::Pristine::Shell` inside a
+    # `Sync{}` block; tests inject a `RecordingRunner` that
+    # captures argv and returns canned output — gate G2).
+    #
+    # All public methods return `Dry::Monads::Result`. A non-zero
+    # `launchctl` exit surfaces as `Failure({argv:, stderr:,
+    # status:})` — the same shape `Shell.run` uses — NOT a
+    # raise. A non-zero `runner` exit propagates as `Failure` to
+    # the caller.
+    #
+    # Domain: every operation targets `gui/<UID>` (the user's
+    # per-GUI-session launchd domain — the conventional domain
+    # for user-installed LaunchAgents on macOS). The UID is
+    # resolved via `Process.uid` by default; tests may inject
+    # a different UID to assert the exact argv (G2).
+    class Agent
+      extend Dry::Monads[:result]
+
+      DEFAULT_LABEL = "io.github.jetpks.repo-tender.sync"
+
+      # The default real-runner. Wraps `Shell.run` in a `Sync{}`
+      # block so the Fiber-scheduler requirement is satisfied.
+      # Outside an ambient Async::Task, `Shell.run` would raise;
+      # the wrapper creates one. This is the only place the
+      # production code path touches `Shell` for launchctl.
+      class ShellRunner
+        def run(*argv, **opts)
+          Sync do |_task|
+            if opts.empty?
+              Shell.run(*argv)
+            else
+              Shell.run(*argv, **opts)
+            end
+          end
+        end
+      end
+
+      def initialize(runner: ShellRunner.new, uid: Process.uid, label: DEFAULT_LABEL)
+        @runner = runner
+        @uid = uid
+        @label = label
+      end
+
+      attr_reader :label
+
+      # `launchctl bootstrap gui/<UID> <abs-plist-path>`
+      def install(plist_path)
+        run("bootstrap", "gui/#{@uid}", plist_path)
+      end
+
+      # `launchctl bootout gui/<UID>/<label>`
+      #
+      # Idempotency (Slice 5 / CF5): a benign bootout Failure
+      # (status 3 / "No such process" / "Could not find
+      # specified service") is mapped to **Success** —
+      # uninstalling a not-loaded agent is a no-op for the
+      # bootout step. The plist removal in the CLI command
+      # layer is independent of this result.
+      def uninstall
+        r = run("bootout", "gui/#{@uid}/#{@label}")
+        return Dry::Monads::Success("") if benign_bootout_failure?(r)
+        r
+      end
+
+      # bootstrap the plist, then `enable` the service.
+      # Both must succeed (both 0 exit) for the operation to
+      # be a `Success`; the first failure short-circuits.
+      def start(plist_path)
+        r1 = run("bootstrap", "gui/#{@uid}", plist_path)
+        return r1 if r1.failure?
+        run("enable", "gui/#{@uid}/#{@label}")
+      end
+
+      # bootout the service, then `disable` it.
+      #
+      # Idempotency (Slice 5 / CF5): a `bootout` Failure with
+      # `status == 3` ("No such process") or matching the
+      # not-loaded stderr is treated as **already not loaded**
+      # and is not propagated — the disable step still runs so
+      # the persistent `disable` override stays in place
+      # (matching the gate's recorded-argv assertion
+      # `[[bootout,…], [disable,…]]` and the
+      # "stopped" semantic). A non-benign bootout Failure
+      # (e.g. status 1 "Operation not permitted") short-
+      # circuits as before.
+      def stop
+        r1 = run("bootout", "gui/#{@uid}/#{@label}")
+        return r1 if r1.failure? && !benign_bootout_failure?(r1)
+        run("disable", "gui/#{@uid}/#{@label}")
+      end
+
+      # `launchctl kickstart -k gui/<UID>/<label>` — `-k` kills
+      # the running instance first so the new one always starts.
+      def restart
+        run("kickstart", "-k", "gui/#{@uid}/#{@label}")
+      end
+
+      # Returns a defensive parse of `launchctl list` (the
+      # machine-readable form — `launchctl print` is documented
+      # as "not API"). We run `launchctl list` (no service
+      # target) and search the output for our label.
+      #
+      # The parser tolerates: empty output, a "Could not find"
+      # line, malformed rows, and PID values that are not
+      # integers. On any of those, we return Success(loaded:
+      # false) — the gate G4 "no raise on malformed" guarantee.
+      def status
+        result = run("list")
+        return result if result.failure?
+        parse_list(result.success)
+      end
+
+      # ----- internal: argv dispatch + list parser -----
+
+      private
+
+      # CF5: a `bootout` Failure whose `status == 3` ("No such
+      # process") OR whose stderr matches the
+      # not-loaded markers is **not a real failure** — the
+      # service is simply not currently loaded, which is the
+      # common case at a 6h refresh interval. We key on
+      # `argv[1] == "bootout"` so the benign mapping is
+      # strictly scoped to bootout (bootstrap status-3
+      # remains a real Failure — gate G3 regression guard).
+      #
+      # Status 3 is the POSIX `ESRCH` errno (`launchctl error 3`
+      # → "No such process") and is the documented signal.
+      # The stderr regex is the defensive OR — `launchctl`
+      # stderr text is NOT API and may drift; we accept both
+      # observed phrasings ("No such process" from recent
+      # macOS, "Could not find specified service" from older
+      # releases / the legacy `unload` path).
+      def benign_bootout_failure?(result)
+        return false unless result.failure?
+
+        f = result.failure
+        return false unless f.is_a?(Hash)
+
+        argv = f[:argv]
+        return false unless argv.is_a?(Array) && argv[1] == "bootout"
+
+        return true if f[:status] == 3
+        stderr = f[:stderr].to_s
+        stderr.match?(/No such process|Could not find specified service/i)
+      end
+
+      # Every operation is a `launchctl` subcommand — the program
+      # name must be argv[0] so the runner (real `Shell.run` →
+      # Open3) actually execs `launchctl`, not the bare subcommand.
+      def run(*argv)
+        @runner.run("launchctl", *argv)
+      end
+
+      # Parses the tabular output of `launchctl list`. Each line
+      # is three tab-separated fields: PID, Status (last exit
+      # code), Label. PID is "-" if the job is not currently
+      # running. A line whose label matches ours is the row we
+      # want; everything else is ignored.
+      def parse_list(output)
+        return Dry::Monads::Success({loaded: false, running: false, last_exit: nil, pid: nil}) if output.nil? || output.empty?
+
+        output.each_line do |line|
+          fields = line.chomp.split("\t", 3)
+          next if fields.length < 3
+          pid_s, status_s, lbl = fields
+          next unless lbl == @label
+          pid = (pid_s == "-" || pid_s.nil? || pid_s.empty?) ? nil : Integer(pid_s, exception: false)
+          status = (status_s == "-" || status_s.nil? || status_s.empty?) ? nil : Integer(status_s, exception: false)
+          return Dry::Monads::Success({
+            loaded: true,
+            running: !pid.nil?,
+            pid: pid,
+            last_exit: status
+          })
+        end
+
+        Dry::Monads::Success({loaded: false, running: false, last_exit: nil, pid: nil})
+      rescue => e
+        # Defensive: any unexpected parse failure is reported as
+        # "unknown" — NOT a raise (gate G4).
+        Dry::Monads::Success({loaded: false, running: false, last_exit: nil, pid: nil, error: e.message})
+      end
+    end
+  end
+end

data/vendor/repo-tender/lib/space_architect/pristine/launchd/plist.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module SpaceArchitect::Pristine
+  module Launchd
+    # Hand-rolled launchd plist emitter. The slice forbids a plist
+    # gem (PRD §2, AGENTS.md) — this class emits an XML property
+    # list as a string and is validated offline with `plutil -lint`.
+    #
+    # The plist produced here is a fixed-shape StartInterval-driven
+    # agent that:
+    #   * runs `repo-tender sync` non-interactively under the
+    #     repo's mise-managed Ruby (so the right toolchain is in
+    #     effect without `mise activate`, which is broken
+    #     non-interactively);
+    #   * is classified as a Background process (lower scheduling
+    #     + I/O priority — sync is a periodic background job);
+    #   * writes its stdout/stderr to absolute log files under
+    #     the log dir (launchd owns the redirect, the sync process
+    #     rotates its own log on each run — see LogRotator);
+    #   * has NO `KeepAlive` key — it is a periodic, not a daemon.
+    #
+    # The caller is responsible for passing absolute paths. We do
+    # NOT `File.expand_path` here — that would mask the caller's
+    # responsibility to pass absolute paths (the G1 / G3 gates
+    # assert that no `~` or `$HOME` appears in any value).
+    class Plist
+      # The plist's outer XML decl + DOCTYPE — required by
+      # plutil's lint and by launchd's parser.
+      HEADER = <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+        <plist version="1.0">
+        <dict>
+      XML
+      FOOTER = "</dict>\n</plist>\n"
+
+      class << self
+        # Emit a launchd plist for a sync job.
+        #
+        # @param label [String]              The job label (must be a valid reverse-DNS string; appears as the basename of the on-disk plist).
+        # @param refresh_interval [Integer] StartInterval in seconds (must be > 0).
+        # @param log_dir [String]            Absolute directory for the standard-out / standard-err logs.
+        # @param repo_root [String]          Absolute path to set as WorkingDirectory (so mise finds the repo's mise.toml).
+        # @param mise_toml [String]          Absolute path to mise.toml (pinned via EnvironmentVariables.MISE_CONFIG_FILE).
+        # @param mise_bin [String]           Absolute path to the mise binary (ProgramArguments[0]).
+        # @param ruby_bin [String]           Absolute path to the ruby to run the script under.
+        # @param bin_path [String]           Absolute path to the repo-tender bin script.
+        # @return [String]                   The full plist XML, ready to be written to disk and `plutil -lint`-validated.
+        def call(label:, refresh_interval:, log_dir:, repo_root:, mise_toml:, mise_bin:, ruby_bin:, bin_path:)
+          raise ArgumentError, "label is required" if label.to_s.empty?
+          raise ArgumentError, "refresh_interval must be > 0" unless refresh_interval.is_a?(Integer) && refresh_interval > 0
+          %w[log_dir repo_root mise_toml mise_bin ruby_bin bin_path].each do |k|
+            v = binding.local_variable_get(k)
+            raise ArgumentError, "#{k} must be absolute (got #{v.inspect})" unless v.is_a?(String) && File.absolute_path?(v)
+          end
+
+          out_log = File.join(log_dir, "#{label}.out.log")
+          err_log = File.join(log_dir, "#{label}.err.log")
+
+          body = +""
+          body << key("Label") << string(label) << "\n"
+          body << key("ProgramArguments") << "\n" << array([
+            mise_bin,
+            "exec",
+            "--",
+            ruby_bin,
+            bin_path,
+            "sync"
+          ])
+          body << key("WorkingDirectory") << string(repo_root) << "\n"
+          body << key("EnvironmentVariables") << "\n" << dict({
+            "MISE_CONFIG_FILE" => mise_toml
+          })
+          body << key("StartInterval") << integer(refresh_interval) << "\n"
+          body << key("RunAtLoad") << boolean(true) << "\n"
+          body << key("ProcessType") << string("Background") << "\n"
+          body << key("StandardOutPath") << string(out_log) << "\n"
+          body << key("StandardErrorPath") << string(err_log) << "\n"
+
+          HEADER + body + FOOTER
+        end
+
+        private
+
+        def key(name)
+          "  <key>#{escape(name)}</key>\n"
+        end
+
+        # XML-escape: & must be first, then <, >, " and ' in attribute values
+        # (we only emit element text, but be safe for both).
+        def escape(s)
+          s.to_s
+            .gsub("&", "&amp;")
+            .gsub("<", "&lt;")
+            .gsub(">", "&gt;")
+            .gsub("\"", "&quot;")
+            .gsub("'", "&apos;")
+        end
+
+        def string(s)
+          "  <string>#{escape(s)}</string>"
+        end
+
+        def integer(i)
+          "  <integer>#{Integer(i)}</integer>"
+        end
+
+        def boolean(b)
+          "  <#{b ? "true" : "false"}/>"
+        end
+
+        def array(items)
+          out = +"  <array>\n"
+          items.each { |arg| out << "    <string>#{escape(arg)}</string>\n" }
+          out << "  </array>"
+        end
+
+        def dict(hash)
+          out = +"  <dict>\n"
+          hash.each do |k, v|
+            out << "    <key>#{escape(k)}</key>\n"
+            out << "    <string>#{escape(v)}</string>\n"
+          end
+          out << "  </dict>"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+require "dry/monads"
+
+module SpaceArchitect::Pristine
+  # Rotates a log file when it exceeds a byte threshold. The
+  # archive's filename embeds an ISO-8601-compact timestamp
+  # (`YYYYMMDDTHHMMSSZ`) of the rotation event (the injected
+  # `now` — deterministic in tests, real `Time.now` in
+  # production). The rename is byte-for-byte — no copy, no
+  # data loss.
+  #
+  # The sync process calls this at the top of `Run#call` to
+  # rotate the two plist log paths (`<label>.out.log` and
+  # `<label>.err.log`). launchd opens those files fresh on the
+  # next spawn; the current process's inherited fd still points
+  # to the renamed file (writes succeed; the file is the
+  # archive). After the process exits, launchd re-opens a new
+  # file at the original path. This is the mechanism the spec
+  # asked for (gate G5).
+  class LogRotator
+    extend Dry::Monads[:result]
+
+    # @param log_path [String]           absolute path to the log file to potentially rotate
+    # @param threshold_bytes [Integer]   rotation threshold; > this many bytes ⇒ rotate
+    # @param now [Time]                  the timestamp to embed in the archive filename
+    # @return [Dry::Monads::Result<Hash>] Success({rotated: bool, archive_path: String|nil})
+    def self.call(log_path, threshold_bytes:, now: Time.now)
+      return Success({rotated: false, archive_path: nil, reason: "missing"}) unless File.exist?(log_path)
+      return Success({rotated: false, archive_path: nil, reason: "under_threshold"}) if File.size(log_path) <= threshold_bytes
+
+      archive = build_archive_path(log_path, now)
+      FileUtils.mv(log_path, archive)
+      Success({rotated: true, archive_path: archive, reason: "oversized"})
+    rescue => e
+      Failure({log_path: log_path, error: e.class.name, message: e.message})
+    end
+
+    def self.build_archive_path(log_path, now)
+      ts = now.utc.strftime("%Y%m%dT%H%M%SZ")
+      "#{log_path}.#{ts}"
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "xdg"
+require "fileutils"
+
+module SpaceArchitect::Pristine
+  # XDG-aware path resolution. Honors $XDG_CONFIG_HOME / $XDG_STATE_HOME
+  # overrides (and a caller-supplied environment hash for testability);
+  # otherwise falls back to the XDG defaults (~/.config, ~/.local/state).
+  #
+  # `base_dir` is the on-disk home for the src clones
+  # ($BASE/:host/:owner/:repo). It defaults to ~/architect/src and is
+  # resolved from the config at call time (passed in as an argument here
+  # so this module owns nothing about config storage).
+  class Paths
+    APP_NAME = "repo-tender"
+
+    DEFAULT_BASE_DIR = File.expand_path("~/architect/src")
+
+    def initialize(environment: ENV, base_dir: nil)
+      @environment = environment
+      @base_dir = base_dir
+    end
+
+    def config_home = xdg.config_home.to_s
+
+    def state_home = xdg.state_home.to_s
+
+    def config_dir = File.join(config_home, APP_NAME)
+
+    def config_file = File.join(config_dir, "config.yaml")
+
+    def state_dir = File.join(state_home, APP_NAME)
+
+    def state_file = File.join(state_dir, "state.yaml")
+
+    def log_dir = File.join(state_dir, "logs")
+
+    # Per-user launchd agent directory. The user's
+    # `~/Library/LaunchAgents/` (PRD §3.2; slice-4 Lane 01). The
+    # path is resolved from the env's HOME so tests can inject a
+    # temp HOME via `Paths.new(environment:)` and assert that
+    # install/uninstall NEVER writes to the real
+    # `~/Library/LaunchAgents` (gate G3).
+    def launch_agents_dir
+      home = @environment["HOME"] || Dir.home
+      File.join(home, "Library", "LaunchAgents")
+    end
+
+    # Default `base_dir` is ~/architect/src. Callers may override by passing
+    # one to the constructor (e.g. from loaded config).
+    def base_dir
+      @base_dir || DEFAULT_BASE_DIR
+    end
+
+    # Ensure the on-disk directories exist. The config file itself is
+    # optional and created lazily by Config::Store; we only ensure parent
+    # dirs. Idempotent.
+    def ensure!
+      FileUtils.mkdir_p(config_dir)
+      FileUtils.mkdir_p(state_dir)
+      FileUtils.mkdir_p(log_dir)
+      self
+    end
+
+    private
+
+    def xdg
+      @xdg ||= XDG::Environment.new(environment: @environment)
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+
+module SpaceArchitect::Pristine
+  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