ace-support-items 0.15.3

data/lib/ace/support/items/molecules/git_committer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Molecules
+        # Shells out to ace-git-commit for auto-committing after mutations.
+        # Pure CLI invocation — no gem dependency on ace-git-commit.
+        class GitCommitter
+          # @param paths [Array<String>] File/directory paths to commit
+          # @param intention [String] Commit intention for LLM message generation
+          # @return [Boolean] true if commit succeeded
+          def self.commit(paths:, intention:)
+            cmd = ["ace-git-commit"] + paths + ["-i", intention]
+            system(*cmd)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/molecules/item_sorter.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Molecules
+        # Sorts collections of items by a field with configurable direction.
+        # Nil values sort last regardless of direction.
+        class ItemSorter
+          # Sort items by a field
+          # @param items [Array] Items to sort
+          # @param field [String, Symbol] Field name to sort by
+          # @param direction [Symbol] :asc or :desc (default: :asc)
+          # @param value_accessor [Proc, nil] Custom accessor: ->(item, key) { value }
+          # @return [Array] Sorted items
+          def self.sort(items, field:, direction: :asc, value_accessor: nil)
+            return [] if items.nil? || items.empty?
+
+            accessor = value_accessor || method(:default_value_accessor)
+
+            multiplier = (direction == :desc) ? -1 : 1
+
+            items.sort do |a, b|
+              val_a = accessor.call(a, field.to_s)
+              val_b = accessor.call(b, field.to_s)
+
+              # Nil values sort last regardless of direction
+              if val_a.nil? && val_b.nil?
+                0
+              elsif val_a.nil?
+                1
+              elsif val_b.nil?
+                -1
+              else
+                (val_a <=> val_b || 0) * multiplier
+              end
+            end
+          end
+
+          # Default value accessor matching FilterApplier convention
+          private_class_method def self.default_value_accessor(item, key)
+            if item.respond_to?(:[])
+              val = begin
+                item[key.to_sym]
+              rescue
+                nil
+              end
+              return val unless val.nil?
+
+              val = begin
+                item[key.to_s]
+              rescue
+                nil
+              end
+              return val unless val.nil?
+            end
+
+            if item.respond_to?(key.to_sym)
+              return item.send(key.to_sym)
+            end
+
+            if item.respond_to?(:frontmatter) && item.frontmatter.is_a?(Hash)
+              val = item.frontmatter[key.to_s] || item.frontmatter[key.to_sym]
+              return val unless val.nil?
+            end
+
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/molecules/llm_slug_generator.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Support
+    module Items
+      module Molecules
+        # Generates hierarchical slugs using LLM with fallback to deterministic generation.
+        # Soft dependency on ace-llm — gracefully falls back if not available.
+        class LlmSlugGenerator
+          # Goal type keywords for consistent naming
+          GOAL_TYPES = %w[add enhance fix refactor].freeze
+
+          def initialize(debug: false)
+            @debug = debug
+          end
+
+          # Generate hierarchical slugs for a task
+          # @param title [String] Task title
+          # @param context [Hash] Additional context (project_name, type, etc.)
+          # @return [Hash] { folder_slug:, file_slug:, success:, source: } or fallback result
+          def generate_task_slugs(title, context = {})
+            llm_result = try_llm_task_generation(title, context)
+            return llm_result if llm_result[:success]
+
+            debug_log("LLM generation failed, using fallback")
+            fallback_task_generation(title, context)
+          end
+
+          # Generate hierarchical slugs for an idea
+          # @param description [String] Idea description/content
+          # @param context [Hash] Additional context
+          # @return [Hash] { folder_slug:, file_slug:, success:, source: } or fallback result
+          def generate_idea_slugs(description, context = {})
+            llm_result = try_llm_idea_generation(description, context)
+            return llm_result if llm_result[:success]
+
+            debug_log("LLM generation failed, using fallback")
+            fallback_idea_generation(description, context)
+          end
+
+          private
+
+          def load_slug_prompt
+            require "open3"
+
+            stdout, _stderr, status = Open3.capture3("ace-nav", "prompt://slug-generation", "--content")
+
+            if status.success?
+              debug_log("Successfully loaded slug-generation prompt via ace-nav")
+              stdout.strip
+            else
+              raise "Slug generation prompt not found via ace-nav"
+            end
+          rescue => e
+            debug_log("Error loading slug prompt: #{e.message}")
+            raise "Failed to load slug generation prompt: #{e.message}"
+          end
+
+          def try_llm_task_generation(title, context)
+            prompt = build_task_slug_prompt(title, context)
+            result = call_llm(prompt)
+            return {success: false} unless result[:success]
+
+            parsed = parse_llm_response(result[:text])
+            return {success: false} unless parsed
+
+            if valid_slugs?(parsed)
+              {
+                success: true,
+                folder_slug: parsed["folder_slug"],
+                file_slug: parsed["file_slug"],
+                source: :llm
+              }
+            else
+              debug_log("LLM returned invalid slug format: #{parsed.inspect}")
+              {success: false}
+            end
+          rescue => e
+            debug_log("LLM task generation error: #{e.message}")
+            {success: false}
+          end
+
+          def try_llm_idea_generation(description, context)
+            prompt = build_idea_slug_prompt(description, context)
+            result = call_llm(prompt)
+            return {success: false} unless result[:success]
+
+            parsed = parse_llm_response(result[:text])
+            return {success: false} unless parsed
+
+            if valid_slugs?(parsed)
+              {
+                success: true,
+                folder_slug: parsed["folder_slug"],
+                file_slug: parsed["file_slug"],
+                source: :llm
+              }
+            else
+              debug_log("LLM returned invalid slug format: #{parsed.inspect}")
+              {success: false}
+            end
+          rescue => e
+            debug_log("LLM idea generation error: #{e.message}")
+            {success: false}
+          end
+
+          def call_llm(prompt)
+            # Soft dependency on ace-llm
+            require "ace/llm/query_interface"
+            require "ace/llm/molecules/llm_alias_resolver"
+
+            debug_log("=== LLM PROMPT ===")
+            debug_log(prompt)
+            debug_log("=== END PROMPT ===")
+
+            response = Ace::LLM::QueryInterface.query(
+              "glite",
+              prompt,
+              temperature: 0.3,
+              max_tokens: 500,
+              debug: @debug
+            )
+
+            debug_log("=== LLM RESPONSE ===")
+            debug_log(response[:text])
+            debug_log("=== END RESPONSE ===")
+
+            {success: true, text: response[:text]}
+          rescue LoadError => e
+            debug_log("ace-llm not available: #{e.message}")
+            {success: false, error: e.message}
+          rescue => e
+            debug_log("LLM call failed: #{e.message}")
+            {success: false, error: e.message}
+          end
+
+          def parse_llm_response(text)
+            json_text = text.strip
+            json_text = json_text.gsub(/^```json\s*\n?/, "").gsub(/\n?```$/, "") if json_text.include?("```")
+
+            JSON.parse(json_text)
+          rescue JSON::ParserError => e
+            debug_log("Failed to parse LLM JSON response: #{e.message}")
+            nil
+          end
+
+          def build_task_slug_prompt(title, context)
+            prompt_template = load_slug_prompt
+
+            <<~PROMPT
+              #{prompt_template}
+
+              ---
+
+              ## Task Details
+
+              **Task Title**: #{title}
+              **Additional Context**: #{context.to_json}
+
+              Generate the hierarchical slugs for this task.
+            PROMPT
+          end
+
+          def build_idea_slug_prompt(description, context)
+            prompt_template = load_slug_prompt
+            desc_preview = description[0..1000]
+
+            <<~PROMPT
+              #{prompt_template}
+
+              ---
+
+              ## Idea Details
+
+              **Idea Description**: #{desc_preview}
+              **Additional Context**: #{context.to_json}
+
+              Generate the hierarchical slugs for this idea.
+            PROMPT
+          end
+
+          def valid_slugs?(parsed)
+            return false unless parsed.is_a?(Hash)
+            return false unless parsed["folder_slug"].is_a?(String)
+            return false unless parsed["file_slug"].is_a?(String)
+            return false if parsed["folder_slug"].empty?
+            return false if parsed["file_slug"].empty?
+
+            folder_valid = parsed["folder_slug"] =~ /^[a-z0-9]+(-[a-z0-9]+)*$/
+            file_valid = parsed["file_slug"] =~ /^[a-z0-9]+(-[a-z0-9]+)*$/
+
+            folder_valid && file_valid
+          end
+
+          def fallback_task_generation(title, _context)
+            slug = sanitize_to_slug(title)
+            parts = slug.split("-")
+            folder_parts = parts.take(3)
+            file_parts = parts.drop(3)
+
+            folder_slug = folder_parts.join("-")
+            file_slug = file_parts.any? ? file_parts.join("-") : folder_slug
+
+            {
+              success: true,
+              folder_slug: folder_slug,
+              file_slug: file_slug,
+              source: :fallback
+            }
+          end
+
+          def fallback_idea_generation(description, _context)
+            title = description.split("\n").first || description
+            title = title[0..49] if title.length > 50
+            file_slug = sanitize_to_slug(title)
+
+            area = extract_area_from_content(description)
+            goal_type = extract_goal_type_from_content(description)
+            folder_slug = [area, goal_type].compact.join("-")
+            folder_slug = file_slug if folder_slug.empty?
+
+            {
+              success: true,
+              folder_slug: folder_slug,
+              file_slug: file_slug,
+              source: :fallback
+            }
+          end
+
+          def sanitize_to_slug(text)
+            text.to_s.downcase
+              .gsub(/[^\w\s-]/, "")
+              .gsub(/[\s_]+/, "-").squeeze("-")
+              .gsub(/^-|-$/, "")
+              .strip
+          end
+
+          def extract_area_from_content(content)
+            content_lower = content.downcase
+            areas = %w[taskflow search docs git llm nav review lint test]
+            areas.find { |area| content_lower.include?(area) }
+          end
+
+          def extract_goal_type_from_content(content)
+            content_lower = content.downcase
+
+            return "add" if /\b(add|create|implement|new)\b/.match?(content_lower)
+            return "enhance" if /\b(enhance|improve|update|upgrade)\b/.match?(content_lower)
+            return "fix" if /\b(fix|repair|resolve|correct)\b/.match?(content_lower)
+            return "refactor" if /\b(refactor|restructure|reorganize)\b/.match?(content_lower)
+
+            "enhance"
+          end
+
+          def debug_log(message)
+            warn "[LlmSlugGenerator] #{message}" if @debug
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/molecules/shortcut_resolver.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Molecules
+        # Resolves shortcut references to item ScanResult objects.
+        #
+        # Shortcuts are the last N characters of an item ID.
+        # For ideas (6-char IDs): "8ppq7w" => shortcut "q7w"
+        # For tasks (9-char formatted IDs): "8pp.t.q7w" => shortcut "q7w"
+        # Full IDs are also accepted directly.
+        #
+        # Warns (via callback or STDERR) when multiple matches are found.
+        class ShortcutResolver
+          # @param scan_results [Array<ScanResult>] Scan results to resolve against
+          # @param full_id_length [Integer] Length of a full ID (6 for raw b36ts, 9 for type-marked)
+          def initialize(scan_results, full_id_length: 6)
+            @scan_results = scan_results
+            @full_id_length = full_id_length
+          end
+
+          # Resolve a reference to a single ScanResult
+          # @param ref [String] Full ID or suffix shortcut
+          # @param on_ambiguity [Proc, nil] Called with array of matches on ambiguity
+          # @return [ScanResult, nil] The resolved result, or nil if not found
+          def resolve(ref, on_ambiguity: nil)
+            return nil if ref.nil? || ref.empty?
+
+            ref = ref.strip.downcase
+
+            if ref.length == @full_id_length
+              # Full ID match
+              exact = @scan_results.find { |r| r.id == ref }
+              return exact
+            end
+
+            # Suffix match (last N characters)
+            matches = @scan_results.select { |r| r.id.end_with?(ref) }
+
+            if matches.empty?
+              nil
+            elsif matches.size == 1
+              matches.first
+            else
+              # Ambiguity: multiple matches
+              if on_ambiguity
+                on_ambiguity.call(matches)
+              else
+                warn "Warning: Ambiguous shortcut '#{ref}' matches #{matches.size} items: " \
+                     "#{matches.map(&:id).join(", ")}. Using most recent."
+              end
+              # Return most recent (last by sorted ID = chronologically latest)
+              matches.last
+            end
+          end
+
+          # Check if a reference would be ambiguous
+          # @param ref [String] Reference to check
+          # @return [Boolean] True if multiple matches exist
+          def ambiguous?(ref)
+            return false if ref.nil? || ref.length == @full_id_length
+
+            ref = ref.strip.downcase
+            matches = @scan_results.select { |r| r.id.end_with?(ref) }
+            matches.size > 1
+          end
+
+          # Return all matches for a reference (useful for listing ambiguous matches)
+          # @param ref [String] Reference to resolve
+          # @return [Array<ScanResult>] All matching results
+          def all_matches(ref)
+            return [] if ref.nil? || ref.empty?
+
+            ref = ref.strip.downcase
+
+            if ref.length == @full_id_length
+              @scan_results.select { |r| r.id == ref }
+            else
+              @scan_results.select { |r| r.id.end_with?(ref) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/molecules/smart_sorter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Molecules
+        # Sorts items using pinned-first + auto-sort logic.
+        # Pinned items (those with a position value) sort first by position ascending.
+        # Unpinned items sort second by computed score descending.
+        class SmartSorter
+          # @param items [Array] Items to sort
+          # @param score_fn [Proc] ->(item) { Float } computes auto-sort score
+          # @param pin_accessor [Proc] ->(item) { String|nil } reads position field
+          # @return [Array] Pinned items (by position asc) + unpinned items (by score desc)
+          def self.sort(items, score_fn:, pin_accessor:)
+            return [] if items.nil? || items.empty?
+
+            pinned = []
+            unpinned = []
+
+            items.each do |item|
+              pos = pin_accessor.call(item)
+              if pos && !pos.to_s.empty?
+                pinned << item
+              else
+                unpinned << item
+              end
+            end
+
+            sorted_pinned = pinned.sort_by { |item| pin_accessor.call(item).to_s }
+            sorted_unpinned = unpinned.sort_by { |item| -score_fn.call(item) }
+
+            sorted_pinned + sorted_unpinned
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/molecules/status_categorizer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Molecules
+        # Categorizes items into "up next" and "recently done" buckets
+        # for status overview displays. Generic — works with any item
+        # responding to :status, :file_path, :special_folder, :id.
+        class StatusCategorizer
+          # @param items [Array] All loaded items
+          # @param up_next_limit [Integer] Max up-next items (0 = disable section)
+          # @param recently_done_limit [Integer] Max recently-done items (0 = disable section)
+          # @param pending_statuses [Array<String>] Statuses considered "up next"
+          # @param done_statuses [Array<String>] Statuses considered "recently done"
+          # @return [Hash] { up_next: [...], recently_done: [{ item:, completed_at: }] }
+          # @param up_next_sorter [Proc, nil] Custom sorter for up-next items.
+          #   Receives array of items, returns sorted array. Default: sort by id.
+          def self.categorize(items, up_next_limit:, recently_done_limit:,
+            pending_statuses: ["pending"], done_statuses: ["done"],
+            up_next_sorter: nil)
+            up_next = if up_next_limit > 0
+              candidates = items
+                .select { |i| pending_statuses.include?(i.status) && i.special_folder.nil? }
+              sorted = if up_next_sorter
+                up_next_sorter.call(candidates)
+              else
+                candidates.sort_by(&:id)
+              end
+              sorted.first(up_next_limit)
+            else
+              []
+            end
+
+            recently_done = if recently_done_limit > 0
+              items
+                .select { |i| done_statuses.include?(i.status) }
+                .map { |i| {item: i, completed_at: safe_mtime(i.file_path)} }
+                .sort_by { |entry| -(entry[:completed_at]&.to_f || 0) }
+                .first(recently_done_limit)
+            else
+              []
+            end
+
+            {up_next: up_next, recently_done: recently_done}
+          end
+
+          # Safely read file mtime, returning nil if the file is missing.
+          def self.safe_mtime(path)
+            File.mtime(path)
+          rescue Errno::ENOENT, TypeError
+            nil
+          end
+
+          private_class_method :safe_mtime
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      VERSION = "0.15.3"
+    end
+  end
+end

data/lib/ace/support/items.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "items/version"
+
+# Atoms
+require_relative "items/atoms/ansi_colors"
+require_relative "items/atoms/slug_sanitizer"
+require_relative "items/atoms/field_argument_parser"
+require_relative "items/atoms/special_folder_detector"
+require_relative "items/atoms/folder_completion_detector"
+require_relative "items/atoms/frontmatter_parser"
+require_relative "items/atoms/frontmatter_serializer"
+require_relative "items/atoms/filter_parser"
+require_relative "items/atoms/title_extractor"
+require_relative "items/atoms/date_partition_path"
+require_relative "items/atoms/item_id_formatter"
+require_relative "items/atoms/item_id_parser"
+require_relative "items/atoms/item_statistics"
+require_relative "items/atoms/stats_line_formatter"
+require_relative "items/atoms/relative_time_formatter"
+require_relative "items/atoms/sort_score_calculator"
+require_relative "items/atoms/position_generator"
+
+# Models
+require_relative "items/models/scan_result"
+require_relative "items/models/loaded_document"
+require_relative "items/models/item_id"
+
+# Molecules
+require_relative "items/molecules/directory_scanner"
+require_relative "items/molecules/shortcut_resolver"
+require_relative "items/molecules/document_loader"
+require_relative "items/molecules/filter_applier"
+require_relative "items/molecules/item_sorter"
+require_relative "items/molecules/base_formatter"
+require_relative "items/molecules/field_updater"
+require_relative "items/molecules/folder_mover"
+require_relative "items/molecules/llm_slug_generator"
+require_relative "items/molecules/status_categorizer"
+require_relative "items/molecules/git_committer"
+require_relative "items/molecules/smart_sorter"
+
+module Ace
+  module Support
+    # Items provides shared infrastructure for item management (tasks, ideas, etc.)
+    # across ace-* gems. Built on b36ts-based IDs and folder conventions.
+    module Items
+    end
+  end
+end