space-architect 8.0.0 → 9.0.0

data/lib/space_src/cli/sync.rb

@@ -1,161 +0,0 @@
-# frozen_string_literal: true
-
-require "dry/monads"
-require "space_src/cli/repo"  # for Repo::Helpers.parse_ref
-require "space_src/cli/options"
-require "space_src/ui/mode"
-require "space_src/ui/plain_reporter"
-require "space_src/ui/json_reporter"
-require "space_src/ui/interactive_reporter"
-
-module Space::Src
-  module CLI
-    # `sync` command: invoke Sync::Engine over the full config, or
-    # scope to a single repo with --repo.
-    #
-    # Scoping is implemented at the CLI layer (per gate G4): the
-    # CLI builds a filtered Config (Config::Store.with(config,
-    # repos: [match], orgs: [])) and passes it to the unchanged
-    # engine. Sync::Engine#call is (config:, paths:) — there is no
-    # scoping parameter on the engine, and the spec forbids editing
-    # sync/engine.rb in this slice.
-    module Sync
-      class Run < Dry::CLI::Command
-        include GlobalOptions
-
-        desc "Run one sync pass (use --repo to scope to a single tracked repo)"
-        option :repo, desc: "Scope to a single tracked repo (host/owner/name)"
-
-        def call(repo: nil, plain: nil, json: nil, no_color: nil, quiet: nil, **)
-          paths = CLI.make_paths
-          paths.ensure!
-          config = Config::Store.load(paths.config_file).success
-
-          # Log rotation pre-step (slice-4 gate G5). launchd owns
-          # the stdout/stderr redirect via StandardOutPath /
-          # StandardErrorPath; the sync process rotates those
-          # files at the start of each run so the previous run's
-          # log doesn't grow unbounded. The rotator renames the
-          # file to a timestamped archive (preserving bytes); the
-          # current process's inherited fd still points to the
-          # renamed file, so writes during this run succeed.
-          # launchd opens a fresh file at the original path on
-          # the next spawn. No-op when the log is missing or
-          # under-threshold (sync tests in G4 stay green).
-          rotate_plist_logs(paths)
-
-          # Resolved BEFORE the scoping block: the "scoping sync to:"
-          # notice below is prose, and must be suppressed in JSON mode
-          # for the same reason the summary line is. Resolution depends
-          # only on flags/env/out, so it is safe this early.
-          mode = UI::Mode.resolve(
-            flags: {plain: plain, json: json, no_color: no_color, quiet: quiet},
-            env: CLI.env,
-            out: out
-          )
-          # Every line of --json output must parse as one JSON object.
-          human = mode.format != :json
-
-          if repo
-            target = scope_target(repo)
-            return fail_with(self, "invalid repo reference: #{repo.inspect} (expected host/owner/name)") if target.failure?
-
-            match = target.success
-            found = config.repos.find { |r| Repo::Helpers.same_repo?(r, match) }
-            if found.nil?
-              return fail_with(self, "no such tracked repo: #{Repo::Helpers.format_ref(match)}")
-            end
-            # Filtered config: only the one matched repo, no orgs
-            # (org expansion would discover other repos — that's
-            # exactly the G4 "other repo gets no state row" test
-            # path, so we explicitly empty orgs here).
-            config = Config::Store.with(config, repos: [found], orgs: [])
-            out.puts "scoping sync to: #{Repo::Helpers.format_ref(found)}" if human
-          end
-
-          reporter = if mode.format == :json
-            UI::JsonReporter.new(out)
-          elsif mode.animate
-            UI::InteractiveReporter.new(out, mode: mode)
-          else
-            UI::PlainReporter.new(out, mode: mode)
-          end
-
-          # prune only on a full sweep. With --repo the config above was
-          # narrowed to one repo, so pruning would delete the state rows
-          # for every OTHER tracked repo.
-          result = Space::Src::Sync::Engine.new(reporter: reporter)
-            .call(config: config, paths: paths, prune: repo.nil?)
-          if result.failure?
-            return fail_with(self, "sync failed: #{format_failure(result.failure)}")
-          end
-
-          report = result.success
-          # JsonReporter already emits a run_finished event carrying the
-          # summary, so suppressing the prose line loses nothing.
-          out.puts "synced #{report.processed} repo(s)" if human
-          CLI.record_outcome(Outcome.new(exit_code: 0))
-        end
-
-        private
-
-        def scope_target(repo)
-          Repo::Helpers.parse_ref(repo)
-        end
-
-        def format_failure(f) = f.is_a?(Hash) ? f.inspect : f.to_s
-
-        def fail_with(cmd, msg)
-          cmd.send(:err).puts msg
-          Space::Src::CLI.record_outcome(Outcome.new(exit_code: 1, message: msg))
-        end
-
-        # Default log-rotation threshold: 10 MiB. Tunable via the
-        # env var `SPACE_SRC_LOG_MAX_BYTES` (introspection /
-        # ops escape hatch). The LogRotator itself is unit-tested
-        # with an injected threshold (gate G5).
-        DEFAULT_LOG_MAX_BYTES = 10 * 1024 * 1024
-
-        def rotate_plist_logs(paths)
-          threshold = log_max_bytes
-          label = Launchd::Agent::DEFAULT_LABEL
-          [File.join(paths.log_dir, "#{label}.out.log"),
-            File.join(paths.log_dir, "#{label}.err.log")].each do |p|
-            Space::Src::LogRotator.call(p, threshold_bytes: threshold)
-          end
-        end
-
-        # CF6 (Slice 5): defensively parse the
-        # `SPACE_SRC_LOG_MAX_BYTES` env var so a malformed
-        # operator value (e.g. `"10MB"`) falls back to the
-        # 10 MiB default instead of raising `ArgumentError`
-        # and crashing the entire `sync` run before any repo
-        # work.
-        #
-        # Accepted: any positive integer in base 10
-        # (e.g. `"1048576"`, `"  524288  "`). Falls back to
-        # `DEFAULT_LOG_MAX_BYTES` (and emits a single
-        # `Kernel#warn` to stderr) for: unset, empty,
-        # whitespace, non-numeric (`"10MB"`, `"abc"`), zero,
-        # and negative inputs. Never raises.
-        #
-        # The optional `env_value` arg exists so the unit
-        # tests can pass arbitrary values without mutating
-        # the real `ENV`; production callers invoke with
-        # no args and the method reads `ENV` itself.
-        def log_max_bytes(env_value = ENV["SPACE_SRC_LOG_MAX_BYTES"])
-          return DEFAULT_LOG_MAX_BYTES if env_value.nil? || env_value.strip.empty?
-
-          parsed = Integer(env_value, 10, exception: false)
-          return parsed if parsed.is_a?(Integer) && parsed.positive?
-
-          warn "src: SPACE_SRC_LOG_MAX_BYTES=#{env_value.inspect} is invalid; " \
-            "falling back to #{DEFAULT_LOG_MAX_BYTES} bytes"
-          DEFAULT_LOG_MAX_BYTES
-        end
-      end
-    end
-  end
-end
-
-Space::Src::CLI::Registry.register "sync", Space::Src::CLI::Sync::Run

data/lib/space_src/cli.rb

@@ -1,159 +0,0 @@
-# frozen_string_literal: true
-
-require "dry/cli"
-require "space_src/migration"
-
-module Space::Src
-  # CLI surface — thin translation layer between argv and the
-  # existing Config::Store / State::Store / Sync::Engine boundaries.
-  #
-  # The CLI never mutates a git repo directly; repo mutation happens
-  # inside the engine, which already upholds the no-data-loss
-  # invariant (PRD §1). The CLI's job is:
-  #   1. parse argv (via Dry::CLI's nested `register`)
-  #   2. load/mutate validated config (Config::Store) OR delegate to
-  #      the engine / state store
-  #   3. translate Result to: out/err message + exit code
-  #
-  # Exit-code seam: each command records an `Outcome(exit_code:,
-  # message:)` (the thread-local stash) and writes the user-facing
-  # message to `out`/`err` via the injected IOs. The `exe/src`
-  # entrypoint reads the recorded Outcome and calls Kernel.exit with
-  # the code — see CLI.run below. Tests can inspect last_outcome
-  # in-process (no subprocess needed for unit tests); a subprocess
-  # Open3.capture3 covers the G3 "real exit" proof.
-  module CLI
-    # The Outcome value object. `exit_code` is 0 for success and 1
-    # for Failure-derived failures. `message` is the user-facing
-    # explanation already written to err (kept here so the
-    # entrypoint could log/record it in a future slice).
-    Outcome = Data.define(:exit_code, :message) do
-      def initialize(exit_code:, message: nil)
-        super
-      end
-    end
-
-    # Thread-local env hash. Defaults to ENV. Tests inject a temp
-    # HOME / XDG_* hash via Thread.current[:space_src_cli_env] =
-    # env_hash. The CLI's `make_paths` reads this to resolve the
-    # config/state file locations under the test's temp home.
-    def self.env
-      Thread.current[:space_src_cli_env] || ENV
-    end
-
-    # Thread-local Outcome stash. The most recent command's Outcome
-    # is read by CLI.run to set the process exit code.
-    def self.record_outcome(outcome)
-      Thread.current[:space_src_cli_outcome] = outcome
-    end
-
-    def self.last_outcome
-      Thread.current[:space_src_cli_outcome]
-    end
-
-    # Program-name-level invocations that must succeed (exit 0) with
-    # output on stdout. Dry::CLI has no root command registered, so it
-    # would otherwise route these through its "command not found" path
-    # (Usage → stderr → exit 1). We intercept ONLY the exact top-level
-    # forms here; a *leaf* help like `sync --help` (argv ["sync",
-    # "--help"]) and a *group* like `repo` / `repo --help` are NOT
-    # matched, so Dry::CLI keeps handling them as before (leaf help →
-    # stdout/exit 0; group → usage/stderr/exit 1, accepted per G7).
-    TOP_LEVEL_HELP = [[], ["--help"], ["-h"], ["help"]].freeze
-    VERSION_REQUEST = [["version"], ["--version"]].freeze
-
-    # True when argv is a single token that is not a registered top-level
-    # command or group, and not already handled by the help/version intercepts.
-    # Both CLI.run and dispatch_src delegate to this shared predicate so the
-    # routing logic is defined exactly once.
-    def self.bare_query?(argv)
-      return false if TOP_LEVEL_HELP.include?(argv)
-      return false if VERSION_REQUEST.include?(argv)
-      # paths:exempt - Registry.get([]).children is a dry-cli command-tree node, not a filesystem path
-      argv.length == 1 && !Registry.get([]).children.key?(argv[0])
-    end
-
-    # Entrypoint. Called by exe/src. Intercepts the top-level
-    # help/version forms (stdout, exit 0), otherwise hands argv to
-    # Dry::CLI for command dispatch and translates the last Outcome to
-    # a process exit code. A `Interrupt` raised from inside command
-    # dispatch (most commonly: a SIGINT during a long-running
-    # `Shell.run`, e.g. at a `git` username prompt or mid-clone) is
-    # caught here and mapped to a clean exit code 130 (128 + SIGINT)
-    # with a single human line on stderr — the G2 ^C-hygiene fix
-    # (Slice 6). The reader-thread `IOError` noise that Open3 emits
-    # in the same scenario is suppressed at the `Shell.run` seam
-    # (see `lib/space_src/shell.rb`).
-    def self.run(argv, stdout, stderr)
-      return print_usage(stdout) if TOP_LEVEL_HELP.include?(argv)
-      return print_version(stdout) if VERSION_REQUEST.include?(argv)
-
-      Migration.run(paths: make_paths, err: stderr)
-
-      if bare_query?(argv)
-        paths = make_paths
-        config = Config::Store.load(paths.config_file).success
-        exit_code = Nav.dispatch(argv[0], stdout, stderr, config.base_dir)
-        Kernel.exit(exit_code)
-      end
-
-      begin
-        Dry::CLI.new(Registry).call(arguments: argv, out: stdout, err: stderr)
-        outcome = last_outcome
-        Kernel.exit(outcome&.exit_code || 0)
-      rescue Interrupt
-        # Map a user ^C to a clean exit-130 with a single human line.
-        # `Kernel.exit` raises `SystemExit` (callers/tests can rescue
-        # it to inspect the status). The `at_exit` handlers run,
-        # stdio is flushed, the process exits with code 130. We do
-        # NOT blanket-rescue `StandardError` and we do NOT make
-        # non-interrupt failures exit 0 (the outcome-translation path
-        # above is unchanged for the happy / non-Interrupt failure
-        # paths).
-        stderr.puts "interrupted"
-        Kernel.exit(130)
-      end
-    end
-
-    # Render the top-level command-group listing (reusing Dry::CLI's
-    # own Usage formatter so it stays in sync with the registry) to
-    # stdout and exit 0.
-    def self.print_usage(stdout)
-      stdout.puts Dry::CLI::Usage.call(Registry.get([]))
-      Kernel.exit(0)
-    end
-
-    # Print the gem version to stdout and exit 0.
-    def self.print_version(stdout)
-      stdout.puts Space::Src::VERSION
-      Kernel.exit(0)
-    end
-
-    # Internal: build a Paths instance scoped to the active env
-    # (Thread.current[:space_src_cli_env] || ENV). Every command
-    # uses this so tests can inject a temp home without mutating
-    # the real ENV.
-    def self.make_paths
-      Paths.new(environment: env)
-    end
-
-    # The Dry::CLI::Registry-extended module. The subcommand files
-    # (cli/repo.rb, cli/org.rb, …) call `register "x" do |p| ... end`
-    # on this module at load time.
-    module Registry
-      extend Dry::CLI::Registry
-    end
-  end
-end
-
-# Subcommand files — each defines its command classes and
-# registers them under their group prefix.
-require "space_src/cli/repo"
-require "space_src/cli/org"
-require "space_src/cli/sync"
-require "space_src/cli/status"
-require "space_src/cli/config"
-require "space_src/cli/daemon"
-require "space_src/cli/clone"
-require "space_src/cli/shell"
-require "space_src/nav"

data/lib/space_src/cloner.rb

@@ -1,77 +0,0 @@
-# frozen_string_literal: true
-
-require "async"
-require "dry/monads"
-require "space_src/shell"
-
-module Space::Src
-  # Resolution + COW-copy boundary for `clone`. Returns Result; no
-  # side effects on Failure. Injected shell seam defaults to ShellRunner
-  # (wraps Shell.run in Sync{} so the Fiber-scheduler requirement is met
-  # from a plain synchronous CLI command — same pattern as Launchd::Agent).
-  class Cloner
-    include Dry::Monads[:result]
-
-    class ShellRunner
-      def run(*argv)
-        Sync { Space::Src::Shell.run(*argv) }
-      end
-    end
-
-    def initialize(base_dir:, shell: ShellRunner.new)
-      @base_dir = File.expand_path(base_dir)
-      @shell = shell
-    end
-
-    # Resolve `name` against `base_dir` and copy to `into/<leaf>`.
-    # Returns Success(dest_path) or Failure(message).
-    def call(name:, into: ".")
-      result = resolve(name)
-      return result if result.failure?
-      copy(result.success, into)
-    end
-
-    private
-
-    def resolve(name)
-      parts = name.split("/")
-      case parts.length
-      when 1
-        # paths:exempt - layout intent (checkout resolution by depth); space_src is deliberately independent of space_core and must not require it
-        candidates = Dir.glob(File.join(@base_dir, "*", "*", name))
-        case candidates.length
-        when 0 then Failure("#{name.inspect} not found under base_dir #{@base_dir}")
-        when 1 then Success(candidates.first)
-        else ambiguous(name, candidates, "owner/name or host/owner/name")
-        end
-      when 2
-        owner, repo_name = parts
-        # paths:exempt - layout intent (checkout resolution by depth); space_src is deliberately independent of space_core and must not require it
-        candidates = Dir.glob(File.join(@base_dir, "*", owner, repo_name))
-        case candidates.length
-        when 0 then Failure("#{name.inspect} not found under base_dir #{@base_dir}")
-        when 1 then Success(candidates.first)
-        else ambiguous(name, candidates, "host/owner/name")
-        end
-      when 3
-        path = File.join(@base_dir, *parts)
-        File.directory?(path) ? Success(path) : Failure("#{name.inspect} not found under base_dir #{@base_dir}")
-      else
-        Failure("invalid repo reference: #{name.inspect}")
-      end
-    end
-
-    def ambiguous(name, candidates, hint)
-      list = candidates.map { |c| "  #{c.delete_prefix("#{@base_dir}/")}" }.join("\n")
-      Failure("ambiguous name #{name.inspect}; qualify with #{hint}:\n#{list}")
-    end
-
-    def copy(src, into)
-      leaf = File.basename(src)
-      dest = File.join(File.expand_path(into), leaf)
-      return Failure("destination already exists: #{dest}") if File.exist?(dest)
-      result = @shell.run("cp", "-Rc", src, dest)
-      result.success? ? Success(dest) : result
-    end
-  end
-end

data/lib/space_src/config/contract.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-require "dry/validation"
-require "dry/validation/extensions/monads"
-require "dry/monads"
-
-module Space::Src
-  module Config
-    # Validates the raw YAML hash before it is built into a Config struct.
-    # Returns a Dry::Monads::Result (via the :monads extension):
-    #   Success(validated_hash)  — keys are coerced + bad keys dropped
-    #   Failure(errors_to_h)     — field-level messages keyed by path
-    #
-    # Per gate G2, each rejection case (missing required field, bad
-    # refresh_interval, non-integer concurrency, malformed repo entry,
-    # malformed org entry) must produce a Failure with a field-level
-    # message — verified by Config::ContractTest.
-    class Contract < Dry::Validation::Contract
-      include Dry::Monads[:result]
-
-      schema do
-        optional(:base_dir).filled(:string)
-        optional(:refresh_interval).filled(:integer, gt?: 0)
-        optional(:concurrency).filled(:integer, gt?: 0)
-
-        optional(:repos).array(:hash) do
-          optional(:host).filled(:string)
-          required(:owner).filled(:string)
-          required(:name).filled(:string)
-        end
-
-        optional(:orgs).array(:hash) do
-          optional(:host).filled(:string)
-          required(:name).filled(:string)
-          optional(:include_archived).filled(:bool)
-          optional(:include_forks).filled(:bool)
-          optional(:ignored_repos).array(:string)
-        end
-      end
-
-      # Override call to return a Dry::Monads::Result. Dry-validation's
-      # monads extension gives us Result#to_monad; we map to our own
-      # namespace so callers see a single Result type at every boundary.
-      def call(input)
-        result = super
-        if result.success?
-          Success(result.to_h)
-        else
-          Failure(result.errors.to_h)
-        end
-      end
-    end
-  end
-end

data/lib/space_src/config/duration.rb

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-require "dry/monads"
-
-module Space::Src
-  module Config
-    # CF1: parse a human-duration string into integer seconds.
-    #
-    # The contract and model keep `refresh_interval` as an integer
-    # (types::Integer.constrained(gt: 0)); this module is the load-
-    # layer normalization that lets a hand-edited config.yaml contain
-    # "6h" / "90m" / "45s" / "30d" and have it round-trip through
-    # Config::Store.load as 21600 / 5400 / 45 / 2592000 — so a user
-    # who writes `refresh_interval: 6h` in their config gets the
-    # same effect as `refresh_interval: 21600` without ever touching
-    # the contract.
-    #
-    # The write-back path emits integer seconds (the human form is
-    # not preserved on rewrite — consistent with Slice 1's documented
-    # YAML comment-loss limitation, see test_write_emits_only_managed_fields).
-    #
-    # Usage:
-    #   Duration.parse("6h")   # => Success(21600)
-    #   Duration.parse(21600)  # => Success(21600)
-    #   Duration.parse("-3h")  # => Failure("invalid duration: \"-3h\"")
-    #   Duration.parse("6x")   # => Failure("invalid duration: \"6x\"")
-    module Duration
-      extend Dry::Monads[:result]
-
-      # Unit suffixes recognized (PRD §3.1 documents "6h" / "90m" /
-      # integer seconds; we also accept "s" and "d" for completeness
-      # — they're natural extensions and cost zero code).
-      UNIT_SECONDS = {
-        nil => 1,        # bare integer string ("21600") or Integer input
-        "s" => 1,
-        "m" => 60,
-        "h" => 3600,
-        "d" => 86_400
-      }.freeze
-
-      # Strictly positive integer (no sign, no decimal, no leading
-      # zeros that change the value's magnitude). Bare integer
-      # strings ("21600") are accepted by making the unit suffix
-      # optional in the pattern.
-      PATTERN = /\A(\d+)([smhd])?\z/
-
-      def self.parse(value)
-        case value
-        when Integer
-          return failure_for(value) if value <= 0
-          Success(value)
-        when String
-          parse_string(value)
-        else
-          failure_for(value)
-        end
-      end
-
-      def self.parse_string(str)
-        s = str.strip
-        return failure_for(str) if s.empty?
-        m = PATTERN.match(s)
-        return failure_for(str) unless m
-        n = m[1].to_i
-        unit = m[2]
-        # The pattern guarantees n is a positive integer ("\d+" matches
-        # 1+ digits, never "0" with no other digits… well, "0" would
-        # match with n=0). Reject zero explicitly to keep the
-        # contract's "gt?: 0" guarantee.
-        return failure_for(str) if n <= 0
-        Success(n * UNIT_SECONDS.fetch(unit))
-      end
-
-      def self.failure_for(value)
-        Failure("invalid duration: #{value.inspect} (expected positive integer or \"<n>[s|m|h|d]\" e.g. \"6h\", \"90m\", \"21600\")")
-      end
-    end
-  end
-end

data/lib/space_src/config/model.rb

@@ -1,49 +0,0 @@
-# frozen_string_literal: true
-
-require "dry/struct"
-require "dry/types"
-
-module Space::Src
-  module Config
-    Types = Dry.Types()
-
-    # Default host for repo/org entries. Per PRD §3.1, host is omitted in
-    # the YAML when the user means github.com.
-    DEFAULT_HOST = "github.com"
-    # Per PRD §3.1, default refresh_interval is 6h. Stored as integer seconds.
-    DEFAULT_REFRESH_INTERVAL = 6 * 3600
-    DEFAULT_CONCURRENCY = 8
-
-    class RepoRef < Dry::Struct
-      transform_keys(&:to_sym)
-
-      attribute :host, Types::String.default(DEFAULT_HOST)
-      attribute :owner, Types::String
-      attribute :name, Types::String
-    end
-
-    class OrgRef < Dry::Struct
-      transform_keys(&:to_sym)
-
-      attribute :host, Types::String.default(DEFAULT_HOST)
-      attribute :name, Types::String
-      attribute :include_archived, Types::Bool.default(false)
-      attribute :include_forks, Types::Bool.default(false)
-      attribute :ignored_repos, Types::Array.of(Types::String).default([].freeze)
-    end
-
-    # Top-level config. The on-disk schema per PRD §3.1:
-    #   base_dir, refresh_interval, concurrency, repos, orgs.
-    # `base_dir` has no struct-level default — the value is set from
-    # Paths::DEFAULT_BASE_DIR at store-load time (see Config::Store).
-    class Config < Dry::Struct
-      transform_keys(&:to_sym)
-
-      attribute :base_dir, Types::String
-      attribute :refresh_interval, Types::Integer.constrained(gt: 0)
-      attribute :concurrency, Types::Integer.constrained(gt: 0)
-      attribute :repos, Types::Array.of(RepoRef).default([].freeze)
-      attribute :orgs, Types::Array.of(OrgRef).default([].freeze)
-    end
-  end
-end