ace-support-items 0.15.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b2aa17665c5e6748f75a2f65366029ebeb0079edb2f0cd16e14a98bba9f5966e
+  data.tar.gz: 6eac1db061422fb21330c7e7327e25cd6a98d06ad6617a8ee686857a27e6764a
+SHA512:
+  metadata.gz: fb9243adbcf8dea7becdee9d395c9cbba517b53f2c157567b4acfde17b9b75c37bd62f02ae5267ed060c328927d348fd0231946de7f621d714bd0661564b40cf
+  data.tar.gz: 00b1a7f87bc1981a55d00e9b77def6550133b6252f4eab37f01b00b66ff18853aca0c0ba761746ec78feff2563c5a34bc7907fe121b018f1ddb04088901f7fe0

data/CHANGELOG.md

@@ -0,0 +1,174 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.15.3] - 2026-03-22
+
+### Technical
+- Updated README dependency example to use the current `~> 0.15` version constraint.
+
+## [0.15.2] - 2026-03-22
+
+### Technical
+- Refreshed README structure with consistent tagline, installation, basic usage, and ACE project footer
+
+## [0.15.1] - 2026-03-04
+
+### Fixed
+- Removed `Ace::Support::Items::Atoms::TmpWorkspace` and reverted to standard system temporary artifact handling.
+
+## [0.15.0] - 2026-03-04
+
+### Added
+- New `Ace::Support::Items::Atoms::TmpWorkspace` atom for creating project-local, B36TS time-partitioned workspace directories under `.ace-local/tmp/`
+
+## [0.14.1] - 2026-03-03
+
+### Fixed
+- `SpecialFolderDetector.normalize`: prefix-based expansion so any folder name is auto-expanded (e.g., `backlog` → `_backlog`), fixing `--in backlog` returning no results
+- `StatsLineFormatter.folder_label`: uses `SpecialFolderDetector.short_name` instead of hardcoded `delete_prefix("_")`
+
+### Changed
+- `SpecialFolderDetector`: replaced hardcoded `SPECIAL_FOLDERS` and `SHORT_ALIASES` constants with `DEFAULT_PREFIX = "_"` for deterministic two-way conversion
+- `SpecialFolderDetector.special?`: accepts `prefix:` keyword parameter
+- `SpecialFolderDetector.detect_in_path`: accepts `prefix:` keyword parameter
+
+### Added
+- `SpecialFolderDetector.short_name`: reverse of `normalize`, strips prefix from folder name (e.g., `_archive` → `archive`)
+
+## [0.14.0] - 2026-03-03
+
+### Added
+- `SlugSanitizer`: optional `max_length:` parameter (default: 55) for controlling slug length
+- `SlugSanitizer`: word-boundary truncation via `truncate_at_word_boundary` — cuts at last hyphen instead of mid-word
+
+## [0.13.1] - 2026-03-03
+
+### Changed
+- `StatsLineFormatter`: folder breakdown section (after em dash) is now dimmed via `AnsiColors` for visual distinction between current-view stats and system-wide totals
+- `StatsLineFormatter`: folder names strip `_` prefix for display (`_archive` → `archive`, `_maybe` → `maybe`)
+
+## [0.13.0] - 2026-03-03
+
+### Added
+- `AnsiColors` atom: TTY-aware ANSI color helpers with `colorize(text, color_code)` class method and color constants (RED, GREEN, YELLOW, CYAN, DIM, BOLD, RESET)
+- `StatsLineFormatter`: new `global_folder_stats:` parameter that always appends folder breakdown to the stats line regardless of filtered/unfiltered state
+
+## [0.12.0] - 2026-03-02
+
+### Added
+- `SortScoreCalculator` atom: computes sort scores using `priority_weight × 100 + age_days` with in-progress boost (+1000) and blocked penalty (×0.1), configurable weights and caps
+- `PositionGenerator` atom: generates B36TS position values for pinning items in sort order (`first`, `last`, `after`, `before`, `between`)
+- `SmartSorter` molecule: sorts items with pinned-first (by position ascending) + unpinned (by score descending) logic
+- `StatusCategorizer` accepts optional `up_next_sorter:` proc for custom sort order in up-next bucket
+
+## [0.11.0] - 2026-03-02
+
+### Added
+- `FolderCompletionDetector` atom: checks if all spec files in a directory have terminal status (done/skipped/blocked), with `recursive:` option for subtask subdirectories
+- `SpecialFolderDetector.move_to_root?` method: recognizes "next", "root", and "/" as move-to-root aliases (case-insensitive)
+
+## [0.10.0] - 2026-03-02
+
+### Added
+- `GitCommitter` molecule: shells out to `ace-git-commit` for auto-committing after CLI mutations, used by ace-task, ace-idea, and ace-retro `--git-commit` / `--gc` flag
+
+## [0.9.0] - 2026-03-02
+
+### Added
+- `RelativeTimeFormatter` atom: formats a Time into human-readable relative strings (just now, 5m ago, 2h ago, 3d ago, 2w ago, 1mo ago, 1y ago) with injectable reference time
+- `StatusCategorizer` molecule: categorizes items into "up next" (pending, root-only, sorted by ID) and "recently done" (done from all folders, sorted by file mtime desc) buckets for status overview displays
+
+## [0.8.1] - 2026-03-02
+
+### Fixed
+- `DirectoryScanner` now recurses into special folders that contain orphan spec files (e.g., `_maybe/` with stray `.idea.s.md` files no longer blocks discovery of item subfolders)
+
+## [0.8.0] - 2026-03-02
+
+### Added
+- `StatsLineFormatter.format` accepts `total_count:` parameter for "X of Y" filtered view display
+- Filtered view (shown < total): displays "3 of 660" instead of redundant "3 total"
+- Full view (shown == total): displays "660 total" with folder breakdown only when multi-folder
+
+### Changed
+- Single-folder stats no longer show redundant folder breakdown (e.g., "3 total" instead of "3 total — next 3")
+
+## [0.7.0] - 2026-03-02
+
+### Added
+- `ItemStatistics` atom: pure counting logic for grouping items by any field (`count_by`) and computing completion rates (`completion_rate`)
+- `StatsLineFormatter` atom: generic stats summary line builder with configurable label, status icons, ordering, and optional completion percentage
+
+## [0.6.0] - 2026-03-02
+
+### Added
+- `SpecialFolderDetector.virtual_filter?` method for resolving virtual filter names ("next", "all") to symbols
+- `VIRTUAL_FILTERS` constant mapping virtual filter names to symbols (`:next`, `:all`)
+
+### Changed
+- Remove `_next` from `SPECIAL_FOLDERS` and `SHORT_ALIASES` — "next" is now a virtual filter, not a physical folder
+- `FolderMover#move` raises `ArgumentError` when target is a virtual filter ("next", "all")
+
+## [0.5.0] - 2026-03-01
+
+### Added
+- `FieldUpdater` molecule for orchestrating --set/--add/--remove frontmatter field updates with nested dot-key support
+- `FolderMover` molecule for generic folder moves with special folder normalization, archive partitioning, and cross-fs atomic moves
+- `LlmSlugGenerator` molecule for LLM-powered slug generation with graceful fallback (moved from ace-taskflow)
+
+### Fixed
+- `FrontmatterSerializer` now correctly serializes nested Hash values with proper YAML indentation (previously produced Ruby Hash#to_s)
+
+## [0.4.0] - 2026-03-01
+
+### Added
+- `ItemIdFormatter` atom: splits 6-char b36ts IDs into type-marked format (`prefix.marker.suffix`) and reconstructs
+- `ItemIdParser` atom: parses all reference forms (full, short, suffix, subtask, raw) into `ItemId` model
+- `ItemId` model: value object with `raw_b36ts`, `prefix`, `type_marker`, `suffix`, `subtask_char`
+
+### Changed
+- `DirectoryScanner`: added configurable `id_extractor:` proc parameter (default preserves existing 6-char behavior)
+- `ShortcutResolver`: added `full_id_length:` parameter (default 6, set to 9 for type-marked IDs)
+
+## [0.3.0] - 2026-02-28
+
+### Added
+- `DatePartitionPath` atom: computes a B36TS month/week partition path (e.g. `"8p/4"`) from a `Time` object for use in archive directory structures
+- Runtime dependency on `ace-b36ts ~> 0.7`
+
+## [0.2.0] - 2026-02-28
+
+### Added
+
+- `FrontmatterParser` atom for parsing YAML frontmatter from markdown files (tuple return: `[Hash, String]`)
+- `FrontmatterSerializer` atom for serializing frontmatter hashes to YAML with inline arrays and value quoting
+- `FilterParser` atom for parsing `--filter key:value` syntax with OR (`|`) and negation (`!`) support
+- `TitleExtractor` atom for extracting first H1 heading from markdown body content
+- `LoadedDocument` model as value object for parsed document with frontmatter, body, title, and attachments
+- `DocumentLoader` molecule for loading documents from item directories with configurable file patterns
+- `FilterApplier` molecule for applying parsed filter specs with AND/OR logic, negation, and custom value accessors
+- `ItemSorter` molecule for sorting item collections by field with nil-last semantics
+- `BaseFormatter` molecule with minimal default item/list formatting (overridable by gems)
+
+## [0.1.1] - 2026-02-28
+
+### Technical
+- Moved `require "pathname"` to top-level in `SpecialFolderDetector` (was inline inside method)
+
+## [0.1.0] - 2026-02-28
+
+### Added
+
+- Initial release with shared item management infrastructure
+- `SlugSanitizer` atom for strict kebab-case slug sanitization
+- `FieldArgumentParser` atom for parsing `key=value` CLI arguments with type inference
+- `SpecialFolderDetector` atom for recognizing `_archive`, `_maybe`, `_anytime`, `_next` folders
+- `ScanResult` model as value object for directory scan results
+- `DirectoryScanner` molecule for recursive item directory scanning with special folder awareness
+- `ShortcutResolver` molecule for resolving 3-char suffix shortcuts to full item IDs with ambiguity detection

data/README.md

@@ -0,0 +1,29 @@
+<div align="center">
+  <h1> ACE - Support Items </h1>
+
+  Shared primitives for scanning, resolving, and sanitizing ACE item stores.
+
+  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <br><br>
+
+  <a href="https://rubygems.org/gems/ace-support-items"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-support-items.svg" /></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
+
+</div>
+
+> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
+
+`ace-support-items` standardizes directory scanning, shortcut resolution, and slug handling for ACE item workflows. It provides the low-level store operations that packages like [ace-task](../ace-task) and [ace-retro](../ace-retro) build their item management on.
+
+## Use Cases
+
+**Parse and resolve ACE task/idea shortcuts** - map compact IDs to canonical b36ts (base-36 timestamp) item paths, powering the shorthand lookups in [ace-task](../ace-task).
+
+**Handle special item directories (underscore-prefixed folders like _maybe, _archive, and _anytime) consistently** - support shared folder conventions across tools so scanners in [ace-retro](../ace-retro) and [ace-task](../ace-task) discover items the same way.
+
+**Normalize metadata safely** - sanitize slugs and arguments before persistence, preventing malformed entries in item stores.
+
+---
+
+Part of [ACE](https://github.com/cs3b/ace)

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task spec: :test
+task default: :test

data/lib/ace/support/items/atoms/ansi_colors.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Atoms
+        # Simple ANSI color helpers for terminal output.
+        # Automatically skips color codes when stdout is not a TTY.
+        module AnsiColors
+          RED = "\e[31m"
+          GREEN = "\e[32m"
+          YELLOW = "\e[33m"
+          CYAN = "\e[36m"
+          DIM = "\e[2m"
+          BOLD = "\e[1m"
+          RESET = "\e[0m"
+
+          # Wrap text in ANSI color codes.
+          # Returns plain text when stdout is not a TTY.
+          # @param text [String] Text to colorize
+          # @param color_code [String] ANSI escape code (e.g. AnsiColors::GREEN)
+          # @return [String]
+          def self.colorize(text, color_code)
+            return text unless tty?
+
+            "#{color_code}#{text}#{RESET}"
+          end
+
+          # @return [Boolean] Whether stdout is a TTY
+          def self.tty?
+            $stdout.tty?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/atoms/date_partition_path.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Atoms
+        # Computes a date-based partition path using B36TS month+week split.
+        # Result: "8p/4" (month / week components joined with "/")
+        class DatePartitionPath
+          DEFAULT_LEVELS = %i[month week].freeze
+
+          # @param time [Time] The time to partition
+          # @param levels [Array<Symbol>] B36TS split levels (default: [:month, :week])
+          # @return [String] Path string e.g. "8p/4"
+          def self.compute(time, levels: DEFAULT_LEVELS)
+            require "ace/b36ts"
+            result = Ace::B36ts.encode_split(time, levels: levels)
+            levels.map { |l| result[l].to_s }.join("/")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/atoms/field_argument_parser.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Atoms
+        # Parses command-line field arguments into typed hash values
+        # Handles type inference and array parsing for CLI input
+        class FieldArgumentParser
+          class ParseError < StandardError; end
+
+          # Parse field update arguments into structured format
+          # @param field_args [Array<String>] Field arguments in "key=value" format
+          # @return [Hash] Parsed field updates with keys and inferred values
+          # @raise [ParseError] If field syntax is invalid
+          def self.parse(field_args)
+            updates = {}
+
+            field_args.each do |arg|
+              # Match key=value with optional quotes around value
+              match = arg.match(/^([^=]+)=(.*)$/)
+              raise ParseError, "Invalid field syntax. Use: --field key=value" unless match
+
+              key = match[1].strip
+              value_str = match[2].strip
+
+              # Infer type from value string
+              value = infer_type(value_str)
+
+              # Store with key path for nested support
+              updates[key] = value
+            end
+
+            updates
+          end
+
+          # Infer value type from string
+          # @param value_str [String] String value from command line
+          # @return [Object] Inferred value (Integer, Boolean, Array, or String)
+          def self.infer_type(value_str)
+            # Remove surrounding quotes if present (must match)
+            if value_str.match?(/^"(.*)"$/) || value_str.match?(/^'(.*)'$/)
+              # Quoted string - strip quotes and return as string
+              return value_str[1..-2]
+            end
+
+            case value_str
+            when "" then ""
+            when "true" then true
+            when "false" then false
+            when /^-?\d+$/ then value_str.to_i
+            when /^-?\d+\.\d+$/ then value_str.to_f
+            when /^\[.*\]$/
+              content = value_str[1..-2].strip
+              return [] if content.empty?
+
+              # Parse array items handling quoted strings
+              items = parse_array_items(content)
+
+              # Try to infer types for array items
+              items.map { |item| infer_type(item) }
+            else
+              value_str
+            end
+          end
+
+          # Parse array items handling quoted strings with commas
+          # @param content [String] Array content without brackets
+          # @return [Array<String>] Parsed items
+          def self.parse_array_items(content)
+            items = []
+            current_item = ""
+            in_quotes = false
+            quote_char = nil
+            i = 0
+
+            while i < content.length
+              char = content[i]
+
+              if !in_quotes && (char == '"' || char == "'")
+                in_quotes = true
+                quote_char = char
+                current_item += char
+              elsif in_quotes && char == quote_char
+                in_quotes = false
+                quote_char = nil
+                current_item += char
+              elsif !in_quotes && char == ","
+                items << current_item.strip
+                current_item = ""
+              else
+                current_item += char
+              end
+
+              i += 1
+            end
+
+            items << current_item.strip unless current_item.strip.empty?
+            items.map { |item| item.empty? ? "" : item }
+          end
+
+          private_class_method :infer_type, :parse_array_items
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/atoms/filter_parser.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Atoms
+        # Parse `--filter key:value` syntax from command-line arguments.
+        # Supports simple values, OR (`key:a|b`), and negation (`key:!value`).
+        class FilterParser
+          # Parse filter strings into filter specifications
+          # @param filter_strings [Array<String>] Array of "key:value" filter strings
+          # @return [Array<Hash>] Array of filter specifications
+          # @raise [ArgumentError] If filter syntax is invalid
+          #
+          # Examples:
+          #   parse(["status:pending"])
+          #   # => [{key: "status", values: ["pending"], negated: false, or_mode: false}]
+          #
+          #   parse(["status:pending|in-progress"])
+          #   # => [{key: "status", values: ["pending", "in-progress"], negated: false, or_mode: true}]
+          #
+          #   parse(["status:!done"])
+          #   # => [{key: "status", values: ["done"], negated: true, or_mode: false}]
+          def self.parse(filter_strings)
+            return [] if filter_strings.nil? || filter_strings.empty?
+
+            Array(filter_strings).map do |filter_string|
+              parse_single_filter(filter_string)
+            end
+          end
+
+          # Parse a single filter string
+          # @param filter_string [String] Single "key:value" string
+          # @return [Hash] Filter specification
+          # @raise [ArgumentError] If syntax is invalid
+          private_class_method def self.parse_single_filter(filter_string)
+            unless filter_string.is_a?(String) && filter_string.include?(":")
+              raise ArgumentError, "Invalid filter syntax: '#{filter_string}'. Use: --filter key:value"
+            end
+
+            parts = filter_string.split(":", 2)
+            key = parts[0]&.strip
+            value_part = parts[1]&.strip
+
+            if key.nil? || key.empty?
+              raise ArgumentError, "Invalid filter syntax: missing key in '#{filter_string}'. Use: --filter key:value"
+            end
+
+            if value_part.nil? || value_part.empty?
+              raise ArgumentError, "Invalid filter syntax: missing value in '#{filter_string}'. Use: --filter key:value"
+            end
+
+            negated = value_part.start_with?("!")
+            value_part = value_part[1..] if negated
+
+            if value_part.nil? || value_part.empty?
+              raise ArgumentError, "Invalid filter syntax: empty value after negation in '#{filter_string}'"
+            end
+
+            values = value_part.split("|").map(&:strip).reject(&:empty?)
+
+            if values.empty?
+              raise ArgumentError, "Invalid filter syntax: no valid values in '#{filter_string}'"
+            end
+
+            or_mode = values.length > 1
+
+            {
+              key: key,
+              values: values,
+              negated: negated,
+              or_mode: or_mode
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/atoms/folder_completion_detector.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "frontmatter_parser"
+
+module Ace
+  module Support
+    module Items
+      module Atoms
+        # Detects whether all spec files in a folder have terminal status.
+        # Used by orchestrator auto-archive: when all subtasks are done/skipped/blocked,
+        # the parent can be auto-archived.
+        class FolderCompletionDetector
+          TERMINAL_STATUSES = %w[done skipped blocked].freeze
+
+          # Check if all spec files in a directory have terminal status.
+          #
+          # @param dir_path [String] Directory to check
+          # @param spec_pattern [String] Glob pattern for spec files (default: "*.s.md")
+          # @param terminal_statuses [Array<String>] Statuses considered terminal
+          # @param recursive [Boolean] If true, also check one level of subdirectories
+          # @return [Boolean] True if all found specs have terminal status; false if none found
+          def self.all_terminal?(dir_path, spec_pattern: "*.s.md", terminal_statuses: TERMINAL_STATUSES, recursive: false)
+            patterns = [File.join(dir_path, spec_pattern)]
+            patterns << File.join(dir_path, "*", spec_pattern) if recursive
+
+            files = patterns.flat_map { |p| Dir.glob(p) }
+            return false if files.empty?
+
+            files.all? do |file|
+              content = File.read(file)
+              frontmatter, = FrontmatterParser.parse(content)
+              status = frontmatter["status"].to_s.downcase
+              terminal_statuses.include?(status)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/atoms/frontmatter_parser.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Support
+    module Items
+      module Atoms
+        # Pure function to parse YAML frontmatter from markdown files.
+        # Extracts frontmatter hash and body content from `---` delimited blocks.
+        class FrontmatterParser
+          # Parse YAML frontmatter from markdown content
+          # @param content [String] The markdown content with optional frontmatter
+          # @return [Hash] Parsed frontmatter data (empty hash if no frontmatter)
+          def self.parse_frontmatter(content)
+            return {} if content.nil? || content.empty?
+            return {} unless content.start_with?("---\n")
+
+            end_index = content.index("\n---\n", 4)
+            return {} unless end_index
+
+            yaml_content = content[4...end_index]
+
+            begin
+              YAML.safe_load(yaml_content, permitted_classes: [Date, Time, Symbol]) || {}
+            rescue Psych::SyntaxError
+              {}
+            end
+          end
+
+          # Extract content after frontmatter
+          # @param content [String] The markdown content with optional frontmatter
+          # @return [String] The content without frontmatter
+          def self.extract_body(content)
+            return "" if content.nil? || content.empty?
+
+            if content.start_with?("---\n")
+              end_index = content.index("\n---\n", 4)
+              if end_index
+                return content[(end_index + 5)..] || ""
+              end
+            end
+
+            content
+          end
+
+          # Parse both frontmatter and body
+          # @param content [String] The markdown content
+          # @return [Array(Hash, String)] Tuple of [frontmatter, body]
+          def self.parse(content)
+            [parse_frontmatter(content), extract_body(content)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/items/atoms/frontmatter_serializer.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Items
+      module Atoms
+        # Serializes frontmatter hashes to YAML block strings with `---` delimiters.
+        # Preserves inline-array style (`tags: [ux, design]`) and quotes
+        # YAML-ambiguous values.
+        class FrontmatterSerializer
+          YAML_AMBIGUOUS = /\A(true|false|yes|no|on|off|null|~|-?\d+(\.\d+)?([eE][+-]?\d+)?)\z/i
+
+          # Serialize frontmatter hash to YAML block string
+          # @param frontmatter [Hash] Frontmatter data
+          # @return [String] YAML frontmatter block including `---` delimiters
+          def self.serialize(frontmatter)
+            lines = ["---"]
+            frontmatter.each do |key, value|
+              serialize_entry(lines, key, value, indent: 0)
+            end
+            lines << "---"
+            lines.join("\n")
+          end
+
+          # Rebuild a full document from frontmatter and body
+          # @param frontmatter [Hash] Frontmatter data
+          # @param body [String] Document body content
+          # @return [String] Full document with frontmatter block and body
+          def self.rebuild(frontmatter, body)
+            "#{serialize(frontmatter)}\n\n#{body}"
+          end
+
+          # Serialize a single key-value entry with indentation support.
+          def self.serialize_entry(lines, key, value, indent:)
+            prefix = "  " * indent
+            case value
+            when Hash
+              lines << "#{prefix}#{key}:"
+              value.each do |k, v|
+                serialize_entry(lines, k, v, indent: indent + 1)
+              end
+            when Array
+              lines << if value.empty?
+                "#{prefix}#{key}: []"
+              else
+                "#{prefix}#{key}: [#{value.join(", ")}]"
+              end
+            when String
+              lines << if needs_quoting?(value)
+                "#{prefix}#{key}: \"#{escape_yaml_string(value)}\""
+              else
+                "#{prefix}#{key}: #{value}"
+              end
+            else
+              lines << "#{prefix}#{key}: #{value}"
+            end
+          end
+
+          private_class_method :serialize_entry
+
+          # Check if a string value needs YAML quoting
+          # @param value [String] Value to check
+          # @return [Boolean]
+          private_class_method def self.needs_quoting?(value)
+            value.match?(YAML_AMBIGUOUS) ||
+              value.match?(/[:#@*&!%{}|>'"`\\,?\[\]]/) ||
+              value.start_with?(" ", "\t") || value.end_with?(" ", "\t") ||
+              value.include?("\n") || value.empty?
+          end
+
+          # Escape a string for double-quoted YAML
+          # @param value [String] Value to escape
+          # @return [String] Escaped value
+          private_class_method def self.escape_yaml_string(value)
+            value.gsub("\\", "\\\\\\\\").gsub('"', '\\"')
+          end
+        end
+      end
+    end
+  end
+end