ace-assign 0.37.0

data/lib/ace/assign/molecules/assignment_manager.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+require "ace/b36ts"
+
+module Ace
+  module Assign
+    module Molecules
+      # Manages assignment YAML file operations.
+      #
+      # Handles creation, loading, and updating of assignment.yaml files.
+      # Uses ace-b36ts for assignment ID generation.
+      class AssignmentManager
+        # @param cache_base [String] Base cache directory
+        def initialize(cache_base: nil)
+          @cache_base = cache_base || Ace::Assign.cache_dir
+        end
+
+        # Create a new assignment
+        #
+        # @param name [String] Assignment name
+        # @param description [String, nil] Assignment description
+        # @param source_config [String] Path to source config file
+        # @param parent [String, nil] Parent assignment ID for hierarchy linking
+        # @return [Models::Assignment] Created assignment
+        def create(name:, source_config:, description: nil, parent: nil)
+          # Ensure cache base directory exists before generate_assignment_id
+          FileUtils.mkdir_p(@cache_base)
+
+          assignment_id = generate_assignment_id
+          cache_dir = File.join(@cache_base, assignment_id)
+
+          # Create directories
+          FileUtils.mkdir_p(cache_dir)
+          FileUtils.mkdir_p(File.join(cache_dir, "steps"))
+          FileUtils.mkdir_p(File.join(cache_dir, "reports"))
+
+          now = Time.now.utc
+
+          assignment = Models::Assignment.new(
+            id: assignment_id,
+            name: name,
+            description: description,
+            created_at: now,
+            updated_at: now,
+            source_config: source_config,
+            cache_dir: cache_dir,
+            parent: parent
+          )
+
+          # Write assignment.yaml
+          write_assignment_file(assignment)
+
+          # Update .latest symlink for O(1) active assignment lookup
+          update_latest_symlink(assignment_id)
+
+          assignment
+        end
+
+        # Load an existing assignment by ID
+        #
+        # @param assignment_id [String] Assignment ID
+        # @return [Models::Assignment, nil] Loaded assignment or nil
+        def load(assignment_id)
+          cache_dir = File.join(@cache_base, assignment_id)
+          assignment_file = File.join(cache_dir, "assignment.yaml")
+
+          return nil unless File.exist?(assignment_file)
+
+          data = YAML.safe_load_file(assignment_file, permitted_classes: [Time, Date])
+          Models::Assignment.from_h(data, cache_dir: cache_dir)
+        end
+
+        # Find the most recent active assignment
+        #
+        # Uses resolution order:
+        # 1. .current symlink (explicit user selection)
+        # 2. .latest symlink (auto, most recent)
+        # 3. Scan all assignments (fallback)
+        #
+        # @return [Models::Assignment, nil] Most recent assignment or nil
+        def find_active
+          return nil unless File.directory?(@cache_base)
+
+          # Priority 1: use .current symlink if it exists (explicit selection)
+          current_symlink = File.join(@cache_base, ".current")
+          if File.symlink?(current_symlink)
+            assignment_id = File.basename(File.readlink(current_symlink))
+            assignment = load(assignment_id)
+            return assignment if assignment
+          end
+
+          # Priority 2: use .latest symlink if it exists
+          latest_symlink = File.join(@cache_base, ".latest")
+          if File.symlink?(latest_symlink)
+            assignment_id = File.basename(File.readlink(latest_symlink))
+            assignment = load(assignment_id)
+            return assignment if assignment
+          end
+
+          # Fallback: find all assignment directories
+          assignments = Dir.glob(File.join(@cache_base, "*", "assignment.yaml"))
+            .map { |f| load_from_file(f) }
+            .compact
+            .sort_by(&:updated_at)
+            .reverse
+
+          assignments.first
+        end
+
+        # Set current assignment via .current symlink
+        #
+        # @param assignment_id [String] Assignment ID to set as current
+        # @raise [AssignmentErrors::NotFound] if assignment doesn't exist
+        def set_current(assignment_id)
+          assignment = load(assignment_id)
+          raise AssignmentErrors::NotFound, "Assignment '#{assignment_id}' not found" unless assignment
+
+          current_symlink = File.join(@cache_base, ".current")
+
+          # Remove old symlink if it exists
+          File.delete(current_symlink) if File.symlink?(current_symlink)
+
+          # Create new symlink
+          target_dir = File.join(@cache_base, assignment_id)
+          File.symlink(target_dir, current_symlink)
+
+          assignment
+        end
+
+        # Clear current assignment selection
+        #
+        # Removes the .current symlink, falling back to .latest resolution
+        def clear_current
+          current_symlink = File.join(@cache_base, ".current")
+          File.delete(current_symlink) if File.symlink?(current_symlink)
+        end
+
+        # Get the currently selected assignment ID (from .current symlink)
+        #
+        # @return [String, nil] Current assignment ID or nil
+        def current_id
+          current_symlink = File.join(@cache_base, ".current")
+          return nil unless File.symlink?(current_symlink)
+
+          File.basename(File.readlink(current_symlink))
+        end
+
+        # Delete an assignment's cache directory and clean up symlinks
+        #
+        # @param assignment_id [String] Assignment ID to delete
+        # @return [Boolean] true if deleted, false if not found
+        def delete(assignment_id)
+          dir = File.join(@cache_base, assignment_id)
+          return false unless File.directory?(dir)
+
+          cleanup_symlink(".current", assignment_id)
+          cleanup_symlink(".latest", assignment_id)
+          FileUtils.rm_rf(dir)
+          true
+        end
+
+        # Update assignment metadata
+        #
+        # @param assignment [Models::Assignment] Assignment to update
+        # @return [Models::Assignment] Updated assignment
+        def update(assignment)
+          # Create new assignment with updated timestamp
+          updated = Models::Assignment.new(
+            id: assignment.id,
+            name: assignment.name,
+            description: assignment.description,
+            created_at: assignment.created_at,
+            updated_at: Time.now.utc,
+            source_config: assignment.source_config,
+            cache_dir: assignment.cache_dir,
+            parent: assignment.parent
+          )
+
+          write_assignment_file(updated)
+
+          # Update .latest symlink since this assignment was just updated
+          update_latest_symlink(assignment.id)
+
+          updated
+        end
+
+        # List all assignments
+        #
+        # @return [Array<Models::Assignment>] All assignments
+        def list
+          return [] unless File.directory?(@cache_base)
+
+          Dir.glob(File.join(@cache_base, "*", "assignment.yaml"))
+            .map { |f| load_from_file(f) }
+            .compact
+            .sort_by(&:updated_at)
+            .reverse
+        end
+
+        private
+
+        def generate_assignment_id
+          base_id = Ace::B36ts.now
+          candidate = base_id
+          max_attempts = 100
+
+          # Handle collision by appending suffix
+          suffix = 0
+          max_attempts.times do
+            dir_path = File.join(@cache_base, candidate)
+            # Atomic directory creation using Dir.mkdir - fails if exists
+            begin
+              Dir.mkdir(dir_path)
+              return candidate
+            rescue Errno::EEXIST
+              # Directory already exists, try next candidate
+              suffix += 1
+              candidate = "#{base_id}#{suffix.to_s(36)}"
+            end
+          end
+
+          # Max attempts exceeded - this should never happen in practice
+          raise Error, "Failed to generate unique assignment ID after #{max_attempts} attempts. Cache directory may be corrupted."
+        end
+
+        def write_assignment_file(assignment)
+          assignment_file = File.join(assignment.cache_dir, "assignment.yaml")
+          File.write(assignment_file, assignment.to_h.to_yaml)
+        end
+
+        def load_from_file(assignment_file)
+          cache_dir = File.dirname(assignment_file)
+          data = YAML.safe_load_file(assignment_file, permitted_classes: [Time, Date])
+          Models::Assignment.from_h(data, cache_dir: cache_dir)
+        rescue => e
+          warn "Failed to load assignment from #{assignment_file}: #{e.message}" if Ace::Assign.debug?
+          nil
+        end
+
+        # Remove a symlink if it points to the specified assignment
+        #
+        # @param symlink_name [String] Symlink name (e.g., ".current", ".latest")
+        # @param assignment_id [String] Assignment ID to match
+        def cleanup_symlink(symlink_name, assignment_id)
+          symlink_path = File.join(@cache_base, symlink_name)
+          return unless File.symlink?(symlink_path)
+
+          target = File.basename(File.readlink(symlink_path))
+          File.delete(symlink_path) if target == assignment_id
+        rescue
+          # Non-fatal: continue without cleanup
+        end
+
+        # Update .latest symlink to point to the specified assignment
+        # Provides O(1) active assignment lookup
+        #
+        # @param assignment_id [String] Assignment ID to link as .latest
+        def update_latest_symlink(assignment_id)
+          latest_symlink = File.join(@cache_base, ".latest")
+          target_dir = File.join(@cache_base, assignment_id)
+
+          # Remove old symlink if it exists
+          File.delete(latest_symlink) if File.symlink?(latest_symlink)
+
+          # Create new symlink
+          File.symlink(target_dir, latest_symlink)
+        rescue => e
+          warn "Failed to update .latest symlink: #{e.message}" if Ace::Assign.debug?
+          # Non-fatal: continue without symlink
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/molecules/fork_session_launcher.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "ace/llm"
+require "fileutils"
+
+module Ace
+  module Assign
+    module Molecules
+      # Launches a forked assignment-driving session via CLI LLM providers.
+      class ForkSessionLauncher
+        DEFAULT_PROVIDER = "claude:sonnet"
+        DEFAULT_TIMEOUT = 1800
+
+        def initialize(config: nil, query_interface: Ace::LLM::QueryInterface)
+          @config = config || Ace::Assign.config
+          @query_interface = query_interface
+        end
+
+        # Launch forked subtree execution synchronously.
+        #
+        # @param assignment_id [String] Assignment identifier
+        # @param fork_root [String] Subtree root step number
+        # @param provider [String, nil] Optional provider override
+        # @param cli_args [String, nil] Optional provider CLI args
+        # @param timeout [Integer, nil] Optional timeout override (seconds)
+        # @param cache_dir [String, nil] Assignment cache directory for last-message capture
+        # @return [Hash] QueryInterface response
+        def launch(assignment_id:, fork_root:, provider: nil, cli_args: nil, timeout: nil, cache_dir: nil)
+          resolved_provider = provider || config.dig("execution", "provider") || DEFAULT_PROVIDER
+          resolved_timeout = timeout || config.dig("execution", "timeout") || DEFAULT_TIMEOUT
+          scoped_assignment = "#{assignment_id}@#{fork_root}"
+          last_msg_file = build_last_message_file(cache_dir, fork_root)
+
+          result = query_interface.query(
+            resolved_provider,
+            "/as-assign-drive #{scoped_assignment}",
+            system: nil,
+            cli_args: cli_args,
+            timeout: resolved_timeout,
+            fallback: false,
+            last_message_file: last_msg_file
+          )
+
+          # Layer 1 write: capture last message for non-Codex providers (or when Codex didn't write).
+          # Safety: `query` blocks until the subprocess exits, so by this point Layer 2 (Codex
+          # --output-last-message) has already finished writing. No other writer exists at this point.
+          if last_msg_file && result[:text] && !result[:text].strip.empty?
+            existing = File.exist?(last_msg_file) ? File.read(last_msg_file).strip : ""
+            File.write(last_msg_file, result[:text]) if existing.empty?
+          end
+
+          write_session_metadata(last_msg_file, result, prompt: "/as-assign-drive #{scoped_assignment}")
+
+          result
+        rescue Ace::LLM::Error => e
+          raise Error, "Fork session execution failed via #{resolved_provider}: #{e.message}"
+        end
+
+        private
+
+        attr_reader :config, :query_interface
+
+        def write_session_metadata(last_msg_file, result, prompt:)
+          return unless last_msg_file
+
+          session_id = result.dig(:metadata, :session_id)
+
+          if session_id.nil? || session_id.to_s.strip.empty?
+            detected = detect_provider_session(result[:provider], prompt)
+            session_id = detected&.dig(:session_id)
+          end
+
+          session_meta_file = last_msg_file.sub(/-last-message\.md$/, "-session.yml")
+          meta = {
+            "session_id" => session_id,
+            "provider" => result[:provider],
+            "model" => result[:model],
+            "completed_at" => Time.now.utc.iso8601
+          }.compact
+          File.write(session_meta_file, meta.to_yaml) unless meta.empty?
+        end
+
+        def detect_provider_session(provider, prompt)
+          require "ace/llm/providers/cli/molecules/session_finder"
+          Ace::LLM::Providers::CLI::Molecules::SessionFinder.call(
+            provider: provider, working_dir: Dir.pwd, prompt: prompt
+          )
+        rescue LoadError, StandardError
+          nil
+        end
+
+        def build_last_message_file(cache_dir, fork_root)
+          return nil unless cache_dir
+
+          sessions_dir = File.join(cache_dir, "sessions")
+          FileUtils.mkdir_p(sessions_dir)
+          File.join(sessions_dir, "#{fork_root}-last-message.md")
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/molecules/queue_scanner.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Ace
+  module Assign
+    module Molecules
+      # Scans and builds queue state from step files.
+      #
+      # Reconstructs queue by scanning steps/*.md files, sorting them,
+      # and parsing each file to build the complete queue state.
+      class QueueScanner
+        # Scan a steps directory and build queue state
+        #
+        # @param steps_dir [String] Path to steps directory
+        # @param assignment [Models::Assignment] Assignment metadata
+        # @return [Models::QueueState] Queue state
+        def scan(steps_dir, assignment:)
+          return Models::QueueState.new(steps: [], assignment: assignment) unless File.directory?(steps_dir)
+
+          # Get all step files
+          files = Dir.glob(File.join(steps_dir, "*.st.md"))
+
+          # Sort files
+          sorted_files = Atoms::StepSorter.sort(files.map { |f| File.basename(f) })
+            .map { |f| File.join(steps_dir, f) }
+
+          # Parse each file into a Step
+          steps = sorted_files.map { |file| parse_step_file(file) }.compact
+
+          Models::QueueState.new(steps: steps, assignment: assignment)
+        end
+
+        # Get current step from queue
+        #
+        # @param steps_dir [String] Path to steps directory
+        # @param assignment [Models::Assignment] Assignment metadata
+        # @return [Models::Step, nil] Current in-progress step
+        def current(steps_dir, assignment:)
+          state = scan(steps_dir, assignment: assignment)
+          state.current
+        end
+
+        # Get all step numbers in the queue
+        #
+        # @param steps_dir [String] Path to steps directory
+        # @return [Array<String>] Step numbers
+        def step_numbers(steps_dir)
+          return [] unless File.directory?(steps_dir)
+
+          files = Dir.glob(File.join(steps_dir, "*.st.md"))
+          files.map do |file|
+            parsed = Atoms::StepFileParser.parse_filename(File.basename(file))
+            parsed[:number]
+          end.compact
+        end
+
+        private
+
+        def parse_step_file(file_path)
+          content = File.read(file_path)
+          parsed = Atoms::StepFileParser.parse(content)
+          fields = Atoms::StepFileParser.extract_fields(parsed)
+
+          # Extract number and name from filename
+          filename_info = Atoms::StepFileParser.parse_filename(File.basename(file_path))
+
+          # Load report from separate file if it exists
+          report = load_report(file_path, filename_info[:number], filename_info[:name])
+
+          Models::Step.new(
+            number: filename_info[:number],
+            name: fields[:name] || filename_info[:name],
+            status: fields[:status],
+            instructions: fields[:instructions],
+            report: report,
+            error: fields[:error],
+            started_at: fields[:started_at],
+            completed_at: fields[:completed_at],
+            fork_launch_pid: fields[:fork_launch_pid],
+            fork_tracked_pids: fields[:fork_tracked_pids],
+            fork_pid_updated_at: fields[:fork_pid_updated_at],
+            fork_pid_file: fields[:fork_pid_file],
+            added_by: fields[:added_by],
+            parent: fields[:parent],
+            skill: fields[:skill],
+            workflow: fields[:workflow],
+            context: fields[:context],
+            batch_parent: fields[:batch_parent],
+            parallel: fields[:parallel],
+            max_parallel: fields[:max_parallel],
+            fork_retry_limit: fields[:fork_retry_limit],
+            stall_reason: fields[:stall_reason],
+            file_path: file_path
+          )
+        rescue ArgumentError => e
+          # ArgumentError indicates invalid data (e.g., invalid context value)
+          # Surface these errors visibly to help users fix configuration
+          warn "Invalid step file #{file_path}: #{e.message}"
+          nil
+        rescue => e
+          warn "Failed to parse step file #{file_path}: #{e.message}" if Ace::Assign.debug?
+          nil
+        end
+
+        # Load report from the reports/ directory
+        # @param step_file_path [String] Path to step file
+        # @param number [String] Step number
+        # @param name [String] Step name
+        # @return [String, nil] Report content or nil
+        def load_report(step_file_path, number, name)
+          # reports/ is sibling of steps/
+          steps_dir = File.dirname(step_file_path)
+          cache_dir = File.dirname(steps_dir)
+          reports_dir = File.join(cache_dir, "reports")
+
+          return nil unless File.directory?(reports_dir)
+
+          report_filename = Atoms::StepFileParser.generate_report_filename(number, name)
+          report_path = File.join(reports_dir, report_filename)
+
+          return nil unless File.exist?(report_path)
+
+          # Read report file and extract body (skip frontmatter)
+          content = File.read(report_path)
+          parsed = Atoms::StepFileParser.parse(content)
+          parsed[:body].strip
+        end
+      end
+    end
+  end
+end