ace-git-worktree 0.26.0 → 0.27.0

data/lib/ace/git/worktree/organisms/worktree_list_report.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "../atoms/duration_parser"
+require_relative "../molecules/worktree_lister"
+require_relative "../molecules/task_index_builder"
+require_relative "../molecules/task_association_resolver"
+require_relative "../molecules/pr_status_resolver"
+require_relative "../molecules/recent_branch_counter"
+require_relative "../molecules/worktree_table_formatter"
+require_relative "../molecules/worktree_footer_formatter"
+require_relative "worktree_probe_runner"
+
+module Ace
+  module Git
+    module Worktree
+      module Organisms
+        # Builds the `ace-git-worktree list` report end to end.
+        #
+        # Pipeline: inventory worktrees once -> build the `.ace-tasks/` index
+        # once -> fork-probe every worktree -> resolve task association ->
+        # classify activity from one clock snapshot -> resolve PRs (one bounded
+        # query) -> apply filters -> split active/inactive -> render.
+        #
+        # The report owns all ordering, clock reads, filtering, and rendering;
+        # probe children only report raw signals.
+        class WorktreeListReport
+          # @param lister [Molecules::WorktreeLister, nil]
+          # @param task_index_builder [Molecules::TaskIndexBuilder, nil]
+          # @param probe_runner [Organisms::WorktreeProbeRunner, nil] injectable
+          # @param pr_resolver [Molecules::PrStatusResolver, nil] injectable
+          # @param branch_counter [Molecules::RecentBranchCounter, nil] injectable
+          # @param clock [Proc, nil] injectable clock (`-> { Time }`) for tests
+          # @param project_root [String, nil]
+          # @param env [Hash]
+          # @param stdout [IO]
+          def initialize(lister: nil, task_index_builder: nil, probe_runner: nil, pr_resolver: nil,
+            branch_counter: nil, clock: nil, project_root: nil, env: ENV, stdout: $stdout)
+            @lister = lister || Molecules::WorktreeLister.new
+            @task_index_builder = task_index_builder
+            @probe_runner = probe_runner
+            @pr_resolver = pr_resolver
+            @branch_counter = branch_counter
+            @clock = clock
+            @project_root = project_root
+            @env = env
+            @stdout = stdout
+          end
+
+          # Run the report.
+          #
+          # @param options [Hash] parsed list options
+          # @return [Hash] `{success:, output:, worktrees:, statistics:}`
+          def run(options = {})
+            options = normalize_options(options)
+            inventory = @lister.inventory
+            unless inventory[:success]
+              return {success: false, error: inventory[:error], worktrees: [], statistics: {}}
+            end
+
+            raw_worktrees = inventory[:worktrees]
+            now = (@clock ? @clock.call : Time.now)
+            task_index = build_task_index
+            project_root = task_index.project_root || @project_root
+
+            probes = probe_worktrees(raw_worktrees, project_root)
+            enriched = enrich(raw_worktrees, probes, task_index, now, options)
+            selected = apply_filters(enriched, options)
+            active, inactive = selected.partition { |worktree| worktree.active_within_window }
+
+            statistics = build_statistics(selected, active, inactive, now, options, raw_worktrees)
+            output = render(selected, active, inactive, statistics, options)
+
+            {
+              success: true,
+              output: output,
+              worktrees: selected,
+              statistics: statistics
+            }
+          end
+
+          private
+
+          def normalize_options(options)
+            window = options[:active_within]
+            window = Atoms::DurationParser.parse(window) if window.is_a?(String)
+            window ||= Atoms::DurationParser.default
+            options.merge(
+              format: (options[:format] || :table).to_sym,
+              window_hours: window[:hours],
+              window_label: window[:label],
+              full: options[:full] ? true : false,
+              quiet: options[:quiet] ? true : false
+            )
+          end
+
+          def build_task_index
+            if @task_index_builder
+              @task_index_builder.build
+            else
+              Molecules::TaskIndexBuilder.new(project_root: @project_root).build
+            end
+          end
+
+          def probe_worktrees(raw_worktrees, project_root)
+            runner = @probe_runner || WorktreeProbeRunner.new(
+              project_root: project_root,
+              base_ref: raw_worktrees.first&.commit
+            )
+            runner.run(raw_worktrees)
+          end
+
+          def enrich(raw_worktrees, probes, task_index, now, options)
+            resolver = Molecules::TaskAssociationResolver.new(task_index: task_index)
+            pr_resolver = @pr_resolver || Molecules::PrStatusResolver.new
+
+            raw_worktrees.each_with_index.map do |worktree, index|
+              probe = probes[index]
+              associated = resolver.resolve(worktree, probe)
+              last_commit = last_commit_hash(probe, now)
+              uncommitted = uncommitted_hash(probe)
+              active = active_worktree?(worktree, probe, options[:window_hours], now)
+              pr = pr_resolver.resolve(associated, associated.task_id)
+
+              associated.with_enrichment(
+                last_commit: last_commit,
+                uncommitted: uncommitted,
+                active_within_window: active,
+                pr: pr,
+                probe_error: probe.nil?
+              )
+            end
+          end
+
+          def last_commit_hash(probe, now)
+            return nil if probe.nil? || probe[:head_sha].nil?
+
+            committed_at = Time.at(probe[:head_committer_epoch].to_i).utc
+            {
+              sha: probe[:head_sha],
+              age_hours: ((now - committed_at) / 3600.0).round(2),
+              committed_at: committed_at.iso8601,
+              subject: probe[:head_subject].to_s
+            }
+          end
+
+          def uncommitted_hash(probe)
+            return nil if probe.nil?
+
+            staged = probe[:staged].to_i
+            unstaged = probe[:unstaged].to_i
+            untracked = probe[:untracked].to_i
+            total = staged + unstaged + untracked
+            return nil unless total.positive?
+
+            {staged: staged, unstaged: unstaged, untracked: untracked, total: total}
+          end
+
+          # A worktree is active inside the window when its HEAD commit is in
+          # the window or it has uncommitted changes. Bare worktrees are never
+          # active; probe failures classify as inactive.
+          def active_worktree?(worktree, probe, window_hours, now)
+            return false if worktree.bare || probe.nil?
+
+            committed_at = probe[:head_committer_epoch]
+            recent_commit = committed_at && now.to_i - committed_at.to_i <= (window_hours * 3600).to_i
+            dirty = uncommitted_hash(probe)
+            recent_commit || !dirty.nil?
+          end
+
+          def apply_filters(worktrees, options)
+            filtered = Array(worktrees)
+
+            if options[:task_associated] == true
+              filtered = filtered.select { |worktree| worktree.task_associated? }
+            elsif options[:task_associated] == false
+              filtered = filtered.reject { |worktree| worktree.task_associated? }
+            end
+
+            if options[:usable] == true
+              filtered = filtered.select(&:usable?)
+            elsif options[:usable] == false
+              filtered = filtered.reject(&:usable?)
+            end
+
+            if options[:search] && !options[:search].to_s.empty?
+              pattern = Regexp.new(options[:search].to_s, Regexp::IGNORECASE)
+              filtered = filtered.select { |worktree| worktree.branch&.match?(pattern) }
+            end
+
+            filtered
+          end
+
+          def build_statistics(selected, active, inactive, now, options, raw_worktrees)
+            {
+              total: selected.length,
+              active: active.length,
+              inactive: inactive.length,
+              task_associated: selected.count(&:task_associated?),
+              usable: selected.count(&:usable?),
+              recent_branches: recent_branch_count(raw_worktrees, now, options),
+              window_hours: options[:window_hours],
+              window_label: options[:window_label]
+            }
+          end
+
+          # Branch-based count; worktree filters never change it, so checkout
+          # exclusions use the complete inventory.
+          def recent_branch_count(raw_worktrees, now, options)
+            if @branch_counter
+              @branch_counter.call(worktrees: raw_worktrees, window_hours: options[:window_hours], now: now)
+            else
+              Molecules::RecentBranchCounter.new(
+                worktrees: raw_worktrees, window_hours: options[:window_hours], now: now
+              ).count
+            end
+          end
+
+          # --- Rendering ---
+
+          def render(selected, active, inactive, statistics, options)
+            case options[:format]
+            when :json
+              render_json(selected)
+            when :simple
+              render_simple(selected)
+            else
+              render_table(active, inactive, statistics, options)
+            end
+          end
+
+          def render_json(worktrees)
+            JSON.generate(worktrees.map(&:to_h))
+          end
+
+          def render_simple(worktrees)
+            @lister.format_for_display(worktrees, :simple)
+          end
+
+          def render_table(active, inactive, statistics, options)
+            footer = Molecules::WorktreeFooterFormatter.new(
+              window_label: statistics[:window_label],
+              full: options[:full]
+            )
+            table = Molecules::WorktreeTableFormatter.new(env: @env, full: options[:full], stdout: @stdout)
+
+            lines = [footer.header(active_count: active.length, total_count: statistics[:total])]
+
+            if statistics[:total].zero?
+              return "No worktrees found."
+            end
+
+            rows = options[:full] ? (active + inactive) : active
+            if rows.empty?
+              lines << footer.no_active_message
+            else
+              lines.concat(table.render(rows))
+            end
+
+            unless options[:quiet]
+              lines << ""
+              lines.concat(footer.lines(
+                inactive: inactive.length,
+                task_associated: statistics[:task_associated],
+                usable: statistics[:usable],
+                recent_branches: statistics[:recent_branches]
+              ))
+            end
+
+            lines.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/worktree/organisms/worktree_manager.rb

@@ -270,24 +270,33 @@ module Ace
           #
           # @example
           #   result = manager.list_all
-          #   result = manager.list_all(format: :json, show_tasks: true)
+          #   result = manager.list_all(format: :json)
           #
-          # @option options [Symbol] :format Output format (:table, :json, :simple)
-          # @option options [Boolean] :show_tasks Include task associations
+          # Programmatic inventory for internal consumers (overseer, prune,
+          # switch/remove hints). The user-facing enriched table is rendered by
+          # {WorktreeListReport}, not here.
+          #
+          # @option options [Symbol] :format Optional formatting (:simple, :json)
           # @option options [Boolean] :task_associated Filter by task association
           # @option options [Boolean] :usable Filter by usability
           # @option options [String] :search Filter by search pattern
           def list_all(options = {})
-            task_filter_requested = !options[:task_associated].nil?
-
-            # Get worktrees
-            worktrees = if options[:show_tasks] || task_filter_requested
-              @worktree_lister.list_with_tasks
-            else
-              @worktree_lister.list_all
+            inventory = @worktree_lister.inventory
+            unless inventory[:success]
+              # Programmatic inventory keeps its historical tolerant contract:
+              # outside a repository it returns an empty list, not an error.
+              return {
+                success: true,
+                worktrees: [],
+                formatted_output: nil,
+                statistics: @worktree_lister.get_statistics([]),
+                count: 0,
+                warning: inventory[:error]
+              }
             end
 
-            # Apply filters
+            worktrees = inventory[:worktrees]
+
             if !options[:task_associated].nil? || !options[:usable].nil? || options[:search] || options[:task_id] || options[:pr_number]
               worktrees = @worktree_lister.filter(
                 worktrees,
@@ -299,13 +308,7 @@ module Ace
               )
             end
 
-            # Format output
-            formatted_output = @worktree_lister.format_for_display(
-              worktrees,
-              options[:format] || :table
-            )
-
-            # Get statistics
+            formatted_output = options[:format] && @worktree_lister.format_for_display(worktrees, options[:format])
             stats = @worktree_lister.get_statistics(worktrees)
 
             {
@@ -441,8 +444,7 @@ module Ace
           #   status = manager.get_status
           #   puts "Total worktrees: #{status[:statistics][:total]}"
           def get_status
-            # Get all worktrees with task associations
-            worktrees = @worktree_lister.list_with_tasks
+            worktrees = @worktree_lister.list_all
             stats = @worktree_lister.get_statistics
 
             # Get task worktree status

data/lib/ace/git/worktree/organisms/worktree_probe_runner.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+require "json"
+require "timeout"
+require_relative "../molecules/worktree_probe"
+
+module Ace
+  module Git
+    module Worktree
+      module Organisms
+        # Runs one read-only probe per worktree in isolated child processes.
+        #
+        # Contract:
+        # - one child per worktree, at most {MAX_LIVE_CHILDREN} alive at once;
+        # - each child has a hard {PROBE_TIMEOUT} second budget; a timed-out
+        #   child is killed together with its process group (no orphan `git`);
+        # - children never write repository state or the terminal, and results
+        #   are stored by input index so output order never depends on child
+        #   completion order;
+        # - a failed/timed-out probe yields nil (rendered as `?` by callers);
+        # - when `fork` is unavailable, probes run sequentially with the same
+        #   per-probe timeout and the same result contract.
+        class WorktreeProbeRunner
+          # Maximum number of live probe children.
+          MAX_LIVE_CHILDREN = 16
+
+          # Per-probe hard timeout in seconds (implementation constant).
+          PROBE_TIMEOUT = 5
+
+          # @param project_root [String, nil] project root for probe task signals
+          # @param base_ref [String, nil] primary worktree head for merge-base diffs
+          # @param probe [Proc, nil] injectable probe callable for tests
+          #   (receives a worktree, returns a Hash or nil); runs inside the child
+          # @param max_children [Integer] maximum live children
+          # @param timeout [Numeric] per-probe timeout in seconds
+          # @param fork_supported [Boolean, nil] force the sequential fallback
+          #   when false (nil = detect POSIX fork)
+          def initialize(project_root: nil, base_ref: nil, probe: nil,
+            max_children: MAX_LIVE_CHILDREN, timeout: PROBE_TIMEOUT, fork_supported: nil)
+            @project_root = project_root
+            @base_ref = base_ref
+            @probe = probe
+            @max_children = max_children
+            @timeout = timeout
+            @fork_supported = fork_supported.nil? ? fork_supported? : fork_supported
+          end
+
+          # Probe every worktree.
+          #
+          # @param worktrees [Array<Models::WorktreeInfo>] worktrees in display order
+          # @return [Array<Hash, nil>] payload per worktree, aligned with input
+          def run(worktrees)
+            list = Array(worktrees)
+            return [] if list.empty?
+            return sequential_all(list) unless @fork_supported
+
+            begin
+              fork_all(list)
+            rescue NotImplementedError
+              # fork exists but is unavailable in this environment (e.g. a
+              # restricted container): fall back to sequential probes.
+              @fork_supported = false
+              sequential_all(list)
+            end
+          end
+
+          private
+
+          def fork_supported?
+            Process.respond_to?(:fork) && !Gem.win_platform?
+          end
+
+          # --- Forked pool ---
+
+          def fork_all(worktrees)
+            results = Array.new(worktrees.length)
+            pending = worktrees.each_with_index.map { |worktree, index| [index, worktree] }
+            active = {}
+
+            begin
+              until pending.empty? && active.empty?
+                start_children(pending, active) while active.length < @max_children && !pending.empty?
+                break if active.empty?
+
+                wait_for_results(active, results)
+              end
+            ensure
+              terminate_all(active, results)
+            end
+
+            results
+          end
+
+          def start_children(pending, active)
+            index, worktree = pending.shift
+            pipe_read, pipe_write = IO.pipe
+            flush_standard_streams
+            pid = fork do
+              child_process(pipe_read, pipe_write, worktree)
+              exit!(0)
+            end
+
+            pipe_write.close
+            pipe_read.binmode
+            active[pid] = {
+              index: index,
+              pipe: pipe_read,
+              buffer: +"",
+              deadline: monotonic_now + @timeout
+            }
+          end
+
+          # Body executed in the forked child. Never raises to the parent and
+          # never writes to the inherited terminal.
+          def child_process(pipe_read, pipe_write, worktree)
+            pipe_read.close
+            begin
+              Process.setpgid(0, 0)
+            rescue StandardError
+              # Process group isolation is best effort on exotic platforms.
+            end
+            begin
+              STDOUT.reopen(File::NULL)
+              STDERR.reopen(File::NULL)
+            rescue StandardError
+              nil
+            end
+
+            payload = execute_probe(worktree)
+            pipe_write.write(JSON.generate(payload)) if payload
+          rescue Exception # rubocop:disable Lint/RescueException
+            nil
+          ensure
+            begin
+              pipe_write.close
+            rescue StandardError
+              nil
+            end
+          end
+
+          # Wait for at least one child to finish or for the nearest deadline.
+          def wait_for_results(active, results)
+            pipes = active.values.map { |job| job[:pipe] }
+            nearest_deadline = active.values.map { |job| job[:deadline] }.min
+            wait_seconds = [nearest_deadline - monotonic_now, 0].max
+
+            ready = IO.select(pipes, nil, nil, wait_seconds)
+
+            if ready.nil?
+              expire_timed_out(active, results)
+            else
+              ready.first.each { |pipe| drain_child_pipe(pipe, active, results) }
+              expire_timed_out(active, results)
+            end
+          end
+
+          # Read currently available bytes; on EOF parse and reap the child.
+          def drain_child_pipe(pipe, active, results)
+            job = active.values.find { |candidate| candidate[:pipe] == pipe }
+            return unless job
+
+            loop do
+              job[:buffer] << pipe.read_nonblock(65_536)
+            rescue IO::WaitReadable
+              return
+            rescue EOFError
+              finish_job(active, job, success: true, results: results)
+              return
+            end
+          end
+
+          def finish_job(active, job, success:, results:)
+            pid = active.key(job)
+            active.delete(pid) if pid
+
+            if success
+              results[job[:index]] = parse_payload(job[:buffer])
+            end
+
+            begin
+              job[:pipe].close unless job[:pipe].closed?
+            rescue StandardError
+              nil
+            end
+
+            reap(pid) if pid
+          end
+
+          def expire_timed_out(active, results)
+            now = monotonic_now
+            active.values.each do |job|
+              next if job[:deadline] > now
+
+              pid = active.key(job)
+              next unless pid
+
+              terminate(pid)
+              results[job[:index]] = nil
+              begin
+                job[:pipe].close unless job[:pipe].closed?
+              rescue StandardError
+                nil
+              end
+              active.delete(pid)
+            end
+          end
+
+          # Kill a child's process group (TERM, then KILL) and reap it.
+          def terminate(pid)
+            terminate_process_group(pid, "TERM")
+            # Give the child a brief chance to exit cleanly.
+            deadline = monotonic_now + 0.2
+            loop do
+              break if reap_nonblocking(pid)
+              break if monotonic_now > deadline
+
+              sleep 0.01
+            end
+            terminate_process_group(pid, "KILL")
+            reap(pid)
+          rescue Errno::ESRCH
+            nil
+          end
+
+          def terminate_all(active, results)
+            active.each do |pid, job|
+              terminate(pid)
+              results[job[:index]] ||= nil
+            end
+            active.clear
+          end
+
+          def terminate_process_group(pid, signal)
+            Process.kill("-#{signal}", pid)
+          rescue Errno::ESRCH
+            # Group already gone.
+            nil
+          rescue StandardError
+            begin
+              Process.kill(signal, pid)
+            rescue StandardError
+              nil
+            end
+          end
+
+          def reap(pid)
+            Process.wait(pid)
+          rescue Errno::ECHILD
+            nil
+          end
+
+          def reap_nonblocking(pid)
+            reaped = Process.wait(pid, Process::WNOHANG)
+            !reaped.nil?
+          rescue Errno::ECHILD
+            true
+          end
+
+          # --- Sequential fallback ---
+
+          def sequential_all(worktrees)
+            worktrees.map do |worktree|
+              Timeout.timeout(@timeout) { normalize_payload(execute_probe(worktree)) }
+            rescue Timeout::Error, StandardError
+              nil
+            end
+          end
+
+          # --- Probe execution ---
+
+          def execute_probe(worktree)
+            if @probe
+              @probe.call(worktree)
+            else
+              Molecules::WorktreeProbe.new(project_root: @project_root, base_ref: @base_ref).probe(worktree.path)
+            end
+          end
+
+          def parse_payload(buffer)
+            return nil if buffer.to_s.strip.empty?
+
+            normalize_payload(JSON.parse(buffer))
+          rescue JSON::ParserError
+            nil
+          end
+
+          def normalize_payload(payload)
+            return nil unless payload.is_a?(Hash)
+
+            deep_symbolize(payload)
+          end
+
+          def deep_symbolize(value)
+            case value
+            when Hash
+              value.each_with_object({}) { |(key, item), memo| memo[key.to_sym] = deep_symbolize(item) }
+            when Array
+              value.map { |item| deep_symbolize(item) }
+            else
+              value
+            end
+          end
+
+          # Flush buffered parent output before forking so children never
+          # inherit (and re-emit) unflushed terminal output.
+          def flush_standard_streams
+            $stdout.flush
+            $stderr.flush
+          rescue StandardError
+            nil
+          end
+
+          def monotonic_now
+            Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/worktree/version.rb

@@ -3,7 +3,7 @@
 module Ace
   module Git
     module Worktree
-      VERSION = "0.26.0"
+      VERSION = "0.27.0"
     end
   end
 end