space-architect 3.0.0 → 5.0.0

data/lib/space_core/cli/help.rb

@@ -2,6 +2,7 @@
 
 require "dry/cli"
 require "pastel"
+require_relative "loop_status"
 
 module Space::Core::CLI
   # Colourful replacement for dry-cli's plain `Usage` listing — the "global
@@ -27,17 +28,30 @@ module Space::Core::CLI
 
     module_function
 
-    def call(result, pastel: CLI.help_pastel)
-      rows  = listing(result)
-      width = rows.map { |label, _| label.length }.max || 0
+    # 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
 
-      lines = rows.map do |label, description|
-        painted = pastel.cyan(label.ljust(width))
-        description ? "  #{painted}   #{pastel.dim("# #{description}")}" : "  #{painted}"
+    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:"), *lines, footer(result, pastel)]
-        .compact.join("\n")
+      [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`),
@@ -69,13 +83,66 @@ module Space::Core::CLI
       [prog, *names].join(" ")
     end
 
-    # [[label_with_banner, description_or_nil], ...] sorted by command name.
-    def listing(result)
-      result.children.sort_by { |name, _| name }.filter_map do |name, node|
-        next if node.hidden
+    # 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)
+      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
 
-        [label(result, name, node), description(node)]
+      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_architect 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)
@@ -109,15 +176,18 @@ module Space::Core::CLI
 end
 
 # Route dry-cli's plain namespace/root listing through our colourful renderer.
-# We replace 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.
+# 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
-      def self.call(result)
-        Space::Core::CLI::Help.call(result)
+      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/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_architect. 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/repeatable_options.rb

@@ -6,7 +6,7 @@ require "dry/cli"
 # 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 reopen two private seams, each mirroring dry-cli 1.4.1 with a single change:
+# 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
@@ -14,62 +14,71 @@ require "dry/cli"
 #     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). 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.
+# 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
-      def self.call(command, arguments, prog_name)
-        original_arguments = arguments.dup
-        parsed_options = {}
+      # 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
+          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
-          end
 
-          opts.on_tail("-h", "--help") do
-            return Result.help
-          end
-        end.parse!(arguments)
+            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(" ")}\"")
+          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
-      def self.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
+      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")
+          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/status.rb

@@ -5,28 +5,69 @@ class Status < BaseCommand
   desc "Set a space status: active, paused, done, archived"
   argument :rest, type: :array, required: false, desc: "[SPACE] STATUS"
 
+  # One command, overloaded by its positional(s):
+  #   help token (`help`, or dry-cli's -h/--help which never reach here) → help
+  #   lone keyword / `<space> <keyword>`                                 → set
+  #   bare, or a lone non-keyword identifier                            → report
   def call(rest: [], **opts)
     setup_terminal(**opts.slice(:color, :colors))
+    args = Array(rest)
+    return show_help if help_token?(args)
+
     handle_errors do
-      identifier, status_value = parse_status_args(Array(rest))
-      render(store.find(identifier)) do |space|
-        space.update_status(status_value)
-        terminal.success "#{space.id} is #{space.status}"
-        CLI.record_outcome(Outcome.new(exit_code: 0))
+      if set_args?(args)
+        set_status(args)
+      elsif args.length <= 1
+        report(args.first)
+      else
+        raise Space::Core::Error, "Usage: space status [SPACE] STATUS"
       end
     end
   end
 
   private
 
-  def parse_status_args(args)
-    case args.length
-    when 1
-      [nil, args.first]
-    when 2
-      args
-    else
-      raise Space::Core::Error, "Usage: space status [SPACE] STATUS"
+  # The bare word `help` shows the command help, like dry-cli's -h/--help (which
+  # it intercepts before dispatch). It must never set status to "help" or report.
+  def help_token?(args)
+    args == ["help"]
+  end
+
+  def show_help
+    out.puts Dry::CLI::Banner.call(self.class, Dry::CLI::ProgramName.call(["status"]))
+    CLI.record_outcome(Outcome.new(exit_code: 0))
+  end
+
+  # A set request: `<space> <keyword>` (two args), or a lone status keyword. A
+  # lone non-keyword arg is a space identifier to REPORT, not a malformed status.
+  def set_args?(args)
+    args.length == 2 ||
+      (args.length == 1 && Space::Core::Space::VALID_STATUSES.include?(args.first))
+  end
+
+  def set_status(args)
+    identifier, status_value = args.length == 2 ? args : [nil, args.first]
+    render(store.find(identifier)) do |space|
+      space.update_status(status_value)
+      terminal.success "#{space.id} is #{space.status}"
+      CLI.record_outcome(Outcome.new(exit_code: 0))
+    end
+  end
+
+  def report(identifier)
+    render(store.find(identifier)) do |space|
+      terminal.say "ID:         #{space.id}"
+      terminal.say "Title:      #{space.title}"
+      terminal.say "Status:     #{space.status}"
+      terminal.say "Path:       #{terminal.path(space.path)}"
+      terminal.say "Created:    #{space.data['created_at']}"
+      terminal.say "Updated:    #{space.data['updated_at']}"
+      lines = LoopStatus.lines(space.data["project"])
+      if lines
+        terminal.say ""
+        lines.each { |line| terminal.say line }
+      end
+      CLI.record_outcome(Outcome.new(exit_code: 0))
     end
   end
 end

data/lib/space_core/shell_integration.rb

@@ -295,7 +295,7 @@ module Space::Core
       complete -c space -f -n "__space_architect_complete_needs_command" -a path -d "Print a space path"
       complete -c space -f -n "__space_architect_complete_needs_command" -a use -d "Select and cd to a space with fish integration"
       complete -c space -f -n "__space_architect_complete_needs_command" -a current -d "Show the current space"
-      complete -c space -f -n "__space_architect_complete_needs_command" -a status -d "Set a space status"
+      complete -c space -f -n "__space_architect_complete_needs_command" -a status -d "Report or set a space status"
       complete -c space -f -n "__space_architect_complete_needs_command" -a config -d "Show or update config"
       complete -c space -f -n "__space_architect_complete_needs_command" -a repo -d "Manage repos in the current space"
       complete -c space -f -n "__space_architect_complete_needs_command" -a repos -d "Manage repos in the current space"

data/lib/space_core/space.rb

@@ -9,6 +9,11 @@ module Space::Core
     METADATA_FILE = "space.yaml"
     VALID_STATUSES = %w[active paused done archived].freeze
 
+    # Canonical space.yaml shape: registry under `project:` (renamed from the
+    # pre-2.0 `architect:` key). Bumped from 1 in the release that did the
+    # rename, since that release shipped no read-side alias for it.
+    SCHEMA_VERSION = 2
+
     attr_reader :path, :data
 
     def self.load(path)
@@ -18,13 +23,58 @@ module Space::Core
       parsed = YAML.safe_load(metadata_path.read, aliases: false) || {}
       raise Error, "Space metadata must contain a YAML mapping: #{metadata_path}" unless parsed.is_a?(Hash)
 
-      new(Pathname.new(path), stringify_keys(parsed))
+      data = stringify_keys(parsed)
+      normalize_schema!(data, metadata_path)
+      new(Pathname.new(path), data)
     end
 
     def self.stringify_keys(hash)
       hash.each_with_object({}) { |(key, value), result| result[key.to_s] = value }
     end
 
+    # Normalizes a parsed space.yaml hash to canonical schema v2, in place:
+    #   - future version (> SCHEMA_VERSION) → raise, refuse to misread it.
+    #   - `architect:` only (v1a) → becomes `project:`.
+    #   - `project:` only (v1b or v2) → left as-is.
+    #   - both present, `project:` empty and `architect:` non-empty → the
+    #     corruption from the old silent-default read path; take `architect:`.
+    #   - both present and non-empty: identical → keep; differing → raise
+    #     rather than silently pick one and lose data.
+    # Idempotent, so a canonical v2 space is a no-op through this method.
+    def self.normalize_schema!(data, metadata_path)
+      version = data["version"]
+      if version.is_a?(Integer) && version > SCHEMA_VERSION
+        raise Error,
+          "space.yaml schema version #{version} is newer than this gem supports " \
+          "(#{SCHEMA_VERSION}); upgrade space-architect: #{metadata_path}"
+      end
+
+      legacy = data.delete("architect")
+      current = data["project"]
+
+      data["project"] =
+        if legacy.nil?
+          current
+        elsif current.nil? || empty_project_block?(current)
+          legacy
+        elsif legacy == current
+          current
+        else
+          raise Error,
+            "#{metadata_path} has both 'architect:' and 'project:' blocks with " \
+            "conflicting content; resolve manually.\narchitect: #{legacy.inspect}\n" \
+            "project: #{current.inspect}"
+        end
+
+      data["version"] = SCHEMA_VERSION
+    end
+    private_class_method :normalize_schema!
+
+    def self.empty_project_block?(block)
+      block.is_a?(Hash) && Array(block["iterations"]).empty? && block["current_iteration"].nil?
+    end
+    private_class_method :empty_project_block?
+
     def initialize(path, data)
       @path = Pathname.new(path)
       @data = data

data/lib/space_core/space_store.rb

@@ -232,7 +232,7 @@ module Space::Core
     def metadata_for(id:, title:, timestamp:)
       iso_timestamp = timestamp.iso8601
       {
-        "version" => 1,
+        "version" => 2,
         "id" => id,
         "title" => title,
         "status" => "active",

data/lib/space_core/version.rb

@@ -2,6 +2,6 @@
 
 module Space
   module Core
-    VERSION = "3.0.0"
+    VERSION = "5.0.0"
   end
 end

data/lib/space_src/cli/clone.rb

@@ -2,7 +2,6 @@
 
 require "pastel"
 require "dry/monads"
-require "space_src/cli"
 require "space_src/cli/options"
 require "space_src/cloner"
 

data/lib/space_src/cli/config.rb

@@ -2,7 +2,6 @@
 
 require "pastel"
 require "yaml"
-require "space_src/cli"
 require "space_src/ui/mode"
 require "space_src/cli/options"
 

data/lib/space_src/cli/daemon.rb

@@ -3,7 +3,6 @@
 require "pastel"
 require "fileutils"
 require "dry/monads"
-require "space_src/cli"
 require "space_src/ui/mode"
 require "space_src/cli/options"
 require "space_src/launchd/agent"

data/lib/space_src/cli/org.rb

@@ -2,7 +2,6 @@
 
 require "pastel"
 require "dry/monads"
-require "space_src/cli"
 require "space_src/ui/mode"
 require "space_src/cli/options"
 

data/lib/space_src/cli/repo.rb

@@ -2,7 +2,6 @@
 
 require "pastel"
 require "dry/monads"
-require "space_src/cli"
 require "space_src/ui/mode"
 require "space_src/cli/options"
 

data/lib/space_src/cli/shell.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "space_src/cli"
 require "space_src/shell_integration"
 
 module Space::Src

data/lib/space_src/cli/status.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "pastel"
-require "space_src/cli"
 require "space_src/ui/mode"
 require "space_src/cli/options"
 

data/lib/space_src/cli/sync.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "dry/monads"
-require "space_src/cli"
 require "space_src/cli/repo"  # for Repo::Helpers.parse_ref
 require "space_src/cli/options"
 require "space_src/ui/mode"

data/lib/space_src/cli.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "dry/cli"
-require "space_src"
 require "space_src/migration"
 
 module Space::Src