space-architect 8.0.0 → 9.0.0

data/lib/space_src/shell_integration.rb

@@ -1,321 +0,0 @@
-# frozen_string_literal: true
-
-require "fileutils"
-require "pathname"
-
-module Space::Src
-  # Generates the standalone `src` fish shell integration and completions.
-  # All paths resolved through Space::Src::Paths (no external core deps).
-  module ShellIntegration
-    FISH_TEMPLATE = <<~'FISH'
-      # Generated by space-src. Do not edit by hand.
-
-      function src --wraps src --description "Navigate source checkouts"
-          if not set -q __src_compat_checked
-              set -g __src_compat_checked 1
-              set -l __src_installed_version __SRC_VERSION__
-              set -l __src_binary_version (command src --version 2>/dev/null)
-              if test "$__src_binary_version" != "$__src_installed_version"
-                  echo "space-src: shell integration version $__src_installed_version does not match binary version $__src_binary_version; re-run 'src shell fish install'" >&2
-              end
-          end
-
-          switch "$argv[1]"
-              case repo org sync status config daemon clone shell
-                  command src $argv
-                  return $status
-              case '*'
-                  set -l __src_output (command src $argv)
-                  set -l __src_status $status
-
-                  if test (count $__src_output) -gt 0
-                      printf "%s\n" $__src_output
-                  end
-
-                  if test $__src_status -eq 0
-                      set -l __src_target $__src_output[-1]
-                      set __src_target (string replace -r "^~(?=/|$)" $HOME -- $__src_target)
-                      if test -d "$__src_target"
-                          cd "$__src_target"
-                      end
-                  end
-
-                  return $__src_status
-          end
-      end
-    FISH
-
-    FISH_COMPLETIONS = <<~'FISH'
-      # Generated by space-src. Do not edit by hand.
-
-      function __src_complete_command
-          set -l tokens (commandline -opc)
-          set -l index 2
-
-          while test $index -le (count $tokens)
-              set -l token $tokens[$index]
-
-              switch "$token"
-                  case "-*"
-                      set index (math $index + 1)
-                      continue
-                  case "*"
-                      echo $token
-                      return 0
-              end
-          end
-      end
-
-      function __src_complete_needs_command
-          test -z "(__src_complete_command)"
-      end
-
-      function __src_complete_using_command
-          contains -- (__src_complete_command) $argv
-      end
-
-      function __src_complete_first_argument_after
-          set -l commands $argv
-          set -l tokens (commandline -opc)
-          set -l index 2
-          set -l matched_command 0
-
-          while test $index -le (count $tokens)
-              set -l token $tokens[$index]
-
-              switch "$token"
-                  case "-*"
-                      set index (math $index + 1)
-                      continue
-              end
-
-              if test $matched_command -eq 0
-                  if contains -- "$token" $commands
-                      set matched_command 1
-                  else
-                      return 1
-                  end
-              else
-                  echo $token
-                  return 0
-              end
-
-              set index (math $index + 1)
-          end
-
-          return 1
-      end
-
-      function __src_complete_has_first_argument_after
-          set -q argv[1]; or return 1
-          set -l first_argument (__src_complete_first_argument_after $argv)
-          test -n "$first_argument"
-      end
-
-      function __src_complete_second_argument_after
-          set -q argv[1]; or return 1
-          set -l command $argv[1]
-          set -l tokens (commandline -opc)
-          set -l index 2
-          set -l matched_command 0
-          set -l matched_first_argument 0
-
-          while test $index -le (count $tokens)
-              set -l token $tokens[$index]
-
-              switch "$token"
-                  case "-*"
-                      set index (math $index + 1)
-                      continue
-              end
-
-              if test $matched_command -eq 0
-                  test "$token" = "$command"; or return 1
-                  set matched_command 1
-              else if test $matched_first_argument -eq 0
-                  set matched_first_argument 1
-              else
-                  echo $token
-                  return 0
-              end
-
-              set index (math $index + 1)
-          end
-
-          return 1
-      end
-
-      function __src_complete_has_second_argument_after
-          set -q argv[1]; or return 1
-          set -l second_argument (__src_complete_second_argument_after $argv)
-          test -n "$second_argument"
-      end
-
-      function __src_complete_first_argument_is
-          set -q argv[1]; or return 1
-          set -l expected $argv[1]
-          set -e argv[1]
-          test "$(__src_complete_first_argument_after $argv)" = "$expected"
-      end
-
-      function __src_complete_checkouts
-          command src shell complete checkouts 2>/dev/null
-      end
-
-      function __src_complete_shells
-          command src shell complete shells 2>/dev/null
-      end
-
-      complete -c src -f -n "__src_complete_needs_command" -a clone   -d "Clone a repo into the source tree"
-      complete -c src -f -n "__src_complete_needs_command" -a config  -d "Show or update config"
-      complete -c src -f -n "__src_complete_needs_command" -a daemon  -d "Manage the background sync daemon"
-      complete -c src -f -n "__src_complete_needs_command" -a org     -d "Manage tracked GitHub orgs"
-      complete -c src -f -n "__src_complete_needs_command" -a repo    -d "Manage tracked repos"
-      complete -c src -f -n "__src_complete_needs_command" -a shell   -d "Manage shell integration"
-      complete -c src -f -n "__src_complete_needs_command" -a status  -d "Show sync status"
-      complete -c src -f -n "__src_complete_needs_command" -a sync    -d "Sync all tracked repos"
-      complete -c src -f -n "__src_complete_needs_command" -a "(__src_complete_checkouts)" -d "Checkout"
-
-      complete -c src -f -n "__src_complete_using_command config; and not __src_complete_has_first_argument_after config" -a path -d "Print config path"
-      complete -c src -f -n "__src_complete_using_command config; and not __src_complete_has_first_argument_after config" -a show -d "Show config"
-
-      complete -c src -f -n "__src_complete_using_command org; and not __src_complete_has_first_argument_after org" -a add    -d "Add a GitHub org"
-      complete -c src -f -n "__src_complete_using_command org; and not __src_complete_has_first_argument_after org" -a remove -d "Remove a GitHub org"
-      complete -c src -f -n "__src_complete_using_command org; and not __src_complete_has_first_argument_after org" -a list   -d "List tracked orgs"
-
-      complete -c src -f -n "__src_complete_using_command repo; and not __src_complete_has_first_argument_after repo" -a add    -d "Add a repo"
-      complete -c src -f -n "__src_complete_using_command repo; and not __src_complete_has_first_argument_after repo" -a remove -d "Remove a repo"
-      complete -c src -f -n "__src_complete_using_command repo; and not __src_complete_has_first_argument_after repo" -a list   -d "List repos"
-
-      complete -c src -f -n "__src_complete_using_command daemon; and not __src_complete_has_first_argument_after daemon" -a install   -d "Install launchd agent"
-      complete -c src -f -n "__src_complete_using_command daemon; and not __src_complete_has_first_argument_after daemon" -a uninstall -d "Uninstall launchd agent"
-      complete -c src -f -n "__src_complete_using_command daemon; and not __src_complete_has_first_argument_after daemon" -a start     -d "Start the agent"
-      complete -c src -f -n "__src_complete_using_command daemon; and not __src_complete_has_first_argument_after daemon" -a stop      -d "Stop the agent"
-      complete -c src -f -n "__src_complete_using_command daemon; and not __src_complete_has_first_argument_after daemon" -a restart   -d "Restart the agent"
-      complete -c src -f -n "__src_complete_using_command daemon; and not __src_complete_has_first_argument_after daemon" -a status    -d "Show agent status"
-
-      complete -c src -f -n "__src_complete_using_command shell; and not __src_complete_has_first_argument_after shell" -a init     -d "Print shell integration"
-      complete -c src -f -n "__src_complete_using_command shell; and not __src_complete_has_first_argument_after shell" -a fish     -d "Manage fish integration and completions"
-      complete -c src -f -n "__src_complete_using_command shell; and not __src_complete_has_first_argument_after shell" -a complete -d "Print completion candidates"
-
-      complete -c src -f -n "__src_complete_first_argument_is fish shell; and not __src_complete_has_second_argument_after shell" -a install   -d "Install fish integration and completions"
-      complete -c src -f -n "__src_complete_first_argument_is fish shell; and not __src_complete_has_second_argument_after shell" -a uninstall -d "Remove fish integration and completions"
-      complete -c src -f -n "__src_complete_first_argument_is fish shell; and not __src_complete_has_second_argument_after shell" -a path      -d "Print fish integration paths"
-
-      complete -c src -f -n "__src_complete_first_argument_is init shell; and not __src_complete_has_second_argument_after shell" -a "(__src_complete_shells)" -d "Shell"
-      complete -c src -f -n "__src_complete_first_argument_is complete shell; and not __src_complete_has_second_argument_after shell" -a "checkouts shells" -d "Completion kind"
-    FISH
-
-    def self.for(shell)
-      case shell.to_s
-      when "fish"
-        FISH_TEMPLATE.gsub("__SRC_VERSION__", Space::Src::VERSION)
-      else
-        raise "Unsupported shell '#{shell}'. Expected: fish"
-      end
-    end
-
-    def self.completions_for(shell)
-      case shell.to_s
-      when "fish"
-        FISH_COMPLETIONS
-      else
-        raise "Unsupported shell '#{shell}'. Expected: fish"
-      end
-    end
-
-    def self.path_for(shell, env: ENV)
-      case shell.to_s
-      when "fish"
-        Pathname(Paths.new(environment: env).config_home).join("fish", "functions", "src.fish")
-      else
-        raise "Unsupported shell '#{shell}'. Expected: fish"
-      end
-    end
-
-    def self.completions_path_for(shell, env: ENV)
-      case shell.to_s
-      when "fish"
-        Pathname(Paths.new(environment: env).config_home).join("fish", "completions", "src.fish")
-      else
-        raise "Unsupported shell '#{shell}'. Expected: fish"
-      end
-    end
-
-    def self.install(shell, env: ENV, force: false)
-      fn_result = write_managed_file(
-        path: path_for(shell, env:),
-        content: self.for(shell),
-        force: force,
-        description: "fish function"
-      )
-      co_result = write_managed_file(
-        path: completions_path_for(shell, env:),
-        content: completions_for(shell),
-        force: force,
-        description: "fish completions"
-      )
-      fn_result.merge(
-        completions_action: co_result.fetch(:action),
-        completions_path: co_result.fetch(:path)
-      )
-    end
-
-    def self.uninstall(shell, env: ENV, force: false)
-      fn_result = remove_managed_file(
-        path: path_for(shell, env:),
-        content: self.for(shell),
-        force: force,
-        description: "fish function"
-      )
-      co_result = remove_managed_file(
-        path: completions_path_for(shell, env:),
-        content: completions_for(shell),
-        force: force,
-        description: "fish completions"
-      )
-      fn_result.merge(
-        completions_action: co_result.fetch(:action),
-        completions_path: co_result.fetch(:path)
-      )
-    end
-
-    def self.managed_src?(content)
-      content.include?("Generated by space-src")
-    end
-
-    private_class_method def self.write_managed_file(path:, content:, force:, description:)
-      existing = File.read(path) if File.exist?(path)
-
-      if existing && existing != content && !force && !managed_src?(existing)
-        raise "Refusing to overwrite existing #{description} at #{path}. Re-run with --force."
-      end
-
-      if existing == content
-        {action: :unchanged, path: path}
-      else
-        FileUtils.mkdir_p(File.dirname(path))
-        tmp = "#{path}.tmp.#{Process.pid}"
-        begin
-          File.write(tmp, content)
-          File.rename(tmp, path)
-        ensure
-          File.delete(tmp) if File.exist?(tmp)
-        end
-        {action: existing ? :updated : :installed, path: path}
-      end
-    end
-
-    private_class_method def self.remove_managed_file(path:, content:, force:, description:)
-      return {action: :missing, path: path} unless File.exist?(path)
-
-      existing = File.read(path)
-      if existing != content && !force && !managed_src?(existing)
-        raise "Refusing to remove existing #{description} at #{path}. Re-run with --force."
-      end
-
-      FileUtils.rm_f(path)
-      {action: :removed, path: path}
-    end
-  end
-end

data/lib/space_src/state/lock.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-require "fileutils"
-
-module Space::Src
-  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/lib/space_src/state/store.rb

@@ -1,140 +0,0 @@
-# frozen_string_literal: true
-
-require "yaml"
-require "fileutils"
-require "time"
-require "dry/monads"
-
-module Space::Src
-  module State
-    # Machine-managed state at $XDG_STATE_HOME/space-src/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