space-cadet 9.0.0

data/lib/space_core/cli/help.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require "pastel"
+require_relative "loop_status"
+
+module Space::Core::CLI
+  # Colourful replacement for dry-cli's plain `Usage` listing — the "global
+  # help" shown by `space`, `architect`, and every bare namespace (`space repo`,
+  # `worktree`, ...). Per-command help still flows through dry-cli's Banner,
+  # whose content we like; only the listing is reskinned.
+  #
+  # We reopen Dry::CLI::Usage.call (below) to delegate here, so BOTH the
+  # intercepted top-level help and dry-cli's own bare-namespace path get the
+  # same treatment from one place. Colour follows CLI.help_pastel, set once per
+  # invocation from the output stream's tty-ness and --color, so piped and test
+  # output stay plain. The `src` binary never loads space_core, so its own plain
+  # Usage is untouched.
+  module Help
+    # One tagline per binary — the root header is served for both `space` and
+    # `architect` from here, so we pick by $PROGRAM_NAME. The default covers the
+    # test runner and any other invocation where the binary can't be identified.
+    TAGLINES = {
+      "space"     => "date-prefixed workspaces; repos provisioned on fibers at copy-on-write speed",
+      "architect" => "the Architect Loop: structured judgment plus a fleet of headless AI builders"
+    }.freeze
+    DEFAULT_TAGLINE = TAGLINES.fetch("space")
+
+    module_function
+
+    # Header for the trailing group of children that declare no phase. Left nil
+    # for the `space` binary (whose commands are all phase-less → one ungrouped
+    # listing); the `architect` binary sets it so its namespaces list under a
+    # "Groups" header. Keeps phase vocabulary out of this generic renderer.
+    def self.trailing_group_label = @trailing_group_label
+
+    def self.trailing_group_label=(label)
+      @trailing_group_label = label
+    end
+
+    def call(result, pastel: CLI.help_pastel)
+      groups = grouped_listing(result)
+      width  = groups.flat_map { |_h, rows| rows.map { |label, _| label.length } }.max || 0
+
+      body = groups.flat_map do |group_header, rows|
+        lines = rows.map do |label, description|
+          painted = pastel.cyan(label.ljust(width))
+          description ? "  #{painted}   #{pastel.dim("# #{description}")}" : "  #{painted}"
+        end
+        group_header ? ["", pastel.bold(group_header), *lines] : lines
+      end
+
+      [header(result, pastel), pastel.bold("Commands:"), *body,
+       footer(result, pastel), loop_status_block(result, pastel)].compact.join("\n")
+    end
+
+    # The richer header only makes sense at the true root (`space` / `architect`),
+    # not on every sub-namespace listing.
+    def header(result, pastel)
+      return unless result.names.empty?
+
+      "#{pastel.bold.cyan("space-cadet")} #{pastel.dim(Space::Core::VERSION)} " \
+        "#{pastel.dim("— #{tagline}")}\n"
+    end
+
+    # The tagline for the binary in hand: `space` and `architect` each get their
+    # own, keyed off $PROGRAM_NAME (the same signal program_prefix reads).
+    def tagline
+      TAGLINES.fetch(File.basename($PROGRAM_NAME), DEFAULT_TAGLINE)
+    end
+
+    def footer(result, pastel)
+      "\n#{pastel.dim("Run `#{program_prefix(result)} <command> --help` for details on a command.")}"
+    end
+
+    # "space" at the root, "space repo" inside a namespace. The `space`/`architect`
+    # binaries inject their name into ARGV, so $PROGRAM_NAME and the leading
+    # namespace segment can collide ("space space ..."); drop the duplicate.
+    def program_prefix(result)
+      prog  = File.basename($PROGRAM_NAME)
+      names = result.names.dup
+      names.shift if names.first == prog
+      [prog, *names].join(" ")
+    end
+
+    # Group non-hidden children into an ordered list of [header_or_nil, rows].
+    # When no child declares a phase (e.g. the `space` binary), returns a single
+    # unlabelled group sorted by name — byte-identical to the pre-phase listing.
+    # Otherwise groups declared commands under their phase label (groups, and
+    # members within a group, ordered by the declared order), with undeclared
+    # children (namespaces) trailing in the default group.
+    def grouped_listing(result)
+      # paths:exempt - result.children is a dry-cli command-tree node, not a filesystem path
+      decorated = result.children.filter_map do |name, node|
+        [name, node, phase_of(node)] unless node.hidden
+      end
+
+      if decorated.all? { |_name, _node, phase| phase.nil? }
+        rows = decorated.sort_by { |name, _node, _phase| name }
+                        .map { |name, node, _phase| row(result, name, node) }
+        return [[nil, rows]]
+      end
+
+      phased, unphased = decorated.partition { |_name, _node, phase| phase }
+      groups = phased.group_by { |_name, _node, phase| phase.last }
+      listing = groups.sort_by { |_label, members| members.map { |_n, _node, phase| phase.first }.min }
+                      .map do |label, members|
+        rows = members.sort_by { |_n, _node, phase| phase.first }
+                      .map { |name, node, _phase| row(result, name, node) }
+        [label, rows]
+      end
+      listing << [trailing_group_label, unphased.map { |name, node, _phase| row(result, name, node) }] \
+        unless unphased.empty?
+      listing
+    end
+
+    def row(result, name, node)
+      [label(result, name, node), description(node)]
+    end
+
+    def phase_of(node)
+      node.command.respond_to?(:phase) ? node.command.phase : nil
+    end
+
+    # Opportunistic, TOTAL loop-status embed: only the architect binary's ROOT
+    # listing gets it. Resolves the current space best-effort and renders the
+    # shared block from that space's own space.yaml `project` data (no
+    # space_cadet dependency). ANY failure — no space, store failure,
+    # malformed yaml, no `project` block — omits the block; help always renders.
+    def loop_status_block(result, pastel)
+      return unless result.names.empty? && File.basename($PROGRAM_NAME) == "architect"
+
+      project = current_space_project
+      lines = project && LoopStatus.lines(project)
+      return if lines.nil? || lines.empty?
+
+      ["", pastel.bold("Loop:"), *lines.map { |l| "  #{pastel.dim(l)}" }].join("\n")
+    rescue StandardError
+      nil
+    end
+
+    def current_space_project
+      store = Space::Core::SpaceStore.new(config: Space::Core::Config.load, state: Space::Core::State.load)
+      store.current.value_or(nil)&.data&.[]("project")
+    rescue StandardError
+      nil
+    end
+
+    def label(result, name, node)
+      "#{program_prefix(result)} #{name}#{banner(node)}"
+    end
+
+    def banner(node)
+      # paths:exempt - node.children? is a dry-cli command-tree predicate, not a filesystem path
+      if node.command && node.leaf? && node.children?
+        " [ARGUMENT|SUBCOMMAND]"
+      elsif node.leaf?
+        arguments(node.command)
+      else
+        " [SUBCOMMAND]"
+      end
+    end
+
+    def arguments(command)
+      return "" unless command.respond_to?(:required_arguments)
+
+      names = command.required_arguments.map { |arg| arg.name.to_s.upcase }
+      names += command.optional_arguments.map { |arg| "[#{arg.name.to_s.upcase}]" }
+      names.empty? ? "" : " #{names.join(" ")}"
+    end
+
+    def description(node)
+      return unless node.leaf? && node.command.respond_to?(:description)
+
+      node.command.description
+    end
+  end
+end
+
+# Route dry-cli's plain namespace/root listing through our colourful renderer.
+# We prepend over Usage.call wholesale and depend only on the LookupResult/Node
+# API (children, command, leaf?/children?/hidden, names) rather than copying
+# Usage's internals — see notes/ruby-cli-gems-report.md.
+module Dry
+  class CLI
+    module Usage
+      module ColourPatch
+        def call(result)
+          Space::Core::CLI::Help.call(result)
+        end
+      end
+      singleton_class.prepend(ColourPatch)
+    end
+  end
+end

data/lib/space_core/cli/helpers.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+
+module Space::Core::CLI
+module Helpers
+  include Dry::Monads[:result]
+  def project_config
+    @project_config ||= Space::Core::Config.load
+  end
+
+  def state
+    @state ||= Space::Core::State.load
+  end
+
+  def store
+    @store ||= Space::Core::SpaceStore.new(config: project_config, state: state)
+  end
+
+  def terminal
+    @terminal
+  end
+
+  def setup_terminal(color: "auto", colors: nil)
+    @terminal = Space::Core::Terminal.new(
+      config: project_config,
+      stdout: out,
+      stderr: err,
+      color_mode: colors || color || "auto"
+    )
+  end
+
+  def display_date(space)
+    id_date = space.id.match(/\A(\d{4})(\d{2})(\d{2})/)
+    return "#{id_date[1]}-#{id_date[2]}-#{id_date[3]}" if id_date
+
+    space.data["created_at"].to_s[0, 10]
+  end
+
+  def handle_errors
+    yield
+  rescue Space::Core::Error => e
+    if terminal
+      terminal.error(e.message)
+    else
+      err.puts e.message
+    end
+    CLI.record_outcome(Outcome.new(exit_code: 1, message: e.message))
+  end
+
+  def render(result)
+    case result
+    when Dry::Monads::Result::Success
+      yield result.value! if block_given?
+    when Dry::Monads::Result::Failure
+      error = result.failure
+      message = error.respond_to?(:message) ? error.message : error.to_s
+      terminal ? terminal.error(message) : err.puts(message)
+      CLI.record_outcome(Outcome.new(exit_code: 1, message: message))
+    end
+  end
+end
+
+class RepoProgress
+  def initialize(total)
+    @total = total
+    @statuses = {}
+  end
+
+  def start(addition)
+    source = addition[:src_source]
+    @statuses[addition.fetch(:reference).full_name] = source&.directory? ? :copying : :cloning
+  end
+
+  def trust(addition)
+    @statuses[addition.fetch(:reference).full_name] = :trusting
+  end
+
+  def finish(addition)
+    @statuses[addition.fetch(:reference).full_name] = :done
+  end
+
+  def fail(addition)
+    @statuses[addition.fetch(:reference).full_name] = :failed
+  end
+
+  def message
+    done = @statuses.count { |_repo, status| status == :done }
+    failed = @statuses.count { |_repo, status| status == :failed }
+    copying = @statuses.select { |_repo, status| status == :copying }.keys
+    cloning = @statuses.select { |_repo, status| status == :cloning }.keys
+    trusting = @statuses.select { |_repo, status| status == :trusting }.keys
+
+    if @total == 1
+      copying_repo = copying.first
+      cloning_repo = cloning.first
+      trusting_repo = trusting.first
+      return "Copying #{copying_repo}" if copying_repo
+      return "Cloning #{cloning_repo}" if cloning_repo
+      return "Trusting #{trusting_repo}" if trusting_repo
+      return "Fetch failed" if failed.positive?
+
+      "Preparing repos"
+    else
+      active = []
+      active << "copying #{copying.join(', ')}" unless copying.empty?
+      active << "cloning #{cloning.join(', ')}" unless cloning.empty?
+      active << "trusting #{trusting.join(', ')}" unless trusting.empty?
+      suffix = active.empty? ? nil : ": #{active.join('; ')}"
+      failed_text = failed.positive? ? ", #{failed} failed" : ""
+      "Fetching repos #{done}/#{@total}#{failed_text}#{suffix}"
+    end
+  end
+end
+end

data/lib/space_core/cli/init.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Space::Core::CLI
+class Init < BaseCommand
+  desc "Create default XDG config and state files"
+  option :force, type: :boolean, default: false, desc: "Overwrite existing config and state files"
+
+  def call(force: false, **opts)
+    setup_terminal(**opts.slice(:color, :colors))
+    handle_errors do
+      if force
+        @project_config = Space::Core::Config.new
+        @state = Space::Core::State.new
+        project_config.save
+        state.save
+      else
+        project_config.ensure_exists!
+        state.ensure_exists!
+      end
+
+      FileUtils.mkdir_p(project_config.spaces_dir)
+      terminal.success "Config: #{terminal.path(project_config.path)}"
+      terminal.success "State: #{terminal.path(state.path)}"
+      terminal.success "Spaces: #{terminal.path(project_config.spaces_dir)}"
+      CLI.record_outcome(Outcome.new(exit_code: 0))
+    end
+  end
+end
+end

data/lib/space_core/cli/list.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Space::Core::CLI
+class List < BaseCommand
+  desc "List spaces"
+
+  def call(**opts)
+    setup_terminal(**opts.slice(:color, :colors))
+    handle_errors do
+      spaces = store.list
+      if spaces.empty?
+        terminal.say "No spaces found in #{terminal.path(project_config.spaces_dir)}"
+        next
+      end
+
+      rows = spaces.map do |space|
+        [space.status, display_date(space), space.title, terminal.path(space.path)]
+      end
+      terminal.say terminal.table(%w[Status Date Title Path], rows)
+      CLI.record_outcome(Outcome.new(exit_code: 0))
+    end
+  end
+end
+end

data/lib/space_core/cli/loop_status.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Space::Core::CLI
+  # Compact Architect-Loop status block, derived from a space's own `project`
+  # block in space.yaml — so this carries NO dependency on space_cadet. It
+  # is shared by the `architect --help` embed and the `space status` report.
+  # Returns plain lines (callers colourise) and never raises on malformed data.
+  module LoopStatus
+    module_function
+
+    # Lines for the compact block, or nil when there is no `project` block.
+    def lines(project)
+      return nil unless project.is_a?(Hash) && !project.empty?
+
+      rows = ["Project status:  #{project["status"] || "(none)"}"]
+      iter = current_iteration(project)
+      rows << "Iteration:       #{ordinal(iter)} #{iter["name"]} — #{state_of(iter)}" if iter
+      rows
+    end
+
+    def current_iteration(project)
+      name = project["current_iteration"]
+      return nil unless name
+
+      Array(project["iterations"]).find { |s| s["name"] == name }
+    end
+
+    def ordinal(iter)
+      iter["ordinal"] ? format("I%02d", iter["ordinal"]) : "I--"
+    end
+
+    # Derived loop state for the current iteration. Mirrors the precedence in
+    # `architect status`: a decided verdict wins, then an integrated lane
+    # (awaiting-verdict), then dispatched lanes, then a bare freeze, else spec.
+    def state_of(iter)
+      verdict = iter["verdict"]
+      return verdict if verdict && verdict != "pending"
+
+      lanes = Array(iter["lanes"])
+      return "awaiting-verdict" if lanes.any? { |l| l["integration_branch"] }
+      return "dispatched" if lanes.any?
+      return "frozen #{iter["freeze_sha"][0, 8]}" if iter["freeze_sha"]
+
+      "speccing"
+    end
+  end
+end

data/lib/space_core/cli/new.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Space::Core::CLI
+class New < BaseCommand
+  desc "Create a new project space"
+  argument :title, required: true, desc: "Space title"
+  option :repo, type: :array, aliases: ["-r"], desc: "Repo ref to clone (repeatable: pass -r once per repo)"
+  option :git, type: :boolean, default: true, desc: "Initialize the space as a Git repository (use --no-git to skip)"
+  example "\"My Space\" -r org/repo -r example-tools/alpha   # clone two repos into the space"
+
+  def call(title:, repo: [], git: true, **opts)
+    setup_terminal(**opts.slice(:color, :colors))
+    result = store.create(title, git: git).bind do |space|
+      terminal.success "Created #{space.id}"
+
+      repo_specs = Array(repo).compact
+      repo_specs.each { |spec| terminal.say "Queued #{spec}" }
+
+      next Success(space) if repo_specs.empty?
+
+      progress = RepoProgress.new(repo_specs.length)
+      terminal.with_spinner(-> { progress.message }) do
+        store.add_repos_to(space, repo_specs, reporter: progress)
+      end.fmap do |results|
+        results.each do |r|
+          terminal.success "Added #{r.fetch(:repo).fetch('full_name')}"
+          terminal.say terminal.path(r.fetch(:path))
+        end
+        space
+      end
+    end
+    render(result) do |space|
+      terminal.say terminal.path(space.path)
+      CLI.record_outcome(Outcome.new(exit_code: 0))
+    end
+  end
+end
+end

data/lib/space_core/cli/pack.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "../oci_packer"
+
+module Space::Core::CLI
+class Pack < BaseCommand
+  desc "Generate a portable OCI build context for the current space"
+  option :output, aliases: ["-o"], type: :string, default: nil,
+         desc: "Output directory (default: build/oci/ under the space root)"
+
+  def call(output: nil, **opts)
+    setup_terminal(**opts.slice(:color, :colors))
+    handle_errors do
+      result = store.current.bind do |space|
+        out_dir = output ? Pathname.new(output).expand_path : space.path.join("build", "oci")
+        Space::Core::OciPacker.new(space: space, output_dir: out_dir).generate
+          .fmap { |dir| { space: space, dir: dir } }
+      end
+      render(result) do |r|
+        terminal.success "Generated OCI context: #{r[:dir]}"
+        terminal.say "Build: docker build -f #{r[:dir]}/Dockerfile -t #{r[:space].id}:latest ."
+        terminal.say "  (run from: #{r[:space].path})"
+        CLI.record_outcome(Outcome.new(exit_code: 0))
+      end
+    end
+  end
+end
+end

data/lib/space_core/cli/path.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Space::Core::CLI
+class Path < BaseCommand
+  desc "Print the path for a space or the current space"
+  argument :identifier, required: false, desc: "Space ID or title slug"
+
+  def call(identifier: nil, **opts)
+    setup_terminal(**opts.slice(:color, :colors))
+    render(store.path_for(identifier)) do |path|
+      terminal.say terminal.path(path)
+      CLI.record_outcome(Outcome.new(exit_code: 0))
+    end
+  end
+end
+end

data/lib/space_core/cli/repeatable_options.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+
+# dry-cli (1.4.x) treats `type: :array` options as comma-separated and OVERWRITES
+# on each occurrence, so `-r a -r b` yields ["b"]. We want repeated flags to
+# accumulate (`-r a -r b -r c` => ["a", "b", "c"]) the way git/docker-style CLIs
+# do, while still accepting the comma form. dry-cli exposes no hook for this, so
+# we prepend two private seams, each mirroring dry-cli 1.4.1 with a single change:
+#
+#   * Parser.call                  — concat instead of assign for array options.
+#   * Banner.extended_command_options — drop the "=VALUE1,VALUE2,.." hint that
+#     advertised the comma form as the only way; show the plain repeatable flag,
+#     matching how you actually type it (-r VALUE).
+#
+# These mirror the released 1.4.1 source EXACTLY (not the dry-rb main branch,
+# which already differs), prepended onto the module's singleton class so `super`
+# reaches dry-cli's own implementation instead of discarding it outright. Pinned
+# via `~> 1.4`; if a future dry-cli reworks these methods, repeatable_options_test
+# goes red and we re-sync. Rationale: notes/ruby-cli-gems-report.md.
+module Dry
+  class CLI
+    module Parser
+      # Reopened on Parser's own nesting (not CLI's) so `Result` resolves
+      # lexically, exactly as it does in dry-cli's own `Parser.call`.
+      module RepeatableOptionsPatch
+        def call(command, arguments, prog_name)
+          original_arguments = arguments.dup
+          parsed_options = {}
+
+          OptionParser.new do |opts|
+            command.options.each do |option|
+              opts.on(*option.parser_options) do |value|
+                if option.array?
+                  (parsed_options[option.name.to_sym] ||= []).concat(value)
+                else
+                  parsed_options[option.name.to_sym] = value
+                end
+              end
+            end
+
+            opts.on_tail("-h", "--help") do
+              return Result.help
+            end
+          end.parse!(arguments)
+
+          parsed_options = command.default_params.merge(parsed_options)
+          parse_required_params(command, arguments, prog_name, parsed_options)
+        rescue ::OptionParser::ParseError, ValueError
+          Result.failure("ERROR: \"#{prog_name}\" was called with arguments \"#{original_arguments.join(" ")}\"")
+        end
+      end
+      singleton_class.prepend(RepeatableOptionsPatch)
+    end
+
+    module Banner
+      module RepeatableOptionsPatch
+        def extended_command_options(command)
+          result = command.options.map do |option|
+            name = Inflector.dasherize(option.name)
+            name = if option.boolean?
+                     "[no-]#{name}"
+                   elsif option.flag?
+                     name
+                   else
+                     # array options included: repeated flags accumulate, so show
+                     # the single repeatable form rather than "=VALUE1,VALUE2,..".
+                     "#{name}=VALUE"
+                   end
+            name = "#{name}, #{option.alias_names.join(", ")}" if option.aliases.any?
+            name = "  --#{name.ljust(30)}"
+            name = "#{name}  # #{option.desc}"
+            name = "#{name}, default: #{option.default.inspect}" unless option.default.nil?
+            name
+          end
+
+          result << "  --#{"help, -h".ljust(30)}  # Print this help"
+          result.join("\n")
+        end
+      end
+      singleton_class.prepend(RepeatableOptionsPatch)
+    end
+  end
+end

data/lib/space_core/cli/repo.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Space::Core::CLI
+module Repo
+  class Add < BaseCommand
+    desc "Add repos to the current space (copy-on-write from an evergreen checkout when available, else clone)"
+    argument :repos, type: :array, required: false, desc: "REPO [REPO...]"
+
+    def call(repos: [], **opts)
+      setup_terminal(**opts.slice(:color, :colors))
+      handle_errors do
+        specs = Array(repos).compact
+        if specs.empty?
+          terminal.error("Usage: space repo add REPO [REPO...]")
+          CLI.record_outcome(Outcome.new(exit_code: 1))
+          next
+        end
+
+        progress = RepoProgress.new(specs.length)
+        add_result = terminal.with_spinner(-> { progress.message }) do
+          store.add_repos(specs, reporter: progress)
+        end
+        render(add_result) do |results|
+          results.each do |result|
+            terminal.success "Added #{result.fetch(:repo).fetch('full_name')}"
+            terminal.say terminal.path(result.fetch(:path))
+          end
+          CLI.record_outcome(Outcome.new(exit_code: 0))
+        end
+      end
+    end
+  end
+
+  class RepoList < BaseCommand
+    desc "List repos in the current space"
+
+    def call(**opts)
+      setup_terminal(**opts.slice(:color, :colors))
+      handle_errors do
+        render(store.repos) do |repos|
+          if repos.empty?
+            id = store.find.fmap(&:id).value_or("(unknown space)")
+            terminal.say "No repos found in #{id}"
+            next
+          end
+
+          rows = repos.map { |repo| [repo.fetch("full_name", repo["name"]), repo.fetch("path", "")] }
+          terminal.say terminal.table(["Repo", "Path"], rows)
+          CLI.record_outcome(Outcome.new(exit_code: 0))
+        end
+      end
+    end
+  end
+
+  class Resolve < BaseCommand
+    desc "Resolve repo refs without cloning"
+    argument :repos, type: :array, required: false, desc: "REPO [REPO...]"
+
+    def call(repos: [], **opts)
+      setup_terminal(**opts.slice(:color, :colors))
+      handle_errors do
+        specs = Array(repos).compact
+        if specs.empty?
+          terminal.error("Usage: space repo resolve REPO [REPO...]")
+          CLI.record_outcome(Outcome.new(exit_code: 1))
+          next
+        end
+
+        references = specs.map { |spec| Space::Core::RepoResolver.new(project_config).resolve(spec) }
+        terminal.say terminal.table(["Repo", "Clone URL"], references.map { |ref| [ref.full_name, ref.clone_url] })
+        CLI.record_outcome(Outcome.new(exit_code: 0))
+      end
+    end
+  end
+end
+end