ace-assign 0.37.0

data/lib/ace/assign/atoms/step_file_parser.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Assign
+    module Atoms
+      # Pure functions for parsing step markdown files.
+      #
+      # Step files have frontmatter + body structure:
+      # ---
+      # name: step-name
+      # status: pending
+      # ---
+      # # Instructions
+      # ...
+      module StepFileParser
+        FRONTMATTER_REGEX = /\A---\s*\n(.*?)\n---\s*\n/m
+
+        # Parse step file content into structured data
+        #
+        # @param content [String] File content with frontmatter + body
+        # @return [Hash] Parsed data with :frontmatter and :body keys
+        def self.parse(content)
+          match = content.match(FRONTMATTER_REGEX)
+
+          if match
+            frontmatter_yaml = match[1]
+            body = content[match.end(0)..]
+
+            frontmatter = YAML.safe_load(frontmatter_yaml, permitted_classes: [Time, Date]) || {}
+            {frontmatter: frontmatter, body: body.strip}
+          else
+            {frontmatter: {}, body: content.strip}
+          end
+        end
+
+        # Extract specific fields from parsed content
+        #
+        # @param parsed [Hash] Result from parse()
+        # @return [Hash] Extracted fields
+        def self.extract_fields(parsed)
+          fm = parsed[:frontmatter]
+          body = parsed[:body]
+
+          context = fm["context"]
+          validate_context!(context)
+
+          {
+            name: fm["name"],
+            status: (fm["status"] || "pending").to_sym,
+            skill: fm["skill"],
+            workflow: fm["workflow"],
+            context: context, # "fork" triggers Task tool execution
+            batch_parent: parse_boolean(fm["batch_parent"]),
+            parallel: parse_boolean(fm["parallel"]),
+            max_parallel: parse_positive_integer(fm["max_parallel"]),
+            fork_retry_limit: parse_non_negative_integer(fm["fork_retry_limit"]),
+            started_at: parse_time(fm["started_at"]),
+            completed_at: parse_time(fm["completed_at"]),
+            fork_launch_pid: parse_integer(fm["fork_launch_pid"]),
+            fork_tracked_pids: parse_integer_array(fm["fork_tracked_pids"]),
+            fork_pid_updated_at: parse_time(fm["fork_pid_updated_at"]),
+            fork_pid_file: fm["fork_pid_file"],
+            error: fm["error"],
+            stall_reason: fm["stall_reason"],
+            added_by: fm["added_by"],
+            parent: fm["parent"],
+            instructions: body.strip,
+            report: nil # Reports are loaded separately from reports/ dir
+          }
+        end
+
+        # Extract instructions section from body
+        # Body is now just instructions (report is in separate file)
+        #
+        # @param body [String] File body after frontmatter
+        # @return [String] Instructions content
+        def self.extract_instructions(body)
+          body.strip
+        end
+
+        # Parse filename to extract number, name, and parent.
+        #
+        # @param filename [String] Filename like "010-init-project.st.md" or "010-init-project.r.md"
+        # @return [Hash] Extracted number, name, and parent (if nested)
+        def self.parse_filename(filename)
+          # Remove .st.md or .r.md extension
+          base = filename.sub(/\.(st|r)\.md$/, "")
+
+          # Match number pattern (with optional dot-separated parts) and name
+          match = base.match(/^([\d.]+)-(.+)$/)
+
+          if match
+            number = match[1]
+            name = match[2]
+            parent = extract_parent_from_number(number)
+            {number: number, name: name, parent: parent}
+          else
+            {number: nil, name: base, parent: nil}
+          end
+        end
+
+        # Extract parent number from a hierarchical step number.
+        #
+        # @param number [String] Step number (e.g., "010.01")
+        # @return [String, nil] Parent number or nil for top-level
+        def self.extract_parent_from_number(number)
+          return nil if number.nil?
+
+          parts = number.split(".")
+          return nil if parts.length <= 1
+
+          parts[0..-2].join(".")
+        end
+
+        # Generate step filename from number and name
+        #
+        # @param number [String] Step number
+        # @param name [String] Step name
+        # @return [String] Step filename with .st.md extension
+        def self.generate_filename(number, name)
+          # Sanitize name for filename
+          safe_name = name.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/^-|-$/, "")
+          "#{number}-#{safe_name}.st.md"
+        end
+
+        # Generate report filename from number and name
+        #
+        # @param number [String] Step number
+        # @param name [String] Step name
+        # @return [String] Report filename with .r.md extension
+        def self.generate_report_filename(number, name)
+          # Sanitize name for filename
+          safe_name = name.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/^-|-$/, "")
+          "#{number}-#{safe_name}.r.md"
+        end
+
+        private
+
+        def self.validate_context!(context)
+          return if context.nil?
+
+          valid_contexts = Ace::Assign::Models::Step::VALID_CONTEXTS
+          return if valid_contexts.include?(context)
+
+          raise ArgumentError, "Invalid context '#{context}'. Valid values: #{valid_contexts.join(", ")}"
+        end
+        private_class_method :validate_context!
+
+        def self.parse_time(value)
+          return nil if value.nil?
+          return value if value.is_a?(Time)
+
+          Time.parse(value.to_s)
+        rescue ArgumentError
+          nil
+        end
+        private_class_method :parse_time
+
+        def self.parse_integer(value)
+          return nil if value.nil?
+
+          Integer(value)
+        rescue ArgumentError, TypeError
+          nil
+        end
+        private_class_method :parse_integer
+
+        def self.parse_integer_array(value)
+          return [] if value.nil?
+
+          Array(value).map { |v| parse_integer(v) }.compact.uniq.sort
+        end
+        private_class_method :parse_integer_array
+
+        def self.parse_boolean(value)
+          return nil if value.nil?
+          return value if value == true || value == false
+
+          normalized = value.to_s.strip.downcase
+          return true if %w[true yes 1].include?(normalized)
+          return false if %w[false no 0].include?(normalized)
+
+          nil
+        end
+        private_class_method :parse_boolean
+
+        def self.parse_positive_integer(value)
+          parsed = parse_integer(value)
+          return nil if parsed.nil? || parsed <= 0
+
+          parsed
+        end
+        private_class_method :parse_positive_integer
+
+        def self.parse_non_negative_integer(value)
+          parsed = parse_integer(value)
+          return nil if parsed.nil? || parsed.negative?
+
+          parsed
+        end
+        private_class_method :parse_non_negative_integer
+      end
+    end
+  end
+end

data/lib/ace/assign/atoms/step_numbering.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module Atoms
+      # Pure functions for hierarchical step numbering operations.
+      #
+      # Supports nested step structure where steps can have sub-steps:
+      # - Main steps: 010, 020, 030
+      # - Nested steps: 010.01, 010.02, 010.03
+      # - Deeply nested: 010.01.01 (if needed)
+      #
+      # This enables verification-as-step patterns where parent steps
+      # wait for all children to complete before advancing.
+      #
+      # @example
+      #   StepNumbering.parse("010.02")
+      #   # => { parent: "010", index: 2, depth: 1, full: "010.02" }
+      #
+      #   StepNumbering.next_sibling("010.02")
+      #   # => "010.03"
+      #
+      #   StepNumbering.first_child("010")
+      #   # => "010.01"
+      #
+      #   StepNumbering.child_of?("010.02", "010")
+      #   # => true
+      module StepNumbering
+        # Maximum allowed nesting depth for step numbers.
+        # Prevents unbounded hierarchy (e.g., 010.01.01.01.01...).
+        # Depth 0 = top-level (010), 1 = first nest (010.01), 2 = second nest (010.01.01).
+        # Maximum is 010.01.01 (3 levels total).
+        MAX_DEPTH = 2
+
+        # Maximum siblings per level.
+        # Child indexes use %02d format (01-99). Top-level uses %03d (001-999).
+        # Exceeding these limits will cause lexicographical sorting issues.
+        MAX_SIBLINGS_TOP_LEVEL = 999
+        MAX_SIBLINGS_NESTED = 99
+
+        # Parse a step number into its components.
+        #
+        # @param number [String] Step number (e.g., "010", "010.02", "010.02.03")
+        # @return [Hash] Parsed components with keys:
+        #   - :parent [String, nil] Parent step number (nil for top-level steps)
+        #   - :index [Integer] The final sequence number
+        #   - :depth [Integer] Nesting depth (0 for top-level, 1 for first nest, etc.)
+        #   - :full [String] Original full number
+        def self.parse(number)
+          parts = number.to_s.split(".")
+
+          {
+            parent: (parts.length > 1) ? parts[0..-2].join(".") : nil,
+            index: parts.last.to_i,
+            depth: parts.length - 1,
+            full: number.to_s
+          }
+        end
+
+        # Generate the next sibling step number.
+        #
+        # @param number [String] Current step number
+        # @return [String] Next sibling number with same parent
+        def self.next_sibling(number)
+          parsed = parse(number)
+          new_index = parsed[:index] + 1
+          limit = parsed[:parent] ? MAX_SIBLINGS_NESTED : MAX_SIBLINGS_TOP_LEVEL
+
+          if new_index > limit
+            raise ArgumentError, "Cannot create sibling: would exceed maximum siblings " \
+                                 "(#{limit}) at this level (current index: #{parsed[:index]})"
+          end
+
+          if parsed[:parent]
+            "#{parsed[:parent]}.#{format("%02d", new_index)}"
+          else
+            # Top-level numbers use 3-digit padding
+            format("%03d", new_index)
+          end
+        end
+
+        # Generate the first child step number.
+        #
+        # @param number [String] Parent step number
+        # @return [String] First child number (e.g., "010" -> "010.01")
+        # @raise [ArgumentError] If adding a child would exceed MAX_DEPTH
+        def self.first_child(number)
+          parent_depth = parse(number)[:depth]
+          child_depth = parent_depth + 1
+          if child_depth > MAX_DEPTH
+            raise ArgumentError, "Cannot create child: would exceed maximum nesting depth of #{MAX_DEPTH} " \
+                                 "(parent '#{number}' is at depth #{parent_depth})"
+          end
+          "#{number}.01"
+        end
+
+        # Generate the next child step number based on existing children.
+        #
+        # @param parent [String] Parent step number
+        # @param existing_children [Array<String>] Existing child numbers
+        # @return [String] Next child number
+        # @raise [ArgumentError] If adding a child would exceed MAX_DEPTH
+        def self.next_child(parent, existing_children = [])
+          parent_depth = parse(parent)[:depth]
+          child_depth = parent_depth + 1
+          if child_depth > MAX_DEPTH
+            raise ArgumentError, "Cannot create child: would exceed maximum nesting depth of #{MAX_DEPTH} " \
+                                 "(parent '#{parent}' is at depth #{parent_depth})"
+          end
+
+          return first_child(parent) if existing_children.empty?
+
+          # Find highest existing child index
+          max_index = existing_children
+            .select { |n| child_of?(n, parent) && direct_child_of?(n, parent) }
+            .map { |n| parse(n)[:index] }
+            .max || 0
+
+          "#{parent}.#{format("%02d", max_index + 1)}"
+        end
+
+        # Check if a step number is a child (direct or nested) of another.
+        #
+        # @param child [String] Potential child number
+        # @param parent [String] Potential parent number
+        # @return [Boolean] True if child is descended from parent
+        def self.child_of?(child, parent)
+          child.to_s.start_with?("#{parent}.")
+        end
+
+        # Check if a step number is a direct (immediate) child of another.
+        #
+        # @param child [String] Potential child number
+        # @param parent [String] Potential parent number
+        # @return [Boolean] True if child is immediate child of parent
+        def self.direct_child_of?(child, parent)
+          return false unless child_of?(child, parent)
+
+          # Direct child has exactly one more level
+          child_parsed = parse(child)
+          parent_parsed = parse(parent)
+
+          child_parsed[:depth] == parent_parsed[:depth] + 1
+        end
+
+        # Get all direct children of a parent from a list of numbers.
+        #
+        # @param parent [String] Parent step number
+        # @param all_numbers [Array<String>] All step numbers to filter
+        # @return [Array<String>] Direct children of parent
+        def self.direct_children(parent, all_numbers)
+          all_numbers.select { |n| direct_child_of?(n, parent) }
+        end
+
+        # Get the parent number of a step, if it has one.
+        #
+        # @param number [String] Step number
+        # @return [String, nil] Parent number or nil for top-level steps
+        def self.parent_of(number)
+          parse(number)[:parent]
+        end
+
+        # Check if a number is a top-level (root) step.
+        #
+        # @param number [String] Step number
+        # @return [Boolean] True if top-level
+        def self.top_level?(number)
+          parse(number)[:depth] == 0
+        end
+
+        # Generate a step number to insert after another step.
+        # This creates a sibling at the same nesting level.
+        #
+        # Note: This method does not check for collisions. Use steps_to_renumber
+        # to determine which existing steps need to be shifted when inserting.
+        #
+        # @param after [String] Step number to insert after
+        # @return [String] New step number (next sibling)
+        def self.insert_after(after)
+          next_sibling(after)
+        end
+
+        # Find step numbers that need to be renumbered when inserting at a position.
+        # Returns steps that have numbers >= the insertion point.
+        #
+        # @param at_number [String] Number where new step will be inserted
+        # @param existing [Array<String>] All existing step numbers
+        # @return [Array<String>] Numbers that need to be shifted (in ascending order)
+        def self.steps_to_renumber(at_number, existing)
+          parsed_at = parse(at_number)
+          parent = parsed_at[:parent]
+
+          existing
+            .select { |n|
+              parsed = parse(n)
+              # Same parent (or both top-level) and index >= insertion point
+              parsed[:parent] == parent && parsed[:index] >= parsed_at[:index]
+            }
+            .sort_by { |n| parse(n)[:index] }
+        end
+
+        # Generate the shifted number for a step being renumbered.
+        #
+        # @param number [String] Original step number
+        # @param shift [Integer] Amount to shift by (default: 1)
+        # @return [String] New shifted number
+        # @raise [ArgumentError] If shifting would exceed sibling limits
+        def self.shift_number(number, shift = 1)
+          parsed = parse(number)
+          new_index = parsed[:index] + shift
+          limit = parsed[:parent] ? MAX_SIBLINGS_NESTED : MAX_SIBLINGS_TOP_LEVEL
+
+          if new_index > limit
+            raise ArgumentError, "Cannot shift step number: would exceed maximum siblings " \
+                                 "(#{limit}) at this level (new index would be: #{new_index})"
+          end
+
+          if parsed[:parent]
+            "#{parsed[:parent]}.#{format("%02d", new_index)}"
+          else
+            format("%03d", new_index)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/atoms/step_sorter.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module Atoms
+      # Pure functions for sorting step files lexicographically.
+      #
+      # Steps are sorted by their numeric components:
+      # 010 < 010.01 < 010.01.01 < 010.02 < 020
+      module StepSorter
+        # Sort filenames lexicographically by step number
+        #
+        # @param filenames [Array<String>] Array of filenames
+        # @return [Array<String>] Sorted filenames
+        def self.sort(filenames)
+          filenames.sort_by { |f| sort_key(f) }
+        end
+
+        # Generate a sort key for a filename
+        #
+        # The key is an array of integers that can be compared
+        # to produce correct lexicographic ordering.
+        #
+        # @param filename [String] Filename to generate key for
+        # @return [Array<Integer>] Sort key
+        def self.sort_key(filename)
+          # Extract number from filename (strip .st.md or .r.md extension)
+          base = filename.sub(/\.(ph|r)\.md$/, "")
+          number_part = base.split("-").first
+
+          # Split by dots and convert to integers
+          parts = number_part.split(".").map(&:to_i)
+
+          # Pad to 3 parts for consistent comparison
+          parts + Array.new(3 - parts.size, 0)
+        end
+
+        # Sort step numbers directly
+        #
+        # @param numbers [Array<String>] Array of step numbers
+        # @return [Array<String>] Sorted step numbers
+        def self.sort_numbers(numbers)
+          numbers.sort_by { |n| number_key(n) }
+        end
+
+        # Generate a sort key for a step number
+        #
+        # @param number [String] Step number
+        # @return [Array<Integer>] Sort key
+        def self.number_key(number)
+          parts = number.split(".").map(&:to_i)
+          parts + Array.new(3 - parts.size, 0)
+        end
+
+        # Compare two step numbers
+        #
+        # @param a [String] First step number
+        # @param b [String] Second step number
+        # @return [Integer] -1, 0, or 1
+        def self.compare(a, b)
+          number_key(a) <=> number_key(b)
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/atoms/tree_formatter.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module Atoms
+      # Pure function: renders assignment hierarchy as an indented tree string.
+      #
+      # Takes a flat list of AssignmentInfo objects with parent fields
+      # and renders them as a visual tree with Unicode box-drawing characters.
+      #
+      # @example
+      #   TreeFormatter.format(assignments)
+      #   # =>  task-148-implement
+      #   #     +-- onboard (completed)
+      #   #     +-- work-on-task (running)
+      #   #     |   +-- onboard (completed)
+      #   #     |   +-- implement (in_progress)
+      #   #     |   \-- verify-tests (pending)
+      #   #     \-- review-pr (pending)
+      module TreeFormatter
+        # State display labels matching list command
+        STATE_LABELS = {
+          pending: "pending",
+          in_progress: "in_progress",
+          running: "running",
+          paused: "paused",
+          completed: "completed",
+          failed: "failed",
+          empty: "empty"
+        }.freeze
+
+        # Format a flat list of assignment info objects as a tree.
+        #
+        # @param assignments [Array<Models::AssignmentInfo>] Flat list with parent metadata
+        # @return [String] Formatted tree string
+        def self.format(assignments)
+          return "No assignments found." if assignments.empty?
+
+          # Build ID index first (pass 1), then attach children (pass 2)
+          by_id = {}
+          assignments.each { |info| by_id[info.id] = info }
+
+          children_of = Hash.new { |h, k| h[k] = [] }
+          assignments.each do |info|
+            parent_id = extract_parent_id(info)
+            if parent_id && by_id.key?(parent_id)
+              children_of[parent_id] << info
+            end
+          end
+
+          # Find roots: assignments whose parent is nil or not in the set
+          roots = assignments.reject do |info|
+            parent_id = extract_parent_id(info)
+            parent_id && by_id.key?(parent_id)
+          end
+
+          lines = []
+          roots.each do |root|
+            render_node(root, children_of, lines, prefix: "", is_last: true, is_root: true)
+          end
+
+          lines.join("\n")
+        end
+
+        # Extract parent assignment ID from an AssignmentInfo.
+        #
+        # @param info [Models::AssignmentInfo] Assignment info
+        # @return [String, nil] Parent assignment ID or nil
+        def self.extract_parent_id(info)
+          return nil unless info.assignment.respond_to?(:parent)
+
+          info.assignment.parent
+        end
+        private_class_method :extract_parent_id
+
+        # Render a single node and its children recursively.
+        #
+        # @param info [Models::AssignmentInfo] Current node
+        # @param children_of [Hash] Children index
+        # @param lines [Array<String>] Output lines accumulator
+        # @param prefix [String] Indentation prefix
+        # @param is_last [Boolean] Whether this is the last sibling
+        # @param is_root [Boolean] Whether this is a root node
+        def self.render_node(info, children_of, lines, prefix:, is_last:, is_root:)
+          state_label = STATE_LABELS[info.state] || info.state.to_s
+
+          if is_root
+            lines << "#{info.name} [#{info.id}] (#{state_label}) #{info.progress}"
+            child_prefix = ""
+          else
+            connector = is_last ? "\\-- " : "+-- "
+            lines << "#{prefix}#{connector}#{info.name} [#{info.id}] (#{state_label}) #{info.progress}"
+            child_prefix = prefix + (is_last ? "    " : "|   ")
+          end
+
+          children = children_of[info.id] || []
+          children.each_with_index do |child, idx|
+            child_is_last = idx == children.size - 1
+            render_node(child, children_of, lines, prefix: child_prefix, is_last: child_is_last, is_root: false)
+          end
+        end
+        private_class_method :render_node
+      end
+    end
+  end
+end