ace-support-items 0.15.3

data/lib/ace/support/items/models/item_id.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Models
+        # Value object representing a parsed item ID with type marker.
+        #
+        # A 6-char b36ts ID (e.g., "8ppq7w") can be split into a type-marked format:
+        #   prefix (3 chars) + type_marker (e.g., ".t.") + suffix (3 chars)
+        #   => "8pp.t.q7w"
+        #
+        # Subtasks append a single char: "8pp.t.q7w.a"
+        ItemId = Struct.new(
+          :raw_b36ts,     # Original 6-char b36ts ID (e.g., "8ppq7w")
+          :prefix,        # First 3 chars (e.g., "8pp")
+          :type_marker,   # Type marker string (e.g., "t", "i")
+          :suffix,        # Last 3 chars (e.g., "q7w")
+          :subtask_char,  # Optional single subtask character (e.g., "a"), nil if none
+          keyword_init: true
+        ) do
+          # Full formatted ID with type marker (e.g., "8pp.t.q7w")
+          # @return [String]
+          def formatted_id
+            base = "#{prefix}.#{type_marker}.#{suffix}"
+            subtask_char ? "#{base}.#{subtask_char}" : base
+          end
+
+          # Full formatted ID (alias for formatted_id)
+          # @return [String]
+          def full_id
+            formatted_id
+          end
+
+          # Whether this represents a subtask
+          # @return [Boolean]
+          def subtask?
+            !subtask_char.nil?
+          end
+
+          def to_h
+            {
+              raw_b36ts: raw_b36ts,
+              prefix: prefix,
+              type_marker: type_marker,
+              suffix: suffix,
+              subtask_char: subtask_char,
+              formatted_id: formatted_id
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/models/loaded_document.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Models
+        # Value object representing a loaded document with parsed frontmatter,
+        # body content, title, and file metadata.
+        LoadedDocument = Struct.new(
+          :frontmatter,    # Hash - parsed YAML frontmatter
+          :body,           # String - document body after frontmatter
+          :title,          # String - from frontmatter["title"], H1 heading, or folder name
+          :file_path,      # String - path to spec file
+          :dir_path,       # String - path to item directory
+          :attachments,    # Array<String> - non-spec filenames in directory
+          keyword_init: true
+        ) do
+          # Access frontmatter values by key (string or symbol)
+          # @param key [String, Symbol] Frontmatter key
+          # @return [Object, nil] Value or nil
+          def [](key)
+            frontmatter[key.to_s] || frontmatter[key.to_sym]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/models/scan_result.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Models
+        # Value object representing a scan result for an item directory
+        # Holds path information, raw ID, and folder metadata
+        ScanResult = Struct.new(
+          :id,           # Raw 6-char b36ts ID (e.g., "8ppq7w")
+          :slug,         # Folder slug without ID (e.g., "dark-mode-support")
+          :folder_name,  # Full folder name (e.g., "8ppq7w-dark-mode-support")
+          :dir_path,     # Full path to item directory
+          :file_path,    # Full path to item spec file
+          :special_folder, # Special folder name (e.g., "_maybe", nil if none)
+          keyword_init: true
+        ) do
+          def to_h
+            {
+              id: id,
+              slug: slug,
+              folder_name: folder_name,
+              dir_path: dir_path,
+              file_path: file_path,
+              special_folder: special_folder
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Molecules
+        # Minimal default formatter for item display.
+        # Gems can override with their own formatter for richer output.
+        class BaseFormatter
+          # Format a single item for display
+          # @param item [Object] Item with id/title (LoadedDocument, ScanResult, etc.)
+          # @param scan_result [ScanResult, nil] Optional scan result for ID fallback
+          # @return [String] Formatted line
+          def self.format_item(item, scan_result: nil)
+            id = resolve_id(item, scan_result)
+            title = resolve_title(item)
+
+            "#{id} #{title}"
+          end
+
+          # Format a list of items
+          # @param items [Array] Items to format
+          # @return [String] Formatted list
+          def self.format_list(items)
+            return "No items found." if items.nil? || items.empty?
+
+            items.map { |item| format_item(item) }.join("\n")
+          end
+
+          private_class_method def self.resolve_id(item, scan_result)
+            return scan_result.id if scan_result&.id
+            return item.frontmatter["id"] if item.respond_to?(:frontmatter) && item.frontmatter.is_a?(Hash)
+            return item[:id] || item["id"] if item.respond_to?(:[])
+            return item.id if item.respond_to?(:id)
+            "?"
+          rescue
+            "?"
+          end
+
+          private_class_method def self.resolve_title(item)
+            return item.title if item.respond_to?(:title) && item.title
+            return item[:title] || item["title"] if item.respond_to?(:[])
+            "Untitled"
+          rescue
+            "Untitled"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "../models/scan_result"
+require_relative "../atoms/special_folder_detector"
+
+module Ace
+  module Support
+    module Items
+      module Molecules
+        # Recursively scans an item root directory for item spec files.
+        # Returns ScanResult objects with folder and ID metadata.
+        #
+        # Item directories follow the convention: {id}-{slug}/
+        # Item spec files match a configurable glob pattern within those directories.
+        #
+        # The id_extractor proc allows customizing how IDs are extracted from folder names.
+        # Default: matches 6-char b36ts IDs (e.g., "8ppq7w-dark-mode")
+        # Custom: can match type-marked IDs (e.g., "8pp.t.q7w-fix-login")
+        class DirectoryScanner
+          # Default extractor for 6-char raw b36ts IDs
+          DEFAULT_ID_EXTRACTOR = ->(folder_name) {
+            match = folder_name.match(/^([0-9a-z]{6})-?(.*)$/)
+            return nil unless match
+
+            id = match[1]
+            slug = match[2].empty? ? folder_name : match[2]
+            [id, slug]
+          }
+
+          # @param root_dir [String] Root directory to scan
+          # @param file_pattern [String] Glob pattern for spec files (e.g., "*.idea.s.md")
+          # @param id_extractor [Proc, nil] Custom proc to extract [id, slug] from folder name.
+          #   Receives folder_name string, returns [id, slug] array or nil if no match.
+          def initialize(root_dir, file_pattern:, id_extractor: nil)
+            @root_dir = root_dir
+            @file_pattern = file_pattern
+            @id_extractor = id_extractor || DEFAULT_ID_EXTRACTOR
+          end
+
+          # Scan root directory recursively for items
+          # @return [Array<ScanResult>] List of scan results, sorted by ID (chronological)
+          def scan
+            return [] unless Dir.exist?(@root_dir)
+
+            results = []
+            scan_directory(@root_dir, results)
+            results.sort_by(&:id)
+          end
+
+          private
+
+          def scan_directory(dir, results)
+            Dir.entries(dir).sort.each do |entry|
+              next if entry.start_with?(".")
+
+              full_path = File.join(dir, entry)
+              next unless File.directory?(full_path)
+
+              # Check if this directory contains spec files
+              spec_files = Dir.glob(File.join(full_path, @file_pattern))
+              if spec_files.any?
+                result = build_result(full_path, spec_files.first)
+                if result
+                  results << result
+                else
+                  # Folder has spec files but isn't an item (e.g., _maybe with orphan files) — recurse
+                  scan_directory(full_path, results)
+                end
+              else
+                # Recurse into subdirectory (for special folders like _maybe/)
+                scan_directory(full_path, results)
+              end
+            end
+          end
+
+          def build_result(dir_path, file_path)
+            folder_name = File.basename(dir_path)
+
+            # Extract ID from folder name: "8ppq7w-dark-mode" => id="8ppq7w", slug="dark-mode"
+            id, slug = extract_id_and_slug(folder_name)
+            return nil unless id
+
+            # Detect special folder (e.g., _maybe, _archive)
+            special_folder = Atoms::SpecialFolderDetector.detect_in_path(dir_path, root: @root_dir)
+
+            Models::ScanResult.new(
+              id: id,
+              slug: slug,
+              folder_name: folder_name,
+              dir_path: dir_path,
+              file_path: file_path,
+              special_folder: special_folder
+            )
+          end
+
+          # Extract ID and slug from folder name using the configured extractor
+          # @return [Array<String, String>, nil] [id, slug] or nil if pattern doesn't match
+          def extract_id_and_slug(folder_name)
+            @id_extractor.call(folder_name)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "../atoms/frontmatter_parser"
+require_relative "../atoms/title_extractor"
+require_relative "../models/loaded_document"
+
+module Ace
+  module Support
+    module Items
+      module Molecules
+        # Loads a document from an item directory: finds the spec file,
+        # parses frontmatter/body, extracts title, and enumerates attachments.
+        class DocumentLoader
+          # Load a document from a directory path
+          # @param dir_path [String] Path to item directory
+          # @param file_pattern [String] Glob pattern for spec files (e.g., "*.idea.s.md")
+          # @param spec_extension [String] Extension to exclude from attachments (e.g., ".idea.s.md")
+          # @return [LoadedDocument, nil] Loaded document or nil if not found
+          def self.load(dir_path, file_pattern:, spec_extension:)
+            return nil unless Dir.exist?(dir_path)
+
+            spec_file = Dir.glob(File.join(dir_path, file_pattern)).first
+            return nil unless spec_file
+
+            build_document(dir_path, spec_file, spec_extension)
+          end
+
+          # Load a document from a ScanResult
+          # @param scan_result [ScanResult] Scan result with dir_path and file_path
+          # @param file_pattern [String] Glob pattern (unused when file_path present, kept for API consistency)
+          # @param spec_extension [String] Extension to exclude from attachments
+          # @return [LoadedDocument, nil] Loaded document or nil
+          def self.from_scan_result(scan_result, spec_extension:, file_pattern: nil)
+            return nil unless scan_result&.dir_path && Dir.exist?(scan_result.dir_path)
+
+            spec_file = scan_result.file_path || Dir.glob(File.join(scan_result.dir_path, file_pattern)).first
+            return nil unless spec_file
+
+            build_document(scan_result.dir_path, spec_file, spec_extension)
+          end
+
+          # Build a LoadedDocument from directory and spec file
+          private_class_method def self.build_document(dir_path, spec_file, spec_extension)
+            content = File.read(spec_file)
+            frontmatter, body = Atoms::FrontmatterParser.parse(content)
+
+            folder_name = File.basename(dir_path)
+            title = frontmatter["title"] ||
+              Atoms::TitleExtractor.extract(body) ||
+              folder_name
+
+            attachments = enumerate_attachments(dir_path, spec_extension)
+
+            Models::LoadedDocument.new(
+              frontmatter: frontmatter,
+              body: body,
+              title: title,
+              file_path: spec_file,
+              dir_path: dir_path,
+              attachments: attachments
+            )
+          end
+
+          # List non-spec files in directory (excluding hidden files)
+          private_class_method def self.enumerate_attachments(dir_path, spec_extension)
+            Dir.glob(File.join(dir_path, "*"))
+              .select { |f| File.file?(f) }
+              .reject { |f| f.end_with?(spec_extension) }
+              .map { |f| File.basename(f) }
+              .reject { |name| name.start_with?(".") }
+              .sort
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../atoms/frontmatter_parser"
+require_relative "../atoms/frontmatter_serializer"
+
+module Ace
+  module Support
+    module Items
+      module Molecules
+        # Orchestrates --set/--add/--remove field updates on frontmatter files.
+        # Handles nested dot-key paths for --set operations.
+        # Writes atomically using temp file + rename.
+        class FieldUpdater
+          # Update frontmatter fields in a spec file.
+          #
+          # @param file_path [String] Path to the spec file
+          # @param set [Hash] Fields to set (key => value). Supports dot-notation for nested keys.
+          # @param add [Hash] Fields to append to arrays (key => value or array of values).
+          # @param remove [Hash] Fields to remove from arrays (key => value or array of values).
+          # @return [Hash] Updated frontmatter hash
+          def self.update(file_path, set: {}, add: {}, remove: {})
+            content = File.read(file_path)
+            frontmatter, body = Atoms::FrontmatterParser.parse(content)
+            # Strip leading newline from body so rebuild doesn't double-space
+            body = body.sub(/\A\n/, "")
+
+            apply_set(frontmatter, set)
+            apply_add(frontmatter, add)
+            apply_remove(frontmatter, remove)
+
+            new_content = Atoms::FrontmatterSerializer.rebuild(frontmatter, body)
+            atomic_write(file_path, new_content)
+
+            frontmatter
+          end
+
+          # Apply --set operations (supports nested dot-key paths).
+          # @param frontmatter [Hash] Frontmatter hash (mutated in place)
+          # @param set [Hash] Key-value pairs to set
+          def self.apply_set(frontmatter, set)
+            return if set.nil? || set.empty?
+
+            set.each do |key, value|
+              key_str = key.to_s
+              if key_str.include?(".")
+                apply_nested_set(frontmatter, key_str, value)
+              else
+                frontmatter[key_str] = value
+              end
+            end
+          end
+
+          # Apply --add operations (append to arrays).
+          # If the existing value is a scalar, coerces it to an array first.
+          # @param frontmatter [Hash] Frontmatter hash (mutated in place)
+          # @param add [Hash] Key-value pairs to add
+          def self.apply_add(frontmatter, add)
+            return if add.nil? || add.empty?
+
+            add.each do |key, value|
+              key_str = key.to_s
+              current = frontmatter[key_str]
+              values_to_add = Array(value)
+
+              frontmatter[key_str] = (Array(current) + values_to_add).uniq
+            end
+          end
+
+          # Apply --remove operations (remove from arrays).
+          # @param frontmatter [Hash] Frontmatter hash (mutated in place)
+          # @param remove [Hash] Key-value pairs to remove
+          # @raise [ArgumentError] If target field is not an array
+          def self.apply_remove(frontmatter, remove)
+            return if remove.nil? || remove.empty?
+
+            remove.each do |key, value|
+              key_str = key.to_s
+              current = frontmatter[key_str]
+              next if current.nil?
+
+              unless current.is_a?(Array)
+                raise ArgumentError, "Cannot remove from non-array field '#{key_str}' (is #{current.class})"
+              end
+
+              values_to_remove = Array(value)
+              frontmatter[key_str] = current - values_to_remove
+            end
+          end
+
+          # Navigate nested dot-key path and set value.
+          # "update.last-updated" => frontmatter["update"]["last-updated"] = value
+          def self.apply_nested_set(frontmatter, key_path, value)
+            parts = key_path.split(".")
+            target = frontmatter
+
+            parts[0...-1].each do |part|
+              target[part] ||= {}
+              target = target[part]
+            end
+
+            target[parts.last] = value
+          end
+
+          # Write content atomically using temp file + rename.
+          def self.atomic_write(file_path, content)
+            tmp_path = "#{file_path}.tmp.#{Process.pid}"
+            File.write(tmp_path, content)
+            File.rename(tmp_path, file_path)
+          rescue
+            File.unlink(tmp_path) if tmp_path && File.exist?(tmp_path)
+            raise
+          end
+
+          private_class_method :apply_nested_set, :atomic_write
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Molecules
+        # Applies parsed filter specifications to collections of items.
+        # Supports AND/OR operations, negation, array matching, and
+        # a configurable value accessor for any object type.
+        class FilterApplier
+          # Apply filter specifications to items
+          # @param items [Array] Items to filter
+          # @param filter_specs [Array<Hash>] Filter specifications from FilterParser
+          # @param value_accessor [Proc, nil] Custom accessor: ->(item, key) { value }
+          # @return [Array] Filtered items
+          def self.apply(items, filter_specs, value_accessor: nil)
+            return items if filter_specs.nil? || filter_specs.empty?
+            return [] if items.nil? || items.empty?
+
+            accessor = value_accessor || method(:default_value_accessor)
+
+            items.select do |item|
+              filter_specs.all? { |spec| matches_filter?(item, spec, accessor) }
+            end
+          end
+
+          # Check if item matches a single filter specification
+          private_class_method def self.matches_filter?(item, filter_spec, accessor)
+            key = filter_spec[:key]
+            values = filter_spec[:values]
+            negated = filter_spec[:negated]
+            or_mode = filter_spec[:or_mode]
+
+            item_value = accessor.call(item, key)
+
+            match = if item_value.is_a?(Array)
+              matches_array?(item_value, values, or_mode)
+            else
+              matches_value?(item_value, values, or_mode)
+            end
+
+            negated ? !match : match
+          end
+
+          # Check if array contains any of the filter values
+          private_class_method def self.matches_array?(item_array, filter_values, or_mode)
+            array_strings = item_array.map { |v| normalize_value(v) }
+
+            if or_mode
+              filter_values.any? { |fv| array_strings.include?(normalize_value(fv)) }
+            else
+              array_strings.include?(normalize_value(filter_values.first))
+            end
+          end
+
+          # Check if value matches any of the filter values
+          private_class_method def self.matches_value?(item_value, filter_values, or_mode)
+            normalized_item = normalize_value(item_value)
+
+            if or_mode
+              filter_values.any? { |fv| normalized_item == normalize_value(fv) }
+            else
+              normalized_item == normalize_value(filter_values.first)
+            end
+          end
+
+          # Normalize value for comparison (case-insensitive, trimmed)
+          private_class_method def self.normalize_value(value)
+            return "" if value.nil?
+            value.to_s.strip.downcase
+          end
+
+          # Default value accessor: tries hash keys, methods, frontmatter, metadata
+          private_class_method def self.default_value_accessor(item, key)
+            # Hash-like access (symbol then string)
+            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
+
+            # Method access
+            if item.respond_to?(key.to_sym)
+              return item.send(key.to_sym)
+            end
+
+            # Frontmatter access
+            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
+
+            # Metadata access (for taskflow-style items)
+            if item.respond_to?(:metadata) && item.metadata.is_a?(Hash)
+              return item.metadata[key.to_s] || item.metadata[key.to_sym]
+            end
+
+            # Nested metadata in hash
+            if item.respond_to?(:dig)
+              item.dig(:metadata, key) || item.dig(:metadata, key.to_sym)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../atoms/special_folder_detector"
+require_relative "../atoms/date_partition_path"
+
+module Ace
+  module Support
+    module Items
+      module Molecules
+        # Generic folder mover for item directories.
+        # Handles special folder name normalization, archive date partitioning,
+        # and cross-filesystem atomic moves.
+        class FolderMover
+          # @param root_dir [String] Root directory for items
+          def initialize(root_dir)
+            @root_dir = root_dir
+          end
+
+          # Move an item folder to a target location.
+          #
+          # @param item [#path] Item with a path attribute (directory to move)
+          # @param to [String] Target folder name (short or full, e.g., "maybe", "_archive")
+          # @param date [Time, nil] Date used to compute archive partition (default: Time.now)
+          # @return [String] New path of the item directory
+          def move(item, to:, date: nil)
+            if Atoms::SpecialFolderDetector.virtual_filter?(to)
+              raise ArgumentError, "Cannot move to virtual filter '#{to}' — it is not a physical folder"
+            end
+
+            normalized = Atoms::SpecialFolderDetector.normalize(to)
+
+            target_parent = if normalized == "_archive"
+              partition = Atoms::DatePartitionPath.compute(date || Time.now)
+              File.expand_path(File.join(@root_dir, normalized, partition))
+            else
+              File.expand_path(File.join(@root_dir, normalized))
+            end
+
+            validate_path_traversal!(target_parent)
+            FileUtils.mkdir_p(target_parent)
+
+            folder_name = File.basename(item.path)
+            new_path = File.join(target_parent, folder_name)
+
+            # Same-location no-op check
+            return item.path if File.expand_path(item.path) == File.expand_path(new_path)
+
+            atomic_move(item.path, new_path)
+          end
+
+          # Move an item back to root (remove from special folder).
+          #
+          # @param item [#path] Item with a path attribute
+          # @return [String] New path of the item directory
+          def move_to_root(item)
+            folder_name = File.basename(item.path)
+            new_path = File.join(@root_dir, folder_name)
+
+            # Same-location no-op check
+            return item.path if File.expand_path(item.path) == File.expand_path(new_path)
+
+            atomic_move(item.path, new_path)
+          end
+
+          private
+
+          def validate_path_traversal!(target_parent)
+            root_real = File.expand_path(@root_dir)
+            unless target_parent.start_with?(root_real + File::SEPARATOR)
+              raise ArgumentError, "Path traversal detected in target folder"
+            end
+          end
+
+          # Move src to dest atomically, handling cross-device moves.
+          def atomic_move(src, dest)
+            raise ArgumentError, "Destination already exists: #{dest}" if File.exist?(dest)
+
+            begin
+              File.rename(src, dest)
+            rescue Errno::EXDEV
+              FileUtils.cp_r(src, dest)
+              FileUtils.rm_rf(src)
+            end
+            dest
+          end
+        end
+      end
+    end
+  end
+end