ace-idea 0.18.0

data/lib/ace/idea/atoms/idea_validation_rules.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "idea_id_formatter"
+
+module Ace
+  module Idea
+    module Atoms
+      # Pure validation predicates and constants for idea health checking.
+      # Used by doctor validators to determine correctness of frontmatter,
+      # file structure, and scope/status consistency.
+      module IdeaValidationRules
+        VALID_STATUSES = %w[pending in-progress done obsolete].freeze
+        TERMINAL_STATUSES = %w[done obsolete].freeze
+        REQUIRED_FIELDS = %w[id status title].freeze
+        RECOMMENDED_FIELDS = %w[tags created_at].freeze
+
+        # Check if a status string is valid
+        # @param status [String] Status to validate
+        # @return [Boolean]
+        def self.valid_status?(status)
+          VALID_STATUSES.include?(status.to_s)
+        end
+
+        # Check if a status is terminal (belongs in _archive)
+        # @param status [String] Status to check
+        # @return [Boolean]
+        def self.terminal_status?(status)
+          TERMINAL_STATUSES.include?(status.to_s)
+        end
+
+        # Check if an ID string is a valid b36ts idea ID
+        # @param id [String] ID to validate
+        # @return [Boolean]
+        def self.valid_id?(id)
+          IdeaIdFormatter.valid?(id)
+        end
+
+        # Check if scope (special folder) is consistent with status
+        # @param status [String] Idea status
+        # @param special_folder [String, nil] Special folder name (e.g., "_archive", "_maybe")
+        # @return [Array<Hash>] List of inconsistency issues (empty if consistent)
+        def self.scope_consistent?(status, special_folder)
+          issues = []
+
+          if terminal_status?(status) && special_folder != "_archive"
+            issues << {
+              type: :warning,
+              message: "Idea with terminal status '#{status}' not in _archive/"
+            }
+          end
+
+          if special_folder == "_archive" && !terminal_status?(status) && status
+            issues << {
+              type: :warning,
+              message: "Idea in _archive/ but status is '#{status}' (expected terminal status)"
+            }
+          end
+
+          if special_folder == "_maybe" && terminal_status?(status)
+            issues << {
+              type: :warning,
+              message: "Idea in _maybe/ with terminal status '#{status}' (should be in _archive/)"
+            }
+          end
+
+          issues
+        end
+
+        # Return list of missing required fields from frontmatter
+        # @param frontmatter [Hash] Parsed frontmatter
+        # @return [Array<String>] Names of missing required fields
+        def self.missing_required_fields(frontmatter)
+          return REQUIRED_FIELDS.dup if frontmatter.nil? || !frontmatter.is_a?(Hash)
+
+          REQUIRED_FIELDS.select { |field| frontmatter[field].nil? || frontmatter[field].to_s.strip.empty? }
+        end
+
+        # Return list of missing recommended fields from frontmatter
+        # @param frontmatter [Hash] Parsed frontmatter
+        # @return [Array<String>] Names of missing recommended fields
+        def self.missing_recommended_fields(frontmatter)
+          return RECOMMENDED_FIELDS.dup if frontmatter.nil? || !frontmatter.is_a?(Hash)
+
+          RECOMMENDED_FIELDS.select { |field| frontmatter[field].nil? }
+        end
+      end
+    end
+  end
+end

data/lib/ace/idea/atoms/slug_sanitizer_adapter.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# This file exists for explicit require - the actual implementation
+# lives in ace-support-items. We use it via require "ace/support/items".
+# This adapter ensures the dependency is clear.
+require "ace/support/items"

data/lib/ace/idea/cli/commands/create.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+
+module Ace
+  module Idea
+    module CLI
+      module Commands
+        # ace-support-cli Command class for ace-idea create
+        class Create < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc <<~DESC.strip
+            Create a new idea
+
+            Captures a new idea with optional title, tags, and folder placement.
+            Content can be provided as a positional argument or via --clipboard.
+
+          DESC
+
+          example [
+            '"Dark mode for night coding"                          # Basic capture',
+            '"Dark mode" --title "Dark mode" --tags ux,design      # With metadata',
+            '"raw thought" --move-to maybe                         # Place in _maybe/',
+            "--clipboard --llm-enhance --move-to maybe             # From clipboard with LLM",
+            '"rough idea" --dry-run                                # Preview without writing'
+          ]
+
+          argument :content, required: false, desc: "Idea content (positional)"
+
+          option :title, type: :string, aliases: %w[-t], desc: "Explicit title"
+          option :tags, type: :string, aliases: %w[-T], desc: "Comma-separated tags"
+          option :"move-to", type: :string, aliases: %w[-m], desc: "Target folder (e.g. next, maybe, archive)"
+          option :clipboard, type: :boolean, aliases: %w[-c], desc: "Capture content from clipboard"
+          option :"llm-enhance", type: :boolean, aliases: %w[-l], desc: "Enhance content with LLM"
+          option :"dry-run", type: :boolean, aliases: %w[-n], desc: "Preview without writing"
+
+          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(content: nil, **options)
+            clipboard = options[:clipboard]
+            llm_enhance = options[:"llm-enhance"]
+            move_to = options[:"move-to"]
+            title = options[:title]
+            tags_str = options[:tags]
+            dry_run = options[:"dry-run"]
+
+            # Parse tags from comma-separated string
+            tags = tags_str ? tags_str.split(",").map(&:strip).reject(&:empty?) : []
+
+            # Require content or clipboard
+            if content.nil? && !clipboard
+              warn "Error: provide content or --clipboard"
+              warn ""
+              warn "Usage: ace-idea create [CONTENT] [--clipboard] [--title T] [--tags T1,T2] [--move-to FOLDER]"
+              raise Ace::Support::Cli::Error.new("Content or --clipboard required")
+            end
+
+            if dry_run
+              puts "Would create idea:"
+              puts "  Content:  #{content || "(from clipboard)"}"
+              puts "  Title:    #{title || "(auto-generated)"}"
+              puts "  Tags:     #{tags.any? ? tags.join(", ") : "(none)"}"
+              puts "  Folder:   #{move_to ? "_#{move_to.delete_prefix("_")}" : "(root)"}"
+              puts "  LLM:      #{llm_enhance ? "yes" : "no"}"
+              return
+            end
+
+            manager = Ace::Idea::Organisms::IdeaManager.new
+            idea = manager.create(
+              content,
+              title: title,
+              tags: tags,
+              move_to: move_to,
+              clipboard: clipboard || false,
+              llm_enhance: llm_enhance || false
+            )
+
+            folder_info = idea.special_folder ? " (#{idea.special_folder})" : ""
+            puts "Idea created: #{idea.id} #{idea.title}#{folder_info}"
+            puts "  Path: #{idea.file_path}"
+
+            if options[:git_commit]
+              Ace::Support::Items::Molecules::GitCommitter.commit(
+                paths: [idea.path],
+                intention: "create idea #{idea.id}"
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require "ace/llm"
+require_relative "../../organisms/idea_doctor"
+require_relative "../../molecules/idea_doctor_fixer"
+require_relative "../../molecules/idea_doctor_reporter"
+require_relative "../../molecules/idea_config_loader"
+
+module Ace
+  module Idea
+    module CLI
+      module Commands
+        # ace-support-cli Command class for ace-idea doctor
+        #
+        # Runs health checks on ideas and optionally auto-fixes issues.
+        class Doctor < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc <<~DESC.strip
+            Run health checks on ideas
+
+            Validates frontmatter, file structure, and scope/status consistency
+            across all ideas 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::IdeaConfigLoader.load
+            root_dir = Molecules::IdeaConfigLoader.root_dir(config)
+
+            unless Dir.exist?(root_dir)
+              puts "Error: Ideas directory not found: #{root_dir}"
+              raise Ace::Support::Cli::Error.new("Ideas directory not found")
+            end
+
+            # Normalize options
+            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)
+
+            # Filter errors-only
+            if options[:errors_only] && results[:issues]
+              results[:issues] = results[:issues].select { |i| i[:type] == :error }
+            end
+
+            output = Molecules::IdeaDoctorReporter.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::IdeaDoctor.new(root_dir, doctor_opts)
+            doctor.run_diagnosis
+          end
+
+          def handle_auto_fix(results, root_dir, doctor_opts, options, colors)
+            doctor = Organisms::IdeaDoctor.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::IdeaDoctorFixer.new(dry_run: options[:dry_run], root_dir: root_dir)
+            fix_results = fixer.fix_issues(fixable_issues)
+
+            output = Molecules::IdeaDoctorReporter.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::IdeaDoctorReporter.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("idea", "doctor_agent_model") || "gemini:flash-latest@yolo"
+
+            prompt = <<~PROMPT
+              The following #{remaining.size} idea issues could NOT be auto-fixed and need manual intervention:
+
+              #{issue_list}
+
+              ---
+
+              Fix each issue listed above in the .ace-ideas/ 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-idea 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/idea/cli/commands/list.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+
+module Ace
+  module Idea
+    module CLI
+      module Commands
+        # ace-support-cli Command class for ace-idea list
+        class List < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          C = Ace::Support::Items::Atoms::AnsiColors
+          desc "List ideas\n\n" \
+            "Lists all ideas with optional filtering by status, tags, or folder.\n\n" \
+            "Status legend:\n" \
+            "  #{C::RESET}○ pending    #{C::YELLOW}▶ in-progress#{C::RESET}    #{C::GREEN}✓ done#{C::RESET}    #{C::DIM}✗ obsolete#{C::RESET}"
+          remove_const(:C)
+
+          example [
+            "                           # Active ideas (root only, default)",
+            "--in all                   # All ideas including archived/maybe",
+            "--in maybe                 # Ideas in _maybe/",
+            "--status pending           # Filter by status",
+            "--tags ux,design           # Ideas matching any tag",
+            "--in next --status pending # Combined filters",
+            "--filter status:pending --filter tags:ux|design  # Generic filters"
+          ]
+
+          option :status, type: :string, aliases: %w[-s], desc: "Filter by status (pending, in-progress, done, obsolete)"
+          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, maybe, archive)"
+          option :root, type: :string, aliases: %w[-r], desc: "Override root path (subpath within ideas root)"
+          option :filter, type: :array, aliases: %w[-f], desc: "Filter by key:value (repeatable, supports key:a|b and key:!value)"
+
+          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]
+            in_folder = options[:in]
+            root = options[:root]
+            tags_str = options[:tags]
+            tags = tags_str ? tags_str.split(",").map(&:strip).reject(&:empty?) : []
+            filters = options[:filter]
+
+            manager = Ace::Idea::Organisms::IdeaManager.new
+            list_opts = {status: status, tags: tags, root: root, filters: filters}
+            list_opts[:in_folder] = in_folder if in_folder
+            ideas = manager.list(**list_opts)
+
+            puts Ace::Idea::Molecules::IdeaDisplayFormatter.format_list(
+              ideas, total_count: manager.last_list_total,
+              global_folder_stats: manager.last_folder_counts
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+
+module Ace
+  module Idea
+    module CLI
+      module Commands
+        # ace-support-cli Command class for ace-idea show
+        class Show < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc <<~DESC.strip
+            Show idea details
+
+            Displays an idea 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: "Idea 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::Idea::Organisms::IdeaManager.new
+            idea = manager.show(ref)
+
+            unless idea
+              raise Ace::Support::Cli::Error.new("Idea '#{ref}' not found")
+            end
+
+            if options[:path]
+              puts idea.file_path
+            elsif options[:content]
+              puts File.read(idea.file_path)
+            else
+              puts Ace::Idea::Molecules::IdeaDisplayFormatter.format(idea, show_content: true)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/idea/cli/commands/status.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+
+module Ace
+  module Idea
+    module CLI
+      module Commands
+        # ace-support-cli Command class for ace-idea status
+        class Status < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc <<~DESC.strip
+            Show idea status overview
+
+            Displays up-next ideas, summary stats, and recently completed ideas.
+          DESC
+
+          example [
+            "                             # Default status view",
+            "--up-next-limit 5            # Show 5 up-next ideas",
+            "--recently-done-limit 3      # Show 3 recently done ideas"
+          ]
+
+          option :up_next_limit, type: :integer, desc: "Max up-next ideas to show"
+          option :recently_done_limit, type: :integer, desc: "Max recently-done ideas to show"
+
+          def call(**options)
+            manager = Ace::Idea::Organisms::IdeaManager.new
+            all_ideas = manager.list(in_folder: "all")
+
+            config = Ace::Idea::Molecules::IdeaConfigLoader.load
+            limits = resolve_limits(config, options)
+
+            categorized = Ace::Support::Items::Molecules::StatusCategorizer.categorize(
+              all_ideas,
+              up_next_limit: limits[:up_next],
+              recently_done_limit: limits[:recently_done],
+              pending_statuses: %w[pending],
+              done_statuses: %w[done]
+            )
+
+            puts Ace::Idea::Molecules::IdeaDisplayFormatter.format_status(
+              categorized, all_ideas: all_ideas
+            )
+          end
+
+          private
+
+          def resolve_limits(config, options)
+            status_config = config.dig("idea", "status") || {}
+            {
+              up_next: (options[:up_next_limit] || status_config["up_next_limit"] || 7).to_i,
+              recently_done: (options[:recently_done_limit] || status_config["recently_done_limit"] || 7).to_i
+            }
+          end
+        end
+      end
+    end
+  end
+end