ace-idea 0.18.0

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/support/items"
+
+module Ace
+  module Idea
+    module CLI
+      module Commands
+        # ace-support-cli Command class for ace-idea update
+        class Update < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc <<~DESC.strip
+            Update idea 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=in-progress --set title="Refined title"',
+            "q7w --add tags=implemented --remove tags=pending-review",
+            "q7w --set status=done --add tags=shipped",
+            "q7w --set status=done --move-to archive",
+            "q7w --move-to next"
+          ]
+
+          argument :ref, required: true, desc: "Idea 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, maybe, anytime, 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-idea 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::Idea::Organisms::IdeaManager.new
+            idea = manager.update(ref, set: set_hash, add: add_hash, remove: remove_hash, move_to: move_to)
+
+            unless idea
+              raise Ace::Support::Cli::Error.new("Idea '#{ref}' not found")
+            end
+
+            if move_to
+              folder_info = idea.special_folder || "root"
+              puts "Idea updated: #{idea.id} #{idea.title} → #{folder_info}"
+            else
+              puts "Idea updated: #{idea.id} #{idea.title}"
+            end
+
+            if options[:git_commit]
+              commit_paths = move_to ? [manager.root_dir] : [idea.path]
+              intention = if move_to
+                "update idea #{idea.id} and move to #{idea.special_folder || "root"}"
+              else
+                "update idea #{idea.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
+
+              # parse([arg]) returns {key => typed_value}
+              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/idea/cli.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "../idea/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"
+require_relative "cli/commands/status"
+
+module Ace
+  module Idea
+    # Flat CLI registry for ace-idea (idea management).
+    #
+    # Provides the flat `ace-idea <command>` invocation pattern.
+    module IdeaCLI
+      extend Ace::Support::Cli::RegistryDsl
+
+      PROGRAM_NAME = "ace-idea"
+
+      REGISTERED_COMMANDS = [
+        ["create", "Create a new idea"],
+        ["show", "Show idea details"],
+        ["list", "List ideas"],
+        ["update", "Update idea metadata (fields and move)"],
+        ["doctor", "Run health checks on ideas"],
+        ["status", "Show idea status overview"]
+      ].freeze
+
+      HELP_EXAMPLES = [
+        'ace-idea create "Dark mode" --tags ux,design --move-to next',
+        "ace-idea show q7w",
+        "ace-idea list --in maybe --status pending",
+        "ace-idea update q7w --set status=done --move-to archive",
+        "ace-idea update q7w --set status=done --add tags=shipped",
+        "ace-idea update q7w --move-to next",
+        "ace-idea doctor --auto-fix",
+        "ace-idea status",
+        "ace-idea status --up-next-limit 5"
+      ].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
+      register "status", CLI::Commands::Status
+
+      version_cmd = Ace::Support::Cli::VersionCommand.build(
+        gem_name: "ace-idea",
+        version: Ace::Idea::VERSION
+      )
+      register "version", version_cmd
+      register "--version", version_cmd
+
+      help_cmd = Ace::Support::Cli::HelpCommand.build(
+        program_name: PROGRAM_NAME,
+        version: Ace::Idea::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/idea/models/idea.rb

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

data/lib/ace/idea/molecules/idea_clipboard_reader.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+# Clipboard reader adapted from ace-taskflow's ClipboardReader.
+# Kept independent (no ace-taskflow dependency) as per task spec:
+# "Shared utilities from ace-taskflow are duplicated rather than centralized."
+
+begin
+  require "clipboard"
+rescue LoadError
+  # clipboard gem not available - will gracefully degrade
+end
+
+begin
+  require "ace/support/mac_clipboard"
+rescue LoadError
+  # Not available on this platform
+end
+
+module Ace
+  module Idea
+    module Molecules
+      # Reads content from the system clipboard for idea capture.
+      # Supports: plain text, RTF, HTML (as text), images (as attachments).
+      class IdeaClipboardReader
+        MAX_CONTENT_SIZE = 100 * 1024 # 100KB
+
+        # Read clipboard content
+        # @return [Hash] Result with :success, :content, :type, :attachments keys
+        def self.read
+          if macos? && macos_clipboard_available?
+            read_macos
+          else
+            read_generic
+          end
+        end
+
+        private
+
+        def self.macos?
+          RUBY_PLATFORM.include?("darwin")
+        end
+
+        def self.macos_clipboard_available?
+          defined?(Ace::Support::MacClipboard)
+        end
+
+        def self.read_macos
+          raw = Ace::Support::MacClipboard::Reader.read
+          return {success: false, error: raw[:error]} unless raw[:success]
+
+          parsed = Ace::Support::MacClipboard::ContentParser.parse(raw)
+
+          has_attachments = parsed[:attachments].any?
+          type = has_attachments ? :rich : :text
+          file_attachments = parsed[:attachments].select { |a| a[:type] == :file }
+
+          {
+            success: true,
+            platform: :macos,
+            type: type,
+            content: parsed[:text],
+            attachments: parsed[:attachments],
+            files: file_attachments.map { |a| a[:source_path] }
+          }
+        rescue
+          read_generic
+        end
+
+        def self.read_generic
+          unless defined?(Clipboard)
+            return {
+              success: false,
+              error: "Clipboard gem not available. Install 'clipboard' gem for clipboard support."
+            }
+          end
+
+          content = Clipboard.paste
+
+          if content.nil? || content.strip.empty?
+            return {
+              success: false,
+              error: "Clipboard is empty. Provide text argument or copy content to clipboard."
+            }
+          end
+
+          if content.bytesize > MAX_CONTENT_SIZE
+            return {
+              success: false,
+              error: "Clipboard content too large (#{content.bytesize} bytes, max #{MAX_CONTENT_SIZE} bytes)"
+            }
+          end
+
+          if content.encoding == Encoding::ASCII_8BIT || content.include?("\x00")
+            return {
+              success: false,
+              error: "Clipboard contains binary data. Only text content is supported."
+            }
+          end
+
+          {
+            success: true,
+            platform: :generic,
+            type: :text,
+            content: content,
+            attachments: [],
+            files: []
+          }
+        rescue => e
+          {
+            success: false,
+            error: "Unable to read clipboard: #{e.message}"
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ace/idea/molecules/idea_config_loader.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "ace/support/fs"
+
+module Ace
+  module Idea
+    module Molecules
+      # Loads and merges configuration for ace-idea from the cascade:
+      # .ace-defaults/idea/config.yml (gem) -> ~/.ace/idea/config.yml (user) -> .ace/idea/config.yml (project)
+      class IdeaConfigLoader
+        DEFAULT_ROOT_DIR = ".ace-ideas"
+
+        # Load configuration with cascade merge
+        # @param gem_root [String] Path to the ace-idea gem root
+        # @return [Hash] Merged configuration
+        def self.load(gem_root: nil)
+          gem_root ||= File.expand_path("../../../..", __dir__)
+          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 ideas
+        # @param config [Hash] Configuration hash
+        # @return [String] Absolute path to ideas root directory
+        def self.root_dir(config = nil)
+          config ||= load
+          dir = config.dig("idea", "root_dir") || DEFAULT_ROOT_DIR
+
+          # Make absolute if relative
+          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", "idea", "config.yml")
+          load_yaml(path) || {}
+        end
+
+        def load_user_config
+          path = File.join(Dir.home, ".ace", "idea", "config.yml")
+          load_yaml(path) || {}
+        end
+
+        def load_project_config
+          path = File.join(Ace::Support::Fs::Molecules::ProjectRootFinder.find_or_current, ".ace", "idea", "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-idea 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

data/lib/ace/idea/molecules/idea_creator.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+require_relative "../atoms/idea_id_formatter"
+require_relative "../atoms/idea_file_pattern"
+require_relative "../atoms/idea_frontmatter_defaults"
+require_relative "../atoms/slug_sanitizer_adapter"
+require_relative "idea_loader"
+require_relative "idea_llm_enhancer"
+require_relative "idea_clipboard_reader"
+
+module Ace
+  module Idea
+    module Molecules
+      # Creates new ideas with b36ts IDs, folder/file creation.
+      # Supports --clipboard, --llm-enhance, and --move-to options.
+      class IdeaCreator
+        # @param root_dir [String] Root directory for ideas
+        # @param config [Hash] Configuration hash
+        def initialize(root_dir:, config: {})
+          @root_dir = root_dir
+          @config = config
+        end
+
+        # Create a new idea
+        # @param content [String] Raw idea content/text
+        # @param title [String, nil] Optional title (extracted from content if nil)
+        # @param tags [Array<String>] Tags for the idea
+        # @param move_to [String, nil] Target folder for the idea
+        # @param clipboard [Boolean] Capture from system clipboard
+        # @param llm_enhance [Boolean] Enhance with LLM
+        # @param time [Time] Creation time (default: now)
+        # @return [Idea] Created idea object
+        def create(content = nil, title: nil, tags: [], move_to: nil,
+          clipboard: false, llm_enhance: false, time: Time.now.utc)
+          # Step 1: Gather content
+          body, attachments_to_save = gather_content(content, clipboard: clipboard)
+
+          if body.nil? || body.strip.empty?
+            raise ArgumentError, "No content provided. Provide text or use --clipboard."
+          end
+
+          # Step 2: Optionally enhance with LLM
+          enhanced_body = if llm_enhance
+            enhance_with_llm(body, config: @config)
+          else
+            body
+          end
+
+          # Step 3: Generate ID and slugs
+          id = Atoms::IdeaIdFormatter.generate(time)
+          slug_title = title || extract_title(enhanced_body)
+          folder_slug = generate_folder_slug(slug_title)
+          file_slug = generate_file_slug(slug_title)
+
+          # Step 4: Determine target directory
+          target_dir = determine_target_dir(move_to)
+          FileUtils.mkdir_p(target_dir)
+
+          # Step 5: Create idea folder (ensure unique name if ID collision occurs)
+          folder_name, _ = unique_folder_name(id, folder_slug, target_dir)
+          idea_dir = File.join(target_dir, folder_name)
+          FileUtils.mkdir_p(idea_dir)
+
+          # Step 6: Handle attachments
+          if attachments_to_save.any?
+            enhanced_body = save_attachments_and_inject_refs(attachments_to_save, idea_dir, enhanced_body)
+          end
+
+          # Step 7: Write spec file
+          effective_title = title || extract_title(enhanced_body) || "Untitled Idea"
+          frontmatter = Atoms::IdeaFrontmatterDefaults.build(
+            id: id,
+            title: effective_title,
+            tags: tags,
+            status: "pending",
+            created_at: time
+          )
+
+          file_content = build_file_content(frontmatter, enhanced_body, effective_title)
+          spec_filename = Atoms::IdeaFilePattern.spec_filename(id, file_slug)
+          spec_file = File.join(idea_dir, spec_filename)
+          File.write(spec_file, file_content)
+
+          # Step 8: Load and return the created idea
+          loader = IdeaLoader.new
+          special_folder = Ace::Support::Items::Atoms::SpecialFolderDetector.detect_in_path(
+            idea_dir, root: @root_dir
+          )
+          loader.load(idea_dir, id: id, special_folder: special_folder)
+        end
+
+        private
+
+        def gather_content(content, clipboard: false)
+          attachments = []
+
+          if clipboard
+            clipboard_result = IdeaClipboardReader.read
+            unless clipboard_result[:success]
+              raise ArgumentError, clipboard_result[:error]
+            end
+
+            clipboard_content = clipboard_result[:content]
+            clipboard_attachments = clipboard_result[:attachments] || []
+
+            # Merge clipboard content with provided content
+            if content.nil? || content.strip.empty?
+              content = clipboard_content
+            elsif clipboard_content && !clipboard_content.strip.empty?
+              content = "#{content}\n\n#{clipboard_content}"
+            end
+
+            attachments = clipboard_attachments
+          end
+
+          [content, attachments]
+        end
+
+        def enhance_with_llm(content, config: {})
+          enhancer = IdeaLlmEnhancer.new(config: config)
+          result = enhancer.enhance(content)
+
+          if result[:success]
+            result[:content]
+          else
+            # Fallback to original content on LLM failure
+            content
+          end
+        end
+
+        # 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::IdeaFilePattern.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::IdeaFilePattern.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? ? "idea" : 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? ? "idea" : s }
+        end
+
+        def extract_title(content)
+          return nil if content.nil? || content.strip.empty?
+
+          # Try to get first heading
+          match = content.match(/^#\s+(.+)$/)
+          return match[1].strip if match
+
+          # Fall back to first line (max 50 chars)
+          first_line = content.split("\n").first&.strip
+          return nil if first_line.nil? || first_line.empty?
+
+          (first_line.length > 50) ? first_line[0..49] : first_line
+        end
+
+        def determine_target_dir(move_to)
+          if move_to
+            if Ace::Support::Items::Atoms::SpecialFolderDetector.virtual_filter?(move_to)
+              raise ArgumentError, "Cannot move to virtual filter '#{move_to}' — it is not a physical folder"
+            end
+            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 save_attachments_and_inject_refs(attachments, idea_dir, content)
+          refs = []
+
+          attachments.each do |attachment|
+            next unless attachment[:source_path] || attachment[:data]
+
+            raw_name = attachment[:filename] || File.basename(attachment[:source_path].to_s)
+            filename = File.basename(raw_name.to_s)
+            if filename.empty? || filename.include?("/") || filename.include?("\0")
+              warn "Warning: Skipping attachment with unsafe filename: #{raw_name.inspect}"
+              next
+            end
+            dest_path = File.join(idea_dir, filename)
+
+            if attachment[:source_path] && File.exist?(attachment[:source_path])
+              FileUtils.cp(attachment[:source_path], dest_path)
+            elsif attachment[:data]
+              File.binwrite(dest_path, attachment[:data])
+            end
+
+            # Add markdown reference based on type
+            refs << case attachment[:type]
+            when :image
+              "![#{filename}](#{filename})"
+            else
+              "[#{filename}](#{filename})"
+            end
+          rescue => e
+            warn "Warning: Failed to save attachment #{filename}: #{e.message}"
+          end
+
+          if refs.any?
+            "#{content}\n\n## Attachments\n\n#{refs.join("\n")}"
+          else
+            content
+          end
+        end
+
+        def build_file_content(frontmatter, body, title)
+          fm_str = Atoms::IdeaFrontmatterDefaults.serialize(frontmatter)
+
+          # Check if body already has a title heading
+          if body.match?(/^#\s+/)
+            "#{fm_str}\n\n#{body}\n"
+          else
+            "#{fm_str}\n\n# #{title}\n\n#{body}\n"
+          end
+        end
+      end
+    end
+  end
+end