ace-idea 0.18.0

data/lib/ace/idea/organisms/idea_manager.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "../atoms/idea_frontmatter_defaults"
+require_relative "../molecules/idea_config_loader"
+require_relative "../molecules/idea_scanner"
+require_relative "../molecules/idea_resolver"
+require_relative "../molecules/idea_loader"
+require_relative "../molecules/idea_creator"
+require_relative "../molecules/idea_mover"
+
+module Ace
+  module Idea
+    module Organisms
+      # Orchestrates all idea CRUD operations.
+      # Entry point for idea management with config-driven root directory.
+      class IdeaManager
+        attr_reader :last_list_total, :last_folder_counts
+
+        # @param root_dir [String, nil] Override root directory for ideas
+        # @param config [Hash, nil] Override configuration
+        def initialize(root_dir: nil, config: nil)
+          @config = config || load_config
+          @root_dir = root_dir || resolve_root_dir
+        end
+
+        # Create a new idea
+        # @param content [String, nil] Idea content
+        # @param title [String, nil] Optional explicit title
+        # @param tags [Array<String>] Tags
+        # @param move_to [String, nil] Target folder
+        # @param clipboard [Boolean] Capture from clipboard
+        # @param llm_enhance [Boolean] Enhance with LLM
+        # @return [Idea] Created idea
+        def create(content = nil, title: nil, tags: [], move_to: nil,
+          clipboard: false, llm_enhance: false)
+          ensure_root_dir
+          creator = Molecules::IdeaCreator.new(root_dir: @root_dir, config: @config)
+          creator.create(content, title: title, tags: tags, move_to: move_to,
+            clipboard: clipboard, llm_enhance: llm_enhance)
+        end
+
+        # Create an idea from clipboard
+        # @param llm_enhance [Boolean] Enhance with LLM after clipboard capture
+        # @param move_to [String, nil] Target folder
+        # @return [Idea] Created idea
+        def create_from_clipboard(llm_enhance: false, move_to: nil)
+          create(nil, clipboard: true, llm_enhance: llm_enhance, move_to: move_to)
+        end
+
+        # Show (load) a single idea by reference
+        # @param ref [String] Full ID (6 chars) or suffix shortcut (3 chars)
+        # @return [Idea, nil] Loaded idea or nil if not found
+        def show(ref)
+          resolver = Molecules::IdeaResolver.new(@root_dir)
+          scan_result = resolver.resolve(ref)
+          return nil unless scan_result
+
+          loader = Molecules::IdeaLoader.new
+          loader.load(scan_result.dir_path,
+            id: scan_result.id,
+            special_folder: scan_result.special_folder)
+        end
+
+        # List ideas with optional filtering
+        # @param status [String, nil] Filter by status
+        # @param in_folder [String, nil] Filter by special folder (default: "next" = root items only)
+        # @param tags [Array<String>] Filter by tags (any match)
+        # @param root [String, nil] Override root path (subpath within root_dir)
+        # @param filters [Array<String>, nil] Generic filter strings (e.g., ["status:pending", "tags:ux|design"])
+        # @return [Array<Idea>] List of ideas
+        def list(status: nil, in_folder: "next", tags: [], root: nil, filters: nil)
+          scan_root = if root
+            candidate = File.expand_path(File.join(@root_dir, root))
+            root_real = File.expand_path(@root_dir)
+            unless candidate.start_with?(root_real + File::SEPARATOR) || candidate == root_real
+              raise ArgumentError, "Path traversal detected in --root option"
+            end
+            candidate
+          else
+            @root_dir
+          end
+          scanner = Molecules::IdeaScanner.new(scan_root)
+          scan_results = scanner.scan_in_folder(in_folder)
+          @last_list_total = scanner.last_scan_total
+          @last_folder_counts = scanner.last_folder_counts
+
+          loader = Molecules::IdeaLoader.new
+          ideas = scan_results.filter_map do |sr|
+            loader.load(sr.dir_path, id: sr.id, special_folder: sr.special_folder)
+          end
+
+          # Apply legacy filters (backward-compatible)
+          ideas = ideas.select { |i| i.status == status } if status
+          ideas = filter_by_tags(ideas, tags) if tags.any?
+
+          # Apply generic --filter specs via FilterApplier
+          if filters && !filters.empty?
+            filter_specs = Ace::Support::Items::Atoms::FilterParser.parse(filters)
+            ideas = Ace::Support::Items::Molecules::FilterApplier.apply(ideas, filter_specs, value_accessor: method(:idea_value_accessor))
+          end
+
+          ideas
+        end
+
+        # Update an idea's fields and optionally move to a folder.
+        # @param ref [String] Idea reference
+        # @param set [Hash] Fields to set (key => value)
+        # @param add [Hash] Fields to add to (for arrays like tags)
+        # @param remove [Hash] Fields to remove from (for arrays)
+        # @param move_to [String, nil] Target folder to move to (archive, maybe, anytime, next/root//)
+        # @return [Idea, nil] Updated idea or nil if not found
+        def update(ref, set: {}, add: {}, remove: {}, move_to: nil)
+          scan_result = resolve_scan_result(ref)
+          return nil unless scan_result
+
+          loader = Molecules::IdeaLoader.new
+          idea = loader.load(scan_result.dir_path,
+            id: scan_result.id,
+            special_folder: scan_result.special_folder)
+          return nil unless idea
+
+          # Apply field updates if any
+          has_field_updates = [set, add, remove].any? { |h| h && !h.empty? }
+          update_idea_file(idea, set: set, add: add, remove: remove) if has_field_updates
+
+          # Apply move if requested
+          current_path = idea.path
+          current_special = idea.special_folder
+          if move_to
+            mover = Molecules::IdeaMover.new(@root_dir)
+            new_path = if Ace::Support::Items::Atoms::SpecialFolderDetector.move_to_root?(move_to)
+              mover.move_to_root(idea)
+            else
+              archive_date = parse_archive_date(idea)
+              mover.move(idea, to: move_to, date: archive_date)
+            end
+            current_path = new_path
+            current_special = Ace::Support::Items::Atoms::SpecialFolderDetector.detect_in_path(
+              new_path, root: @root_dir
+            )
+          end
+
+          # Reload and return updated idea
+          loader.load(current_path, id: idea.id, special_folder: current_special)
+        end
+
+        # Get the root directory
+        # @return [String] Absolute path to ideas root
+        attr_reader :root_dir
+
+        private
+
+        def load_config
+          gem_root = File.expand_path("../../../..", __dir__)
+          Molecules::IdeaConfigLoader.load(gem_root: gem_root)
+        end
+
+        def resolve_root_dir
+          Molecules::IdeaConfigLoader.root_dir(@config)
+        end
+
+        def ensure_root_dir
+          require "fileutils"
+          FileUtils.mkdir_p(@root_dir) unless Dir.exist?(@root_dir)
+        end
+
+        def resolve_scan_result(ref)
+          resolver = Molecules::IdeaResolver.new(@root_dir)
+          resolver.resolve(ref)
+        end
+
+        def filter_by_tags(ideas, tags)
+          return ideas if tags.empty?
+
+          ideas.select do |idea|
+            tags.any? { |tag| idea.tags.include?(tag) }
+          end
+        end
+
+        def update_idea_file(idea, set:, add:, remove:)
+          content = File.read(idea.file_path)
+          frontmatter, body = Ace::Support::Items::Atoms::FrontmatterParser.parse(content)
+          # Strip leading newline from body so rebuild doesn't double-space
+          body = body.sub(/\A\n/, "")
+
+          # Apply set operations
+          set.each { |k, v| frontmatter[k.to_s] = v }
+
+          # Apply add operations (for arrays)
+          add.each do |k, v|
+            key = k.to_s
+            current = Array(frontmatter[key])
+            values = Array(v)
+            frontmatter[key] = (current + values).uniq
+          end
+
+          # Apply remove operations (for arrays)
+          remove.each do |k, v|
+            key = k.to_s
+            next unless frontmatter[key].is_a?(Array)
+
+            values = Array(v)
+            frontmatter[key] = frontmatter[key] - values
+          end
+
+          # Write back atomically (temp + rename to avoid partial writes)
+          new_content = Ace::Support::Items::Atoms::FrontmatterSerializer.rebuild(frontmatter, body)
+          tmp_path = "#{idea.file_path}.tmp.#{Process.pid}"
+          File.write(tmp_path, new_content)
+          File.rename(tmp_path, idea.file_path)
+        ensure
+          begin
+            File.unlink(tmp_path) if tmp_path && File.exist?(tmp_path)
+          rescue
+            nil
+          end
+        end
+
+        # Extract archive date from idea frontmatter, falling back to Time.now
+        def parse_archive_date(idea)
+          raw = idea.metadata["completed_at"] || idea.metadata["created_at"]
+          return nil unless raw
+
+          case raw
+          when Time then raw
+          when DateTime then raw.to_time
+          else begin
+            Time.parse(raw.to_s)
+          rescue
+            nil
+          end
+          end
+        end
+
+        # Value accessor for FilterApplier — reads from Idea model attributes and metadata
+        def idea_value_accessor(item, key)
+          case key
+          when "status" then item.status
+          when "title" then item.title
+          when "tags" then item.tags
+          when "id" then item.id
+          when "special_folder" then item.special_folder
+          else
+            item.metadata[key] || item.metadata[key.to_sym] if item.respond_to?(:metadata) && item.metadata
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/idea/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ace
+  module Idea
+    VERSION = "0.18.0"
+  end
+end

data/lib/ace/idea.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "idea/version"
+
+# External dependencies
+require "ace/b36ts"
+require "ace/support/items"
+
+# Atoms
+require_relative "idea/atoms/idea_id_formatter"
+require_relative "idea/atoms/idea_file_pattern"
+require_relative "idea/atoms/idea_frontmatter_defaults"
+
+# Models
+require_relative "idea/models/idea"
+
+# Molecules
+require_relative "idea/molecules/idea_config_loader"
+require_relative "idea/molecules/idea_scanner"
+require_relative "idea/molecules/idea_resolver"
+require_relative "idea/molecules/idea_loader"
+require_relative "idea/molecules/idea_creator"
+require_relative "idea/molecules/idea_llm_enhancer"
+require_relative "idea/molecules/idea_clipboard_reader"
+require_relative "idea/molecules/idea_mover"
+require_relative "idea/molecules/idea_display_formatter"
+
+# Organisms
+require_relative "idea/organisms/idea_manager"
+
+module Ace
+  # Idea management gem for ACE.
+  # Manages ideas in .ace-ideas/ using raw 6-char b36ts IDs.
+  module Idea
+    class Error < StandardError; end
+  end
+end

metadata

@@ -0,0 +1,166 @@
+--- !ruby/object:Gem::Specification
+name: ace-idea
+version: !ruby/object:Gem::Version
+  version: 0.18.0
+platform: ruby
+authors:
+- Michal Czyz
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ace-support-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+- !ruby/object:Gem::Dependency
+  name: ace-support-fs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: ace-support-items
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: ace-b36ts
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: ace-support-cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+description: Capture rough ideas quickly, store them as structured files, organize
+  them with GTD-style folders, and manage them through a focused six-command CLI.
+email:
+- mc@cs3b.com
+executables:
+- ace-idea
+extensions: []
+extra_rdoc_files: []
+files:
+- ".ace-defaults/idea/config.yml"
+- ".ace-defaults/nav/protocols/wfi-sources/ace-idea.yml"
+- CHANGELOG.md
+- README.md
+- Rakefile
+- docs/demo/ace-idea-getting-started.gif
+- docs/demo/ace-idea-getting-started.tape.yml
+- docs/demo/fixtures/README.md
+- docs/demo/fixtures/sample.txt
+- docs/getting-started.md
+- docs/handbook.md
+- docs/usage.md
+- exe/ace-idea
+- handbook/skills/as-idea-capture-features/SKILL.md
+- handbook/skills/as-idea-capture/SKILL.md
+- handbook/skills/as-idea-review/SKILL.md
+- handbook/workflow-instructions/idea/capture-features.wf.md
+- handbook/workflow-instructions/idea/capture.wf.md
+- handbook/workflow-instructions/idea/prioritize.wf.md
+- handbook/workflow-instructions/idea/review.wf.md
+- lib/ace/idea.rb
+- lib/ace/idea/atoms/idea_file_pattern.rb
+- lib/ace/idea/atoms/idea_frontmatter_defaults.rb
+- lib/ace/idea/atoms/idea_id_formatter.rb
+- lib/ace/idea/atoms/idea_validation_rules.rb
+- lib/ace/idea/atoms/slug_sanitizer_adapter.rb
+- lib/ace/idea/cli.rb
+- lib/ace/idea/cli/commands/create.rb
+- lib/ace/idea/cli/commands/doctor.rb
+- lib/ace/idea/cli/commands/list.rb
+- lib/ace/idea/cli/commands/show.rb
+- lib/ace/idea/cli/commands/status.rb
+- lib/ace/idea/cli/commands/update.rb
+- lib/ace/idea/models/idea.rb
+- lib/ace/idea/molecules/idea_clipboard_reader.rb
+- lib/ace/idea/molecules/idea_config_loader.rb
+- lib/ace/idea/molecules/idea_creator.rb
+- lib/ace/idea/molecules/idea_display_formatter.rb
+- lib/ace/idea/molecules/idea_doctor_fixer.rb
+- lib/ace/idea/molecules/idea_doctor_reporter.rb
+- lib/ace/idea/molecules/idea_frontmatter_validator.rb
+- lib/ace/idea/molecules/idea_llm_enhancer.rb
+- lib/ace/idea/molecules/idea_loader.rb
+- lib/ace/idea/molecules/idea_mover.rb
+- lib/ace/idea/molecules/idea_resolver.rb
+- lib/ace/idea/molecules/idea_scanner.rb
+- lib/ace/idea/molecules/idea_structure_validator.rb
+- lib/ace/idea/organisms/idea_doctor.rb
+- lib/ace/idea/organisms/idea_manager.rb
+- lib/ace/idea/version.rb
+homepage: https://github.com/cs3b/ace
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/cs3b/ace
+  source_code_uri: https://github.com/cs3b/ace/tree/main/ace-idea/
+  changelog_uri: https://github.com/cs3b/ace/blob/main/ace-idea/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Capture ideas quickly, then shape and organize them for execution
+test_files: []