ace-retro 0.16.0

data/lib/ace/retro/molecules/retro_creator.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+require_relative "../atoms/retro_id_formatter"
+require_relative "../atoms/retro_file_pattern"
+require_relative "../atoms/retro_frontmatter_defaults"
+require_relative "retro_loader"
+
+module Ace
+  module Retro
+    module Molecules
+      # Creates new retros with b36ts IDs, folder+file creation.
+      # Supports --type and --move-to options.
+      class RetroCreator
+        # @param root_dir [String] Root directory for retros
+        # @param config [Hash] Configuration hash
+        def initialize(root_dir:, config: {})
+          @root_dir = root_dir
+          @config = config
+        end
+
+        # Create a new retro
+        # @param title [String] Retro title
+        # @param type [String] Retro type (standard, conversation-analysis, self-review)
+        # @param tags [Array<String>] Tags for the retro
+        # @param move_to [String, nil] Target folder for the retro
+        # @param time [Time] Creation time (default: now)
+        # @return [Retro] Created retro object
+        def create(title, type: nil, tags: [], move_to: nil, time: Time.now.utc)
+          raise ArgumentError, "Title is required" if title.nil? || title.strip.empty?
+
+          effective_type = type || @config.dig("retro", "default_type") || "standard"
+
+          # Generate ID and slugs
+          id = Atoms::RetroIdFormatter.generate(time)
+          folder_slug = generate_folder_slug(title)
+          file_slug = generate_file_slug(title)
+
+          # Determine target directory
+          target_dir = determine_target_dir(move_to)
+          FileUtils.mkdir_p(target_dir)
+
+          # Create retro folder (ensure unique name if ID collision occurs)
+          folder_name, _ = unique_folder_name(id, folder_slug, target_dir)
+          retro_dir = File.join(target_dir, folder_name)
+          FileUtils.mkdir_p(retro_dir)
+
+          # Build frontmatter
+          frontmatter = Atoms::RetroFrontmatterDefaults.build(
+            id: id,
+            title: title,
+            type: effective_type,
+            tags: tags,
+            status: "active",
+            created_at: time
+          )
+
+          # Write retro file
+          file_content = build_file_content(frontmatter, title, effective_type)
+          retro_filename = Atoms::RetroFilePattern.retro_filename(id, file_slug)
+          retro_file = File.join(retro_dir, retro_filename)
+          File.write(retro_file, file_content)
+
+          # Load and return the created retro
+          loader = RetroLoader.new
+          special_folder = Ace::Support::Items::Atoms::SpecialFolderDetector.detect_in_path(
+            retro_dir, root: @root_dir
+          )
+          loader.load(retro_dir, id: id, special_folder: special_folder)
+        end
+
+        private
+
+        # Ensure unique folder name when the same b36ts ID is generated within the
+        # same 2-second window. If the candidate folder already exists, appends a
+        # numeric counter to the slug: {id}-{slug}-2, {id}-{slug}-3, etc.
+        # @return [Array<String>] [folder_name, effective_slug]
+        def unique_folder_name(id, slug, target_dir)
+          folder_name = Atoms::RetroFilePattern.folder_name(id, slug)
+          candidate_dir = File.join(target_dir, folder_name)
+
+          return [folder_name, slug] unless Dir.exist?(candidate_dir)
+
+          counter = 2
+          loop do
+            unique_slug = "#{slug}-#{counter}"
+            folder_name = Atoms::RetroFilePattern.folder_name(id, unique_slug)
+            candidate_dir = File.join(target_dir, folder_name)
+            break [folder_name, unique_slug] unless Dir.exist?(candidate_dir)
+
+            counter += 1
+          end
+        end
+
+        def generate_folder_slug(title)
+          sanitized = Ace::Support::Items::Atoms::SlugSanitizer.sanitize(title.to_s)
+          words = sanitized.split("-")
+          words.take(5).join("-").then { |s| s.empty? ? "retro" : s }
+        end
+
+        def generate_file_slug(title)
+          sanitized = Ace::Support::Items::Atoms::SlugSanitizer.sanitize(title.to_s)
+          words = sanitized.split("-")
+          words.take(7).join("-").then { |s| s.empty? ? "retro" : s }
+        end
+
+        def determine_target_dir(move_to)
+          if move_to
+            normalized = Ace::Support::Items::Atoms::SpecialFolderDetector.normalize(move_to)
+            candidate = File.expand_path(File.join(@root_dir, normalized))
+            root_real = File.expand_path(@root_dir)
+            unless candidate.start_with?(root_real + File::SEPARATOR) || candidate == root_real
+              raise ArgumentError, "Path traversal detected in --move-to option"
+            end
+            candidate
+          else
+            @root_dir
+          end
+        end
+
+        def build_file_content(frontmatter, title, type)
+          fm_str = Atoms::RetroFrontmatterDefaults.serialize(frontmatter)
+
+          body = retro_template(type)
+
+          "#{fm_str}\n\n# #{title}\n\n#{body}\n"
+        end
+
+        def retro_template(type)
+          case type
+          when "conversation-analysis"
+            <<~BODY
+              ## Context
+
+              ## Key Observations
+
+              ## Patterns Identified
+
+              ## Action Items
+            BODY
+          when "self-review"
+            <<~BODY
+              ## What I Did Well
+
+              ## What I Could Improve
+
+              ## Key Learnings
+
+              ## Action Items
+            BODY
+          else # standard
+            <<~BODY
+              ## What Went Well
+
+              ## What Could Be Improved
+
+              ## Action Items
+            BODY
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/retro/molecules/retro_display_formatter.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Ace
+  module Retro
+    module Molecules
+      # Formats retro objects for terminal display.
+      class RetroDisplayFormatter
+        STATUS_SYMBOLS = {
+          "active" => "○",
+          "done" => "✓"
+        }.freeze
+
+        STATUS_COLORS = {
+          "active" => Ace::Support::Items::Atoms::AnsiColors::YELLOW,
+          "done" => Ace::Support::Items::Atoms::AnsiColors::GREEN
+        }.freeze
+
+        TYPE_LABELS = {
+          "standard" => "standard",
+          "conversation-analysis" => "conversation",
+          "self-review" => "self-review"
+        }.freeze
+
+        # Return the status symbol with ANSI color applied.
+        def self.colored_status_sym(status)
+          sym = STATUS_SYMBOLS[status] || "○"
+          color = STATUS_COLORS[status]
+          color ? Ace::Support::Items::Atoms::AnsiColors.colorize(sym, color) : sym
+        end
+
+        private_class_method :colored_status_sym
+
+        # Format a single retro for display
+        # @param retro [Retro] Retro to format
+        # @param show_content [Boolean] Whether to include full content
+        # @return [String] Formatted output
+        def self.format(retro, show_content: false)
+          c = Ace::Support::Items::Atoms::AnsiColors
+          status_sym = colored_status_sym(retro.status)
+          id_str = show_content ? retro.id : c.colorize(retro.id, c::DIM)
+          tags_str = retro.tags.any? ? c.colorize(" [#{retro.tags.join(", ")}]", c::DIM) : ""
+          folder_str = retro.special_folder ? c.colorize(" (#{retro.special_folder})", c::DIM) : ""
+          type_str = c.colorize(" <#{TYPE_LABELS[retro.type] || retro.type}>", c::DIM)
+          lines = []
+          lines << "#{status_sym} #{id_str} #{retro.title}#{type_str}#{tags_str}#{folder_str}"
+
+          if show_content && retro.content && !retro.content.strip.empty?
+            lines << ""
+            lines << retro.content
+          end
+
+          if retro.folder_contents&.any?
+            lines << ""
+            lines << "Files: #{retro.folder_contents.join(", ")}"
+          end
+
+          lines.join("\n")
+        end
+
+        # Format a list of retros for display
+        # @param retros [Array<Retro>] Retros to format
+        # @param total_count [Integer, nil] Total items before folder filtering
+        # @param global_folder_stats [Hash, nil] Folder name → count hash from full scan
+        # @return [String] Formatted list output
+        def self.format_list(retros, total_count: nil, global_folder_stats: nil)
+          return "No retros found." if retros.empty?
+
+          lines = retros.map { |retro| format(retro) }.join("\n")
+          "#{lines}\n\n#{format_stats_line(retros, total_count: total_count, global_folder_stats: global_folder_stats)}"
+        end
+
+        STATUS_ORDER = %w[active done].freeze
+
+        # Format a stats summary line for a list of retros.
+        # @param retros [Array<Retro>] Retros to summarize
+        # @param total_count [Integer, nil] Total items before folder filtering
+        # @param global_folder_stats [Hash, nil] Folder name → count hash from full scan
+        # @return [String] e.g. "Retros: ○ 2 | ✓ 5 • 2 of 7"
+        def self.format_stats_line(retros, total_count: nil, global_folder_stats: nil)
+          stats = Ace::Support::Items::Atoms::ItemStatistics.count_by(retros, :status)
+          folder_stats = Ace::Support::Items::Atoms::ItemStatistics.count_by(retros, :special_folder)
+          Ace::Support::Items::Atoms::StatsLineFormatter.format(
+            label: "Retros",
+            stats: stats,
+            status_order: STATUS_ORDER,
+            status_icons: STATUS_SYMBOLS,
+            folder_stats: folder_stats,
+            total_count: total_count,
+            global_folder_stats: global_folder_stats
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ace/retro/molecules/retro_doctor_fixer.rb

@@ -0,0 +1,404 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "ace/support/markdown"
+require "ace/support/items"
+require_relative "../atoms/retro_id_formatter"
+require_relative "../atoms/retro_validation_rules"
+require_relative "../atoms/retro_frontmatter_defaults"
+require_relative "retro_loader"
+require_relative "retro_mover"
+
+module Ace
+  module Retro
+    module Molecules
+      # Handles auto-fixing of common retro issues detected by doctor.
+      # Supports dry_run mode to preview fixes without applying them.
+      class RetroDoctorFixer
+        attr_reader :dry_run, :fixed_count, :skipped_count
+
+        def initialize(dry_run: false, root_dir: nil)
+          @dry_run = dry_run
+          @root_dir = root_dir
+          @fixed_count = 0
+          @skipped_count = 0
+          @fixes_applied = []
+        end
+
+        # Fix a batch of issues
+        # @param issues [Array<Hash>] Issues to fix
+        # @return [Hash] Fix results summary
+        def fix_issues(issues)
+          fixable_issues = issues.select { |issue| can_fix?(issue) }
+
+          fixable_issues.each do |issue|
+            fix_issue(issue)
+          end
+
+          {
+            fixed: @fixed_count,
+            skipped: @skipped_count,
+            fixes_applied: @fixes_applied,
+            dry_run: @dry_run
+          }
+        end
+
+        # Fix a single issue by pattern matching its message
+        # @param issue [Hash] Issue to fix
+        # @return [Boolean] Whether fix was successful
+        def fix_issue(issue)
+          case issue[:message]
+          when /Missing opening '---' delimiter/
+            fix_missing_opening_delimiter(issue[:location])
+          when /Missing closing '---' delimiter/
+            fix_missing_closing_delimiter(issue[:location])
+          when /Missing required field: id/
+            fix_missing_id(issue[:location])
+          when /Missing required field: status/,
+               /Missing recommended field: status/
+            fix_missing_status(issue[:location])
+          when /Missing required field: title/,
+               /Missing recommended field: title/
+            fix_missing_title(issue[:location])
+          when /Missing required field: type/
+            fix_missing_type(issue[:location])
+          when /Missing required field: created_at/
+            fix_missing_created_at(issue[:location])
+          when /Field 'tags' is not an array/
+            fix_tags_not_array(issue[:location])
+          when /Missing recommended field: tags/
+            fix_missing_tags(issue[:location])
+          when /terminal status.*not in _archive/
+            fix_move_to_archive(issue[:location])
+          when /in _archive\/ but status is/
+            fix_archive_status(issue[:location])
+          when /Invalid archive partition/
+            fix_invalid_archive_partition(issue[:location])
+          when /Stale backup file/
+            fix_stale_backup(issue[:location])
+          when /Empty directory/
+            fix_empty_directory(issue[:location])
+          else
+            @skipped_count += 1
+            false
+          end
+        end
+
+        # Check if an issue can be auto-fixed
+        # @param issue [Hash] Issue to check
+        # @return [Boolean]
+        def can_fix?(issue)
+          return false unless issue[:location]
+
+          FIXABLE_PATTERNS.any? { |pattern| issue[:message].match?(pattern) }
+        end
+
+        FIXABLE_PATTERNS = [
+          /Missing opening '---' delimiter/,
+          /Missing closing '---' delimiter/,
+          /Missing required field: id/,
+          /Missing required field: status/,
+          /Missing required field: title/,
+          /Missing required field: type/,
+          /Missing required field: created_at/,
+          /Missing recommended field: status/,
+          /Missing recommended field: title/,
+          /Missing recommended field: tags/,
+          /Field 'tags' is not an array/,
+          /terminal status.*not in _archive/,
+          /in _archive\/ but status is/,
+          /Invalid archive partition/,
+          /Stale backup file/,
+          /Empty directory/
+        ].freeze
+
+        private
+
+        def fix_missing_closing_delimiter(file_path)
+          return false unless File.exist?(file_path)
+
+          content = File.read(file_path)
+          lines = content.lines
+          insert_idx = nil
+          lines[1..].each_with_index do |line, i|
+            if line.strip.empty? || line.start_with?("#")
+              insert_idx = i + 1
+              break
+            end
+          end
+          insert_idx ||= lines.size
+
+          fixed_lines = lines.dup
+          fixed_lines.insert(insert_idx, "---\n")
+          fixed_content = fixed_lines.join
+
+          apply_file_fix(file_path, fixed_content, "Added missing closing '---' delimiter")
+        end
+
+        def fix_missing_opening_delimiter(file_path)
+          return false unless File.exist?(file_path)
+
+          content = File.read(file_path)
+          dir_name = File.basename(File.dirname(file_path))
+          id_match = dir_name.match(/^([0-9a-z]{6})/)
+          id = id_match ? id_match[1] : nil
+
+          title = extract_title_from_content(content) || extract_slug_title(dir_name)
+
+          frontmatter = Atoms::RetroFrontmatterDefaults.build(
+            id: id || Atoms::RetroIdFormatter.generate,
+            title: title,
+            status: "active",
+            created_at: Time.now.utc
+          )
+          frontmatter["id"] = id if id
+
+          yaml_block = Atoms::RetroFrontmatterDefaults.serialize(frontmatter)
+          new_content = "#{yaml_block}\n#{content}"
+
+          apply_file_fix(file_path, new_content, "Added opening '---' delimiter and frontmatter")
+        end
+
+        def fix_missing_id(file_path)
+          return false unless File.exist?(file_path)
+
+          dir_name = File.basename(File.dirname(file_path))
+          id_match = dir_name.match(/^([0-9a-z]{6})/)
+          unless id_match
+            return (@skipped_count += 1
+                    false)
+          end
+
+          id = id_match[1]
+          update_frontmatter_field(file_path, "id", id, "Added missing 'id' field from folder name")
+        end
+
+        def fix_missing_status(file_path)
+          update_frontmatter_field(file_path, "status", "active", "Added missing 'status' field with default 'active'")
+        end
+
+        def fix_missing_title(file_path)
+          return false unless File.exist?(file_path)
+
+          content = File.read(file_path)
+          title = nil
+          _fm, body = Ace::Support::Items::Atoms::FrontmatterParser.parse(content)
+          if body
+            h1_match = body.match(/^#\s+(.+)/)
+            title = h1_match[1].strip if h1_match
+          end
+
+          unless title
+            dir_name = File.basename(File.dirname(file_path))
+            slug_match = dir_name.match(/^[0-9a-z]{6}-(.+)$/)
+            title = slug_match ? slug_match[1].tr("-", " ").capitalize : "Untitled"
+          end
+
+          update_frontmatter_field(file_path, "title", title, "Added missing 'title' field: '#{title}'")
+        end
+
+        def fix_missing_type(file_path)
+          update_frontmatter_field(file_path, "type", "standard", "Added missing 'type' field with default 'standard'")
+        end
+
+        def fix_missing_created_at(file_path)
+          return false unless File.exist?(file_path)
+
+          content = File.read(file_path)
+          frontmatter, _body = Ace::Support::Items::Atoms::FrontmatterParser.parse(content)
+
+          id = frontmatter&.dig("id")
+          unless id
+            match = File.basename(File.dirname(file_path)).match(/^([0-9a-z]{6})/)
+            id = match[1] if match
+          end
+
+          created_at = if id && Atoms::RetroIdFormatter.valid?(id)
+            Atoms::RetroIdFormatter.decode_time(id).strftime("%Y-%m-%d %H:%M:%S")
+          else
+            Time.now.utc.strftime("%Y-%m-%d %H:%M:%S")
+          end
+
+          update_frontmatter_field(file_path, "created_at", created_at, "Added missing 'created_at' field")
+        end
+
+        def fix_tags_not_array(file_path)
+          update_frontmatter_field(file_path, "tags", [], "Coerced 'tags' field to empty array")
+        end
+
+        def fix_missing_tags(file_path)
+          update_frontmatter_field(file_path, "tags", [], "Added missing 'tags' field with empty array")
+        end
+
+        def fix_move_to_archive(file_path)
+          return false unless file_path && @root_dir
+
+          retro_dir = File.directory?(file_path) ? file_path : File.dirname(file_path)
+          folder_name = File.basename(retro_dir)
+          partition = Ace::Support::Items::Atoms::DatePartitionPath.compute(Time.now, levels: [:month])
+          archive_dir = File.join(@root_dir, "_archive", partition)
+          target = File.join(archive_dir, folder_name)
+
+          if @dry_run
+            log_fix(retro_dir, "Would move to _archive/#{partition}/")
+            @fixed_count += 1
+            return true
+          end
+
+          FileUtils.mkdir_p(archive_dir)
+          if File.exist?(target)
+            return (@skipped_count += 1
+                    false)
+          end
+
+          FileUtils.mv(retro_dir, target)
+          log_fix(retro_dir, "Moved to _archive/#{partition}/")
+          @fixed_count += 1
+          true
+        rescue
+          @skipped_count += 1
+          false
+        end
+
+        def fix_archive_status(file_path)
+          update_frontmatter_field(file_path, "status", "done", "Updated status to 'done' (in _archive/)")
+        end
+
+        def fix_invalid_archive_partition(partition_dir)
+          return false unless partition_dir && Dir.exist?(partition_dir) && @root_dir
+
+          loader = RetroLoader.new
+          mover = RetroMover.new(@root_dir)
+          moved = 0
+
+          Dir.glob(File.join(partition_dir, "*")).each do |retro_path|
+            next unless File.directory?(retro_path)
+
+            retro = loader.load(retro_path, special_folder: "_archive")
+            next unless retro
+
+            if @dry_run
+              partition = Ace::Support::Items::Atoms::DatePartitionPath.compute(retro.created_at || Time.now)
+              log_fix(retro_path, "Would move to _archive/#{partition}/")
+            else
+              mover.move(retro, to: "archive", date: retro.created_at)
+            end
+            moved += 1
+          end
+
+          # Remove empty partition dir
+          unless @dry_run
+            remaining = Dir.glob(File.join(partition_dir, "*"))
+            FileUtils.rmdir(partition_dir) if remaining.empty?
+          end
+
+          if moved > 0
+            unless @dry_run
+              log_fix(partition_dir, "Relocated #{moved} retro(s) to b36ts partition(s)")
+            end
+            @fixed_count += 1
+            true
+          else
+            @skipped_count += 1
+            false
+          end
+        rescue
+          @skipped_count += 1
+          false
+        end
+
+        def fix_stale_backup(file_path)
+          return false unless file_path && File.exist?(file_path)
+
+          if @dry_run
+            log_fix(file_path, "Would delete stale backup file")
+          else
+            File.delete(file_path)
+            log_fix(file_path, "Deleted stale backup file")
+          end
+
+          @fixed_count += 1
+          true
+        end
+
+        def fix_empty_directory(dir_path)
+          return false unless dir_path && Dir.exist?(dir_path)
+
+          files = Dir.glob(File.join(dir_path, "**", "*")).select { |f| File.file?(f) }
+          unless files.empty?
+            @skipped_count += 1
+            return false
+          end
+
+          if @dry_run
+            log_fix(dir_path, "Would delete empty directory")
+          else
+            FileUtils.rm_rf(dir_path)
+            log_fix(dir_path, "Deleted empty directory")
+          end
+
+          @fixed_count += 1
+          true
+        end
+
+        def extract_title_from_content(content)
+          h1_match = content.match(/^#\s+(.+)$/)
+          h1_match ? h1_match[1].strip : nil
+        end
+
+        def extract_slug_title(dir_name)
+          slug_match = dir_name.match(/^[0-9a-z]{6}-(.+)$/)
+          slug = slug_match ? slug_match[1] : dir_name
+          slug.tr("-", " ").capitalize
+        end
+
+        def update_frontmatter_field(file_path, field, value, description)
+          return false unless file_path && File.exist?(file_path)
+
+          if @dry_run
+            log_fix(file_path, "Would: #{description}")
+            @fixed_count += 1
+            return true
+          end
+
+          editor = Ace::Support::Markdown::Organisms::DocumentEditor.new(file_path)
+          editor.update_frontmatter(field => value)
+          editor.save!(backup: true, validate_before: false)
+          log_fix(file_path, description)
+          @fixed_count += 1
+          true
+        rescue
+          @skipped_count += 1
+          false
+        end
+
+        def apply_file_fix(file_path, new_content, description)
+          if @dry_run
+            log_fix(file_path, "Would: #{description}")
+          else
+            Ace::Support::Markdown::Organisms::SafeFileWriter.write(
+              file_path,
+              new_content,
+              backup: true
+            )
+            log_fix(file_path, description)
+          end
+
+          @fixed_count += 1
+          true
+        rescue
+          @skipped_count += 1
+          false
+        end
+
+        def log_fix(file_path, description)
+          @fixes_applied << {
+            file: file_path,
+            description: description,
+            timestamp: Time.now
+          }
+        end
+      end
+    end
+  end
+end