space-architect 8.0.0 → 9.1.0

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

data/lib/space_src/config/store.rb

@@ -1,156 +0,0 @@
-# frozen_string_literal: true
-
-require "yaml"
-require "fileutils"
-require "dry/monads"
-require "space_src/config/model"
-require "space_src/config/contract"
-
-module Space::Src
-  module Config
-    # Load/validate/write-back the YAML config file.
-    #
-    # The store is the only place that touches the disk. It does not
-    # preserve unknown keys or YAML comments on write — that's a known
-    # limitation per the PRD §2 (YAML comment loss accepted) and is
-    # documented in the Slice 1 lane report. Managed fields round-trip
-    # byte-identically (gate G1).
-    class Store
-      extend Dry::Monads[:result]
-
-      DEFAULT_BASE_DIR = Space::Src::Paths::DEFAULT_BASE_DIR
-      DEFAULT_REFRESH_INTERVAL = 6 * 3600
-      DEFAULT_CONCURRENCY = 8
-
-      def self.load(path)
-        raw = read_yaml(path)
-        hash = symbolize(raw)
-        # CF1: normalize `refresh_interval` from a human-duration
-        # string ("6h", "90m", "45s", "30d") or bare integer string
-        # ("21600") into integer seconds BEFORE the contract runs.
-        # The contract stays integer-typed (:integer, gt?: 0); this
-        # is a load-layer normalization that lets a hand-edited
-        # config.yaml round-trip without rejecting "6h" as a
-        # non-integer. See lib/space_src/config/duration.rb.
-        if hash.key?(:refresh_interval)
-          result = Duration.parse(hash[:refresh_interval])
-          return result if result.failure?
-          hash[:refresh_interval] = result.success
-        end
-        with_defaults(hash) do |filled|
-          result = Contract.new.call(filled)
-          if result.success?
-            Success(Config.new(result.success))
-          else
-            Failure(result.failure)
-          end
-        end
-      rescue Errno::ENOENT
-        # Missing file is treated as an empty config (load defaults).
-        # The store does not create the file on read — that is the
-        # writer's job (write() is idempotent and always validates first).
-        Success(Config.new(defaults))
-      end
-
-      def self.write(path, config)
-        # Always re-validate the struct's contents before writing. This
-        # guards against a caller constructing a Config with a
-        # constraint-violating value via Struct.new (which does not run
-        # the same checks as the contract).
-        hash = config.to_h
-        result = Contract.new.call(hash)
-        return result if result.failure?
-
-        FileUtils.mkdir_p(File.dirname(path))
-        File.write(path, emit(hash))
-        Success(config)
-      end
-
-      def self.update(path)
-        config = load(path).success
-        new_config = yield(config)
-        write(path, new_config)
-      end
-
-      # dry-struct update idiom: pass a hash of attributes to
-      # `Config#new` to get a new struct with the overrides applied
-      # (existing fields are kept).
-      def self.with(config, **changes)
-        config.new(**changes)
-      end
-
-      # Hash → human-clean YAML string. String keys, defaults omitted.
-      # Stable key order: base_dir, refresh_interval, concurrency, repos, orgs.
-      # repos/orgs omitted when empty.
-      def self.emit(hash)
-        ordered = {}
-        ordered["base_dir"] = hash[:base_dir] if hash.key?(:base_dir)
-        ordered["refresh_interval"] = hash[:refresh_interval] if hash.key?(:refresh_interval)
-        ordered["concurrency"] = hash[:concurrency] if hash.key?(:concurrency)
-
-        repos = hash[:repos]
-        ordered["repos"] = repos.map { |r| compact_repo(r) } if repos && !repos.empty?
-
-        orgs = hash[:orgs]
-        ordered["orgs"] = orgs.map { |o| compact_org(o) } if orgs && !orgs.empty?
-
-        YAML.dump(ordered, line_width: -1)
-      end
-
-      def self.compact_repo(r)
-        h = {}
-        h["host"] = r[:host] if r[:host] && r[:host] != DEFAULT_HOST
-        h["owner"] = r[:owner]
-        h["name"] = r[:name]
-        h
-      end
-
-      def self.compact_org(o)
-        h = {}
-        h["host"] = o[:host] if o[:host] && o[:host] != DEFAULT_HOST
-        h["name"] = o[:name]
-        h["include_archived"] = true if o[:include_archived]
-        h["include_forks"] = true if o[:include_forks]
-        ignored = o[:ignored_repos]
-        h["ignored_repos"] = ignored if ignored && !ignored.empty?
-        h
-      end
-
-      def self.read_yaml(path)
-        return {} unless File.exist?(path)
-        # Symbol permitted because some YAML files use :symbol keys; the
-        # store's symbolize() then re-keys consistently anyway. We still
-        # disallow arbitrary classes.
-        YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: false) || {}
-      end
-
-      def self.symbolize(value)
-        case value
-        when Hash
-          value.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = symbolize(v) }
-        when Array
-          value.map { |v| symbolize(v) }
-        else
-          value
-        end
-      end
-
-      # Fill in missing top-level defaults before validation, so an empty
-      # YAML produces a fully-populated Config.
-      def self.with_defaults(hash)
-        filled = defaults.merge(hash)
-        yield(filled)
-      end
-
-      def self.defaults
-        {
-          base_dir: DEFAULT_BASE_DIR,
-          refresh_interval: DEFAULT_REFRESH_INTERVAL,
-          concurrency: DEFAULT_CONCURRENCY,
-          repos: [],
-          orgs: []
-        }
-      end
-    end
-  end
-end

data/lib/space_src/forge/client.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-require "dry/monads"
-require "space_src/config/model"
-
-module Space::Src
-  module Forge
-    # Abstract forge interface. The GitHub implementation lists the
-    # repos belonging to an OrgRef. The interface is intentionally
-    # narrow: a forge is a source of (host, owner, name) triples. The
-    # sync engine expands an OrgRef into RepoRefs at sync time; it
-    # never asks the forge about a specific repo.
-    class Client
-      extend Dry::Monads[:result]
-
-      # Returns Success(:authenticated) or Failure({reason:}).
-      # Called ONCE by the engine before fanning out org listings.
-      def check_authenticated
-        raise NotImplementedError
-      end
-
-      # Returns Success([RepoRef, ...]) or Failure. Honors the
-      # include_archived / include_forks flags on the OrgRef.
-      # Does NOT perform authentication — the engine calls
-      # check_authenticated first.
-      def list_org(org_ref)
-        raise NotImplementedError
-      end
-    end
-  end
-end

data/lib/space_src/forge/github.rb

@@ -1,98 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "space_src/forge/client"
-require "space_src/shell"
-require "space_src/config/model"
-
-module Space::Src
-  module Forge
-    # `gh repo list <org> --json …` implementation of Forge::Client.
-    #
-    # Per AGENTS.md gotcha, `gh` can silently fall back to
-    # unauthenticated (60 req/hr). We probe `gh auth status` once
-    # (via the engine calling check_authenticated before listing)
-    # and surface a clear Failure rather than risking the rate-limit wall.
-    class GitHub < Client
-      # Default page size for `gh repo list`. Matches gh's own --limit
-      # cap; orgs with >1000 repos are out of scope for Slice 1.
-      LIST_LIMIT = 1000
-
-      def initialize(shell: Shell)
-        @shell = shell
-      end
-
-      # Probe `gh auth status`. On stderr the unauthenticated case is
-      # obvious: "You are not logged into any GitHub hosts." We treat
-      # that exact phrase as Failure; otherwise Success.
-      #
-      # Public so the engine can call it once before fanning out org
-      # listings. `list_org` no longer authenticates per-call.
-      def check_authenticated
-        # `gh auth status` writes a human-friendly summary to stdout
-        # and exits 0 when authenticated, 1 when not. We also fail
-        # when the binary is missing (status 127 from the shell).
-        result = @shell.run("gh", "auth", "status")
-        return result if result.failure?
-
-        if result.success.include?("not logged into any GitHub hosts")
-          Dry::Monads::Failure({reason: "gh not authenticated; run `gh auth login` first"})
-        else
-          Dry::Monads::Success(:authenticated)
-        end
-      end
-
-      def list_org(org_ref)
-        return Dry::Monads::Failure({org: org_ref.name, reason: "missing org name"}) if org_ref.name.nil? || org_ref.name.empty?
-
-        argv = build_argv(org_ref)
-        result = @shell.run(*argv)
-        return result if result.failure?
-
-        parsed = parse_repos(result.success, org_ref)
-        Dry::Monads::Success(parsed)
-      rescue JSON::ParserError => e
-        Dry::Monads::Failure({org: org_ref.name, reason: "invalid JSON from gh", error: e.message})
-      end
-
-      def build_argv(org_ref)
-        # G11 fix (Slice 2): `--no-source` is NOT a valid `gh repo list`
-        # flag (`gh repo list --help` lists `--archived`, `--no-archived`,
-        # `--fork`, `--source`, `--json`, `--limit`, `--topic`,
-        # `--language`, `--visibility`, `--jq`, `--template` — no
-        # `--no-source`). Fork exclusion is handled authoritatively in
-        # `parse_repos` below (the `include_forks` filter), so we no
-        # longer emit an advisory CLI flag for it. The existing G6
-        # behavioral tests for `include_forks=false` still pass.
-        argv = ["gh", "repo", "list", org_ref.name, "--json", "nameWithOwner,defaultBranchRef,isArchived,isFork", "--limit", LIST_LIMIT.to_s]
-        argv << "--no-archived" unless org_ref.include_archived
-        argv
-      end
-
-      private
-
-      # Parses gh's JSON output into RepoRef structs, honoring
-      # include_archived / include_forks (the CLI flags are advisory;
-      # the filter is authoritative so a future gh flag rename
-      # doesn't break us silently).
-      def parse_repos(json_text, org_ref)
-        rows = JSON.parse(json_text)
-        ignored = org_ref.ignored_repos
-        rows.map do |row|
-          next if !org_ref.include_archived && row["isArchived"]
-          next if !org_ref.include_forks && row["isFork"]
-
-          owner, name = row.fetch("nameWithOwner").split("/", 2)
-          next if ignored.include?(name) || ignored.include?(row.fetch("nameWithOwner"))
-          # default_branch is state, not config — the SCM layer resolves
-          # it on the local clone (see SCM::Git#default_branch).
-          Config::RepoRef.new(
-            host: org_ref.host,
-            owner: owner,
-            name: name
-          )
-        end.compact
-      end
-    end
-  end
-end