ace-retro 0.16.0

data/lib/ace/retro/cli/commands/doctor.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require "ace/llm"
+require_relative "../../organisms/retro_doctor"
+require_relative "../../molecules/retro_doctor_fixer"
+require_relative "../../molecules/retro_doctor_reporter"
+require_relative "../../molecules/retro_config_loader"
+
+module Ace
+  module Retro
+    module CLI
+      module Commands
+        # ace-support-cli Command class for ace-retro doctor
+        #
+        # Runs health checks on retros and optionally auto-fixes issues.
+        class Doctor < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc <<~DESC.strip
+            Run health checks on retros
+
+            Validates frontmatter, file structure, and scope/status consistency
+            across all retros in the repository. Supports auto-fixing safe issues.
+
+          DESC
+
+          example [
+            "                          # Run all health checks",
+            "--auto-fix                # Auto-fix safe issues",
+            "--auto-fix --dry-run      # Preview fixes without applying",
+            "--auto-fix-with-agent     # Auto-fix then launch agent for remaining",
+            "--check frontmatter       # Run specific check (frontmatter|structure|scope)",
+            "--json                    # Output as JSON",
+            "--verbose                 # Show all warnings"
+          ]
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :auto_fix, type: :boolean, aliases: %w[-f], desc: "Auto-fix safe issues"
+          option :auto_fix_with_agent, type: :boolean, desc: "Auto-fix then launch agent for remaining"
+          option :model, type: :string, desc: "Provider:model for agent session"
+          option :errors_only, type: :boolean, desc: "Show only errors, not warnings"
+          option :no_color, type: :boolean, desc: "Disable colored output"
+          option :json, type: :boolean, desc: "Output in JSON format"
+          option :dry_run, type: :boolean, aliases: %w[-n], desc: "Preview fixes without applying"
+          option :check, type: :string, desc: "Run specific check (frontmatter, structure, scope)"
+
+          def call(**options)
+            execute_doctor(options)
+          end
+
+          private
+
+          def execute_doctor(options)
+            config = Molecules::RetroConfigLoader.load
+            root_dir = Molecules::RetroConfigLoader.root_dir(config)
+
+            unless Dir.exist?(root_dir)
+              puts "Error: Retros directory not found: #{root_dir}"
+              raise Ace::Support::Cli::Error.new("Retros directory not found")
+            end
+
+            format = options[:json] ? :json : :terminal
+            fix = options[:auto_fix] || options[:auto_fix_with_agent]
+            colors = !options[:no_color]
+            colors = false if format == :json
+
+            doctor_opts = {}
+            doctor_opts[:check] = options[:check] if options[:check]
+
+            if options[:quiet]
+              results = run_diagnosis(root_dir, doctor_opts)
+              raise Ace::Support::Cli::Error.new("Health check failed") unless results[:valid]
+              return
+            end
+
+            results = run_diagnosis(root_dir, doctor_opts)
+
+            if options[:errors_only] && results[:issues]
+              results[:issues] = results[:issues].select { |i| i[:type] == :error }
+            end
+
+            output = Molecules::RetroDoctorReporter.format_results(
+              results,
+              format: format,
+              verbose: options[:verbose],
+              colors: colors
+            )
+            puts output
+
+            if fix && results[:issues]&.any?
+              handle_auto_fix(results, root_dir, doctor_opts, options, colors)
+            end
+
+            if options[:auto_fix_with_agent]
+              handle_agent_fix(root_dir, doctor_opts, options, config)
+            end
+
+            raise Ace::Support::Cli::Error.new("Health check failed") unless results[:valid]
+          rescue Ace::Support::Cli::Error
+            raise
+          rescue => e
+            raise Ace::Support::Cli::Error.new(e.message)
+          end
+
+          def run_diagnosis(root_dir, doctor_opts)
+            doctor = Organisms::RetroDoctor.new(root_dir, doctor_opts)
+            doctor.run_diagnosis
+          end
+
+          def handle_auto_fix(results, root_dir, doctor_opts, options, colors)
+            doctor = Organisms::RetroDoctor.new(root_dir, doctor_opts)
+            fixable_issues = results[:issues].select { |issue| doctor.auto_fixable?(issue) }
+
+            if fixable_issues.empty?
+              puts "\nNo auto-fixable issues found"
+              return
+            end
+
+            unless options[:quiet] || options[:dry_run]
+              puts "\nFound #{fixable_issues.size} auto-fixable issues"
+              print "Apply fixes? (y/N): "
+              response = $stdin.gets.chomp.downcase
+              return unless response == "y" || response == "yes"
+            end
+
+            fixer = Molecules::RetroDoctorFixer.new(dry_run: options[:dry_run], root_dir: root_dir)
+            fix_results = fixer.fix_issues(fixable_issues)
+
+            output = Molecules::RetroDoctorReporter.format_fix_results(
+              fix_results,
+              colors: colors
+            )
+            puts output
+
+            unless options[:dry_run]
+              puts "\nRe-running health check after fixes..."
+              new_results = run_diagnosis(root_dir, doctor_opts)
+
+              output = Molecules::RetroDoctorReporter.format_results(
+                new_results,
+                format: :summary,
+                verbose: false,
+                colors: colors
+              )
+              puts output
+            end
+          end
+
+          def handle_agent_fix(root_dir, doctor_opts, options, config)
+            results = run_diagnosis(root_dir, doctor_opts)
+            remaining = results[:issues]&.reject { |i| i[:type] == :info }
+
+            if remaining.nil? || remaining.empty?
+              puts "\nNo remaining issues for agent to fix."
+              return
+            end
+
+            issue_list = remaining.map { |i|
+              prefix = (i[:type] == :error) ? "ERROR" : "WARNING"
+              "- [#{prefix}] #{i[:message]}#{" (#{i[:location]})" if i[:location]}"
+            }.join("\n")
+
+            provider_model = options[:model] || config.dig("retro", "doctor_agent_model") || "gemini:flash-latest@yolo"
+
+            prompt = <<~PROMPT
+              The following #{remaining.size} retro issues could NOT be auto-fixed and need manual intervention:
+
+              #{issue_list}
+
+              ---
+
+              Fix each issue listed above in the .ace-retros/ directory.
+
+              IMPORTANT RULES:
+              - For invalid ID format issues, inspect the folder name and fix the frontmatter ID to match
+              - For YAML syntax errors, read the file and fix the YAML
+              - For missing opening delimiter, add '---' at the start of the file
+              - Do NOT delete content files — prefer fixing in place
+              - For folder naming issues, rename the folder to match {id}-{slug} convention
+
+              ---
+
+              Run `ace-retro doctor --verbose` to verify all issues are fixed.
+            PROMPT
+
+            puts "\nLaunching agent to fix #{remaining.size} remaining issues..."
+            query_options = {
+              system: nil,
+              timeout: 600,
+              fallback: false
+            }
+
+            response = Ace::LLM::QueryInterface.query(provider_model, prompt, **query_options)
+
+            puts response[:text]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/retro/cli/commands/list.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+
+module Ace
+  module Retro
+    module CLI
+      module Commands
+        # ace-support-cli Command class for ace-retro list
+        class List < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          C = Ace::Support::Items::Atoms::AnsiColors
+          desc "List retros\n\n" \
+            "Lists all retros with optional filtering by status, type, tags, or folder.\n\n" \
+            "Status legend:\n" \
+            "  #{C::YELLOW}○ active#{C::RESET}    #{C::GREEN}✓ done#{C::RESET}"
+          remove_const(:C)
+
+          example [
+            "                           # Active retros (root only, default)",
+            "--in all                   # All retros including archived",
+            "--in archive               # Retros in _archive/",
+            "--status active            # Filter by status",
+            "--type standard            # Filter by type",
+            "--tags sprint,team         # Retros matching any tag",
+            "--in archive --type standard  # Combined filters"
+          ]
+
+          option :status, type: :string, aliases: %w[-s], desc: "Filter by status (active, done)"
+          option :type, type: :string, aliases: %w[-t], desc: "Filter by type (standard, conversation-analysis, self-review)"
+          option :tags, type: :string, aliases: %w[-T], desc: "Filter by tags (comma-separated, any match)"
+          option :in, type: :string, aliases: %w[-i], desc: "Filter by folder (next=root only [default], all=everything, archive)"
+          option :root, type: :string, aliases: %w[-r], desc: "Override root path"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(**options)
+            status = options[:status]
+            type = options[:type]
+            in_folder = options[:in]
+            tags_str = options[:tags]
+            tags = tags_str ? tags_str.split(",").map(&:strip).reject(&:empty?) : []
+
+            manager_opts = {}
+            manager_opts[:root_dir] = options[:root] if options[:root]
+            manager = Ace::Retro::Organisms::RetroManager.new(**manager_opts)
+            list_opts = {status: status, type: type, tags: tags}
+            list_opts[:in_folder] = in_folder if in_folder
+            retros = manager.list(**list_opts)
+
+            puts Ace::Retro::Molecules::RetroDisplayFormatter.format_list(
+              retros, total_count: manager.last_list_total,
+              global_folder_stats: manager.last_folder_counts
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/retro/cli/commands/show.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+
+module Ace
+  module Retro
+    module CLI
+      module Commands
+        # ace-support-cli Command class for ace-retro show
+        class Show < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc <<~DESC.strip
+            Show retro details
+
+            Displays a retro by reference (full 6-char ID or last 3-char shortcut).
+
+          DESC
+
+          example [
+            "q7w                    # Formatted display (default)",
+            "8ppq7w --path          # Print file path only",
+            "q7w --content          # Print raw markdown content"
+          ]
+
+          argument :ref, required: true, desc: "Retro reference (6-char ID or 3-char shortcut)"
+
+          option :path, type: :boolean, desc: "Print file path only"
+          option :content, type: :boolean, desc: "Print raw markdown content"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(ref:, **options)
+            manager = Ace::Retro::Organisms::RetroManager.new
+            retro = manager.show(ref)
+
+            unless retro
+              raise Ace::Support::Cli::Error.new("Retro '#{ref}' not found")
+            end
+
+            if options[:path]
+              puts retro.file_path
+            elsif options[:content]
+              puts File.read(retro.file_path)
+            else
+              puts Ace::Retro::Molecules::RetroDisplayFormatter.format(retro, show_content: true)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/retro/cli/commands/update.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/support/items"
+
+module Ace
+  module Retro
+    module CLI
+      module Commands
+        # ace-support-cli Command class for ace-retro update
+        class Update < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc <<~DESC.strip
+            Update retro metadata and/or move to a folder
+
+            Updates frontmatter fields using set, add, or remove operations.
+            Use --set for scalar fields, --add/--remove for array fields like tags.
+            Use --move-to to relocate to a special folder or back to root.
+          DESC
+
+          example [
+            "q7w --set status=done",
+            'q7w --set status=done --set title="Refined title"',
+            "q7w --add tags=reviewed --remove tags=in-progress",
+            "q7w --set status=done --add tags=shipped",
+            "q7w --set status=done --move-to archive",
+            "q7w --move-to next"
+          ]
+
+          argument :ref, required: true, desc: "Retro reference (6-char ID or 3-char shortcut)"
+
+          option :set, type: :string, repeat: true, desc: "Set field: key=value (can repeat)"
+          option :add, type: :string, repeat: true, desc: "Add to array field: key=value (can repeat)"
+          option :remove, type: :string, repeat: true, desc: "Remove from array field: key=value (can repeat)"
+          option :move_to, type: :string, aliases: %w[-m], desc: "Move to folder (archive, next)"
+
+          option :git_commit, type: :boolean, aliases: %w[--gc], desc: "Auto-commit changes"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(ref:, **options)
+            set_args = Array(options[:set])
+            add_args = Array(options[:add])
+            remove_args = Array(options[:remove])
+            move_to = options[:move_to]
+
+            if set_args.empty? && add_args.empty? && remove_args.empty? && move_to.nil?
+              warn "Error: at least one of --set, --add, --remove, or --move-to is required"
+              warn ""
+              warn "Usage: ace-retro update REF [--set K=V]... [--add K=V]... [--remove K=V]... [--move-to FOLDER]"
+              raise Ace::Support::Cli::Error.new("No update operations specified")
+            end
+
+            set_hash = parse_kv_pairs(set_args)
+            add_hash = parse_kv_pairs(add_args)
+            remove_hash = parse_kv_pairs(remove_args)
+
+            manager = Ace::Retro::Organisms::RetroManager.new
+            retro = manager.update(ref, set: set_hash, add: add_hash, remove: remove_hash, move_to: move_to)
+
+            unless retro
+              raise Ace::Support::Cli::Error.new("Retro '#{ref}' not found")
+            end
+
+            if move_to
+              folder_info = retro.special_folder || "root"
+              puts "Retro updated: #{retro.id} #{retro.title} → #{folder_info}"
+            else
+              puts "Retro updated: #{retro.id} #{retro.title}"
+            end
+
+            if options[:git_commit]
+              commit_paths = move_to ? [manager.root_dir] : [retro.path]
+              intention = if move_to
+                "update retro #{retro.id} and move to #{retro.special_folder || "root"}"
+              else
+                "update retro #{retro.id}"
+              end
+              Ace::Support::Items::Molecules::GitCommitter.commit(
+                paths: commit_paths,
+                intention: intention
+              )
+            end
+          end
+
+          private
+
+          # Parse ["key=value", "key=value2"] into {"key" => typed_value, ...}
+          # Delegates to FieldArgumentParser for type inference (arrays, booleans, numerics).
+          def parse_kv_pairs(args)
+            result = {}
+            args.each do |arg|
+              unless arg.include?("=")
+                raise Ace::Support::Cli::Error.new("Invalid format '#{arg}': expected key=value")
+              end
+
+              parsed = Ace::Support::Items::Atoms::FieldArgumentParser.parse([arg])
+              parsed.each do |key, value|
+                result[key] = if result.key?(key)
+                  Array(result[key]) + Array(value)
+                else
+                  value
+                end
+              end
+            rescue Ace::Support::Items::Atoms::FieldArgumentParser::ParseError => e
+              raise Ace::Support::Cli::Error.new("Invalid argument '#{arg}': #{e.message}")
+            end
+            result
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/retro/cli.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "../retro/version"
+require_relative "cli/commands/create"
+require_relative "cli/commands/show"
+require_relative "cli/commands/list"
+require_relative "cli/commands/update"
+require_relative "cli/commands/doctor"
+
+module Ace
+  module Retro
+    # Flat CLI registry for ace-retro (retrospective management).
+    #
+    # Provides the flat `ace-retro <command>` invocation pattern.
+    module RetroCLI
+      extend Ace::Support::Cli::RegistryDsl
+
+      PROGRAM_NAME = "ace-retro"
+
+      REGISTERED_COMMANDS = [
+        ["create", "Create a new retro"],
+        ["show", "Show retro details"],
+        ["list", "List retros"],
+        ["update", "Update retro metadata (fields and move)"],
+        ["doctor", "Run health checks on retros"]
+      ].freeze
+
+      HELP_EXAMPLES = [
+        'ace-retro create "Sprint Review" --type standard --tags sprint,team',
+        "ace-retro show q7w",
+        "ace-retro list --in archive --status active",
+        "ace-retro update q7w --set status=done --move-to archive",
+        "ace-retro update q7w --set status=done --add tags=reviewed",
+        "ace-retro update q7w --move-to next",
+        "ace-retro doctor --verbose"
+      ].freeze
+
+      register "create", CLI::Commands::Create
+      register "show", CLI::Commands::Show
+      register "list", CLI::Commands::List
+      register "update", CLI::Commands::Update
+      register "doctor", CLI::Commands::Doctor
+
+      version_cmd = Ace::Support::Cli::VersionCommand.build(
+        gem_name: "ace-retro",
+        version: Ace::Retro::VERSION
+      )
+      register "version", version_cmd
+      register "--version", version_cmd
+
+      help_cmd = Ace::Support::Cli::HelpCommand.build(
+        program_name: PROGRAM_NAME,
+        version: Ace::Retro::VERSION,
+        commands: REGISTERED_COMMANDS,
+        examples: HELP_EXAMPLES
+      )
+      register "help", help_cmd
+      register "--help", help_cmd
+      register "-h", help_cmd
+
+      # Entry point for CLI invocation
+      # @param args [Array<String>] Command-line arguments
+      def self.start(args)
+        Ace::Support::Cli::Runner.new(self).call(args: args)
+      end
+    end
+  end
+end

data/lib/ace/retro/models/retro.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Ace
+  module Retro
+    module Models
+      # Value object representing a retrospective
+      # Holds all metadata and content for a single retro
+      Retro = Struct.new(
+        :id,              # Raw 6-char b36ts ID (e.g., "8ppq7w")
+        :status,          # Status string: "active", "done"
+        :title,           # Human-readable title
+        :type,            # Retro type: "standard", "conversation-analysis", "self-review"
+        :tags,            # Array of tag strings
+        :content,         # Body content (markdown, excluding frontmatter)
+        :path,            # Directory path for the retro folder
+        :file_path,       # Full path to the .retro.md file
+        :special_folder,  # Special folder if any (e.g., "_archive", nil)
+        :created_at,      # Time object for creation time
+        :folder_contents, # Array of additional filenames in the retro folder
+        :metadata,        # Additional frontmatter fields as Hash
+        keyword_init: true
+      ) do
+        # Display-friendly representation
+        def to_s
+          "Retro(#{id}: #{title})"
+        end
+
+        # Short reference (last 3 chars of ID)
+        def shortcut
+          id[-3..] if id
+        end
+
+        # Check if retro is in a special folder
+        def special?
+          !special_folder.nil?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "ace/support/fs"
+
+module Ace
+  module Retro
+    module Molecules
+      # Loads and merges configuration for ace-retro from the cascade:
+      # .ace-defaults/retro/config.yml (gem) -> ~/.ace/retro/config.yml (user) -> .ace/retro/config.yml (project)
+      class RetroConfigLoader
+        DEFAULT_ROOT_DIR = ".ace-retros"
+
+        # Load configuration with cascade merge
+        # @param gem_root [String] Path to the ace-retro gem root
+        # @return [Hash] Merged configuration
+        def self.load(gem_root: nil)
+          gem_root ||= File.expand_path("../../../..", __dir__)
+          # lib/ace/retro/molecules/ → 4 levels up to gem root
+          new(gem_root: gem_root).load
+        end
+
+        def initialize(gem_root:)
+          @gem_root = gem_root
+        end
+
+        # Load and merge configuration
+        # @return [Hash] Merged configuration
+        def load
+          config = load_defaults
+          config = deep_merge(config, load_user_config)
+          deep_merge(config, load_project_config)
+        end
+
+        # Get the root directory for retros
+        # @param config [Hash] Configuration hash
+        # @return [String] Absolute path to retros root directory
+        def self.root_dir(config = nil)
+          config ||= load
+          dir = config.dig("retro", "root_dir") || DEFAULT_ROOT_DIR
+
+          if dir.start_with?("/")
+            dir
+          else
+            File.join(Ace::Support::Fs::Molecules::ProjectRootFinder.find_or_current, dir)
+          end
+        end
+
+        private
+
+        def load_defaults
+          path = File.join(@gem_root, ".ace-defaults", "retro", "config.yml")
+          load_yaml(path) || {}
+        end
+
+        def load_user_config
+          path = File.join(Dir.home, ".ace", "retro", "config.yml")
+          load_yaml(path) || {}
+        end
+
+        def load_project_config
+          path = File.join(Ace::Support::Fs::Molecules::ProjectRootFinder.find_or_current, ".ace", "retro", "config.yml")
+          load_yaml(path) || {}
+        end
+
+        def load_yaml(path)
+          return nil unless File.exist?(path)
+
+          YAML.safe_load_file(path, permitted_classes: [Date, Time, Symbol])
+        rescue Errno::ENOENT
+          nil
+        rescue Psych::SyntaxError => e
+          warn "Warning: ace-retro config parse error in #{path}: #{e.message}"
+          nil
+        end
+
+        def deep_merge(base, override)
+          return base unless override.is_a?(Hash)
+
+          result = base.dup
+          override.each do |key, value|
+            result[key] = if result[key].is_a?(Hash) && value.is_a?(Hash)
+              deep_merge(result[key], value)
+            else
+              value
+            end
+          end
+          result
+        end
+      end
+    end
+  end
+end