omnifocus_mcp 1.0.0

data/lib/omnifocus_mcp/tools/presenters/batch_report.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module OmnifocusMcp
+  module Tools
+    module Presenters
+      # Shared formatting for batch add/remove tool replies.
+      module BatchReport
+        class << self
+          def format_success(past_tense:, failure_verb:, results:, items:, &detail)
+            success_count = results.count(&:ok?)
+            failure_count = results.count(&:error?)
+
+            message = "✅ Successfully #{past_tense} #{success_count} items."
+            message += " ⚠️ Failed to #{failure_verb} #{failure_count} items." if failure_count.positive?
+
+            lines = results.each_with_index.map { |r, i| yield(r, items[i]) }
+            "#{message}\n\n#{lines.join("\n")}"
+          end
+
+          # True when every per-item result failed (and at least one item was processed).
+          def all_failed?(results) = results.any? && results.all?(&:error?)
+
+          def format_failure(error_message, results: [], items: [], &detail)
+            if results.any?
+              lines = results.each_with_index.map { |r, i| yield(r, items[i]) }
+              "Failed to process batch operation.\n\n#{lines.join("\n")}"
+            else
+              "Failed to process batch operation.\n\nNo items processed. #{error_message || ""}"
+            end
+          end
+
+          def add_detail(result, original)
+            item_type = original.type
+            item_name = original.name
+            if result.ok?
+              %(- ✅ #{item_type}: "#{item_name}")
+            else
+              %(- ❌ #{item_type}: "#{item_name}" - Error: #{result.error || "Unknown error"})
+            end
+          end
+
+          def remove_detail(result, original)
+            item_type = original.item_type
+            if result.ok?
+              %(- ✅ #{item_type}: "#{result.ok.name}")
+            else
+              identifier = original.id || original.name
+              "- ❌ #{item_type}: #{identifier} - Error: #{result.error}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/tools/presenters/list_perspectives.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module OmnifocusMcp
+  module Tools
+    module Presenters
+      module ListPerspectives
+        class << self
+          def format(perspectives)
+            return "No perspectives found." if perspectives.empty?
+
+            built_in = perspectives.select { |perspective| perspective["type"] == "builtin" }
+            custom = perspectives.select { |perspective| perspective["type"] == "custom" }
+
+            output = "## Available Perspectives (#{perspectives.length})\n\n"
+            append_group(output:, title: "Built-in Perspectives", perspectives: built_in)
+            output << "\n" if built_in.any? && custom.any?
+            append_group(output:, title: "Custom Perspectives", perspectives: custom)
+            output
+          end
+
+          private
+
+          def append_group(output:, title:, perspectives:)
+            return if perspectives.empty?
+
+            output << "### #{title}\n"
+            perspectives.each { |perspective| output << "• #{perspective["name"]}\n" }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/tools/presenters/list_tags.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module OmnifocusMcp
+  module Tools
+    module Presenters
+      module ListTags
+        class << self
+          def format(tags)
+            return "No tags found." if tags.empty?
+
+            nested_tags, top_level_tags = tags.partition { |tag| tag["parentTagID"] }
+            children_by_parent = nested_tags.group_by { |tag| tag["parentTagID"] }
+
+            output = "## Tags (#{tags.length})\n\n"
+            append_top_level_tags(output:, top_level_tags:, children_by_parent:)
+            append_orphaned_children(output:, top_level_tags:, children_by_parent:)
+            output
+          end
+
+          private
+
+          def append_top_level_tags(output:, top_level_tags:, children_by_parent:)
+            top_level_tags.each do |tag|
+              output << format_tag(tag, "")
+              (children_by_parent[tag["id"]] || []).each do |child|
+                output << format_tag(child, "  ")
+              end
+            end
+          end
+
+          def append_orphaned_children(output:, top_level_tags:, children_by_parent:)
+            rendered_parents = top_level_tags.to_set { |tag| tag["id"] }
+            children_by_parent.each do |parent_id, children|
+              next if rendered_parents.include?(parent_id)
+
+              children.each { |child| output << format_tag(child, "") }
+            end
+          end
+
+          def format_tag(tag, indent)
+            status = tag["active"] ? "" : " (inactive)"
+            tasks = (tag["taskCount"] || 0).positive? ? " [#{tag["taskCount"]} tasks]" : ""
+            "#{indent}- **#{tag["name"]}**#{status}#{tasks} (id: #{tag["id"]})\n"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/tools/presenters/perspective_view.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "../definitions/date_formatter"
+
+module OmnifocusMcp
+  module Tools
+    module Presenters
+      module PerspectiveView
+        class << self
+          def format(perspective_name, items, limit)
+            output = "## #{perspective_name} Perspective (#{items.length} items)\n\n"
+
+            if items.empty?
+              output << "No items visible in this perspective."
+              return output
+            end
+
+            items.each { |item| append_item(output, item) }
+            append_limit_warning(output:, items:, limit:)
+            output
+          end
+
+          private
+
+          def append_item(output, item)
+            output << "• #{format_parts(item).join(" ")}\n"
+            append_note_preview(output, item["note"]) if item["note"] && !item["note"].to_s.strip.empty?
+          end
+
+          def format_parts(item)
+            parts = []
+            flag = item["flagged"] ? "🚩 " : ""
+            checkbox = item["completed"] ? "☑" : "☐"
+            parts << "#{checkbox} #{flag}#{item["name"] || "Unnamed"}"
+
+            parts << "(#{item["projectName"]})" if item["projectName"]
+            if item["dueDate"]
+              parts << "[due: #{Definitions::DateFormatter.format_date(item["dueDate"],
+                                                                       style: :compact)}]"
+            end
+            if item["deferDate"]
+              parts << "[defer: #{Definitions::DateFormatter.format_date(item["deferDate"],
+                                                                         style: :compact)}]"
+            end
+            append_estimate(parts, item["estimatedMinutes"])
+            parts << "<#{item["tagNames"].join(",")}>" if item["tagNames"] && !item["tagNames"].empty?
+            parts << "##{item["taskStatus"].downcase}" if item["taskStatus"] && item["taskStatus"] != "Available"
+            parts << "[#{item["id"]}]" if item["id"]
+            parts
+          end
+
+          def append_estimate(parts, estimated_minutes)
+            return unless estimated_minutes
+
+            minutes = estimated_minutes.to_i
+            formatted = if minutes >= 60
+                          remainder = minutes % 60
+                          remainder.positive? ? "#{minutes / 60}h#{remainder}m" : "#{minutes / 60}h"
+                        else
+                          "#{minutes}m"
+                        end
+            parts << "(#{formatted})"
+          end
+
+          def append_note_preview(output, note)
+            first_line = note.strip.split("\n").first.to_s
+            preview = first_line.slice(0, 80)
+            ellipsis = note.length > 80 || note.include?("\n") ? "..." : ""
+            output << "  └─ #{preview}#{ellipsis}\n"
+          end
+
+          def append_limit_warning(output:, items:, limit:)
+            return unless items.length == limit
+
+            output << "\n⚠️ Results limited to #{limit} items. More may be available in this perspective."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/tools/presenters/query_reply.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "query_results"
+
+module OmnifocusMcp
+  module Tools
+    module Presenters
+      module QueryReply
+        class << self
+          def format(args:, params:, match:)
+            return JSON.pretty_generate(json_payload(args:, params:, match:)) if output_format(params) == "json"
+            return "Found #{match.count} #{params.entity} matching your criteria." if params.summary
+
+            items = match.items || []
+            output = QueryResults.format_query_results(items:, entity: params.entity, filters: args[:filters])
+            output += limit_warning(params.limit) if params.limit && items.length == params.limit
+            output
+          end
+
+          def failure(error) = "Query failed: #{error}"
+
+          private
+
+          def output_format(params)
+            params.respond_to?(:to_h) ? params.to_h[:format] : nil
+          end
+
+          def json_payload(args:, params:, match:)
+            {
+              entity: params.entity,
+              count: match.count,
+              items: match.items,
+              filters: args[:filters] || {},
+              fields: params.fields,
+              limit: params.limit,
+              sortBy: args[:sortBy],
+              sortOrder: params.sort_order,
+              includeCompleted: params.include_completed == true,
+              summary: params.summary == true
+            }
+          end
+
+          def limit_warning(limit)
+            "\n\n⚠️ Results limited to #{limit} items. More may be available."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/tools/presenters/query_results.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require_relative "../../utils/blank"
+require_relative "../../utils/iso_date"
+
+module OmnifocusMcp
+  module Tools
+    module Presenters
+      # Pure-string formatters for `query_omnifocus` results.
+      #
+      # Exposes `format_tasks`, `format_projects`, `format_folders`,
+      # `format_query_results`, `format_filters`. Used by
+      # {Definitions::QueryOmnifocusTool} to build the user-facing text reply.
+      module QueryResults
+        class << self
+          def format_query_results(items:, entity:, filters: nil)
+            return "No #{entity} found matching the specified criteria." if items.nil? || items.empty?
+
+            output = "## Query Results: #{items.length} #{entity}\n\n"
+
+            output << "Filters applied: #{format_filters(filters)}\n\n" if filters && !filters.empty?
+
+            output << case entity.to_s
+                      when "tasks"    then format_tasks(items)
+                      when "projects" then format_projects(items)
+                      when "folders"  then format_folders(items)
+                      else "Unsupported entity: #{entity}"
+                      end
+
+            output
+          end
+
+          def format_filters(filters)
+            f = stringify_keys(filters)
+            parts = []
+
+            parts << %(project ID: "#{f["projectId"]}") if f["projectId"]
+            parts << %(project: "#{f["projectName"]}")  if f["projectName"]
+            parts << %(task: "#{f["taskName"]}")        if f["taskName"]
+            parts << %(folder ID: "#{f["folderId"]}")   if f["folderId"]
+            parts << "tags: [#{Array(f["tags"]).join(", ")}]"     if f["tags"]
+            parts << "status: [#{Array(f["status"]).join(", ")}]" if f["status"]
+            parts << "flagged: #{f["flagged"]}" unless f["flagged"].nil?
+
+            parts << format_within(label: "due", value: f["dueWithin"]) if f["dueWithin"]
+            parts << format_deferred(f["deferredUntil"]) if f["deferredUntil"]
+            parts << format_within(label: "planned", value: f["plannedWithin"]) if f["plannedWithin"]
+
+            parts << "has note: #{f["hasNote"]}" unless f["hasNote"].nil?
+            parts << "inbox: #{f["inbox"]}"      unless f["inbox"].nil?
+
+            parts << format_on(label: "due", value: f["dueOn"]) unless f["dueOn"].nil?
+            parts << format_on(label: "defer", value: f["deferOn"]) unless f["deferOn"].nil?
+            parts << format_on(label: "planned", value: f["plannedOn"]) unless f["plannedOn"].nil?
+
+            parts << "added within #{f["addedWithin"]} days" unless f["addedWithin"].nil?
+            parts << "added on day #{f["addedOn"]}" unless f["addedOn"].nil?
+            parts << "repeating: #{f["isRepeating"]}" unless f["isRepeating"].nil?
+            parts << "completed within #{f["completedWithin"]} days" unless f["completedWithin"].nil?
+            parts << "completed on day #{f["completedOn"]}" unless f["completedOn"].nil?
+
+            parts.join(", ")
+          end
+
+          def format_tasks(tasks)
+            tasks.map { format_task(it) }
+                 .join("\n")
+          end
+
+          def format_projects(projects)
+            projects.map { format_project(it) }
+                    .join("\n")
+          end
+
+          def format_folders(folders)
+            folders.map { format_folder(it) }
+                   .join("\n")
+          end
+
+          def format_task(task)
+            t = stringify_keys(task)
+            parts = []
+
+            flag = t["flagged"] ? "🚩 " : ""
+            parts << "• #{flag}#{t["name"] || "Unnamed"}"
+
+            parts << "[#{t["id"]}]" if t["id"]
+            parts << "(#{t["projectName"]})" if t["projectName"]
+
+            append_date(parts, label: "due", value: t["dueDate"])
+            append_date(parts, label: "defer", value: t["deferDate"])
+            append_date(parts, label: "planned", value: t["plannedDate"])
+
+            if t["estimatedMinutes"]
+              minutes = t["estimatedMinutes"].to_i
+              formatted = minutes >= 60 ? "#{minutes / 60}h" : "#{minutes}m"
+              parts << "(#{formatted})"
+            end
+
+            parts << "<#{Array(t["tagNames"]).join(",")}>" if t["tagNames"] && !t["tagNames"].empty?
+            parts << "##{t["taskStatus"].downcase}"        if t["taskStatus"]
+
+            unless t["isRepeating"].nil?
+              parts << (t["isRepeating"] ? "[repeating]" : "[not repeating]")
+            end
+
+            parts << "[rule: #{t["repetitionRule"]}]" if t["repetitionRule"]
+            parts << "[parent: #{t["parentId"]}]"     if t["parentId"]
+
+            if t["hasChildren"] && t["childIds"] && !t["childIds"].empty?
+              parts << "[children: #{t["childIds"].join(", ")}]"
+            end
+
+            append_date(parts, label: "created", value: t["creationDate"])
+            append_date(parts, label: "modified", value: t["modificationDate"])
+            append_date(parts, label: "completed", value: t["completionDate"])
+
+            result = parts.join(" ")
+            result += "\n  Note: #{t["note"]}" unless Utils::Blank.blank?(t["note"])
+            result
+          end
+
+          def format_project(project)
+            p = stringify_keys(project)
+
+            status     = p["status"] && p["status"] != "Active" ? " [#{p["status"]}]" : ""
+            folder     = p["folderName"]                        ? " 📁 #{p["folderName"]}" : ""
+            task_count = p["taskCount"].nil?                    ? "" : " (#{p["taskCount"]} tasks)"
+            flagged    = p["flagged"] ? "🚩 " : ""
+            due        = format_due_segment(p["dueDate"])
+
+            result = "P: #{flagged}#{p["name"]}#{status}#{due}#{folder}#{task_count}"
+            result += "\n  Note: #{p["note"]}" unless Utils::Blank.blank?(p["note"])
+            result
+          end
+
+          def format_folder(folder)
+            f = stringify_keys(folder)
+
+            project_count = f["projectCount"].nil? ? "" : " (#{f["projectCount"]} projects)"
+            path          = f["path"]              ? " 📍 #{f["path"]}" : ""
+
+            "F: #{f["name"]}#{project_count}#{path}"
+          end
+
+          private
+
+          def stringify_keys(hash)
+            return {} if hash.nil?
+
+            hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+          end
+
+          def format_within(label:, value:)
+            value.is_a?(String) ? "#{label} within #{value}" : "#{label} within #{value} days"
+          end
+
+          def format_deferred(value)
+            if value.is_a?(String)
+              "deferred within #{value}"
+            else
+              "deferred becoming available within #{value} days"
+            end
+          end
+
+          def format_on(label:, value:)
+            value.is_a?(String) ? "#{label} on #{value}" : "#{label} on day +#{value}"
+          end
+
+          def format_due_segment(date_str)
+            formatted = Utils::IsoDate.to_date_only(date_str)
+            formatted ? " [due: #{formatted}]" : ""
+          end
+
+          def append_date(parts, label:, value:)
+            formatted = Utils::IsoDate.to_date_only(value)
+            parts << "[#{label}: #{formatted}]" if formatted
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/tools/presenters.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module OmnifocusMcp
+  module Tools
+    module Presenters
+    end
+  end
+end

data/lib/omnifocus_mcp/tools/query_omnifocus_formatter.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "presenters/query_results"
+
+module OmnifocusMcp
+  module Tools
+    QueryOmnifocusFormatter = Presenters::QueryResults
+  end
+end

data/lib/omnifocus_mcp/tools/query_statuses.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module OmnifocusMcp
+  module Tools
+    # Valid status filter values for `query_omnifocus`, shared by the MCP schema,
+    # generated OmniJS, and specs.
+    module QueryStatuses
+      TASK = %w[Next Available Blocked DueSoon Overdue Completed Dropped].freeze
+      PROJECT = %w[Active OnHold Done Dropped].freeze
+
+      class << self
+        def task_list_for_schema
+          TASK.map { |s| "'#{s}'" }.join(", ")
+        end
+
+        def project_list_for_schema
+          PROJECT.map { |s| "'#{s}'" }.join(", ")
+        end
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/utils/apple_script.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "../infrastructure/apple_script"
+
+module OmnifocusMcp
+  module Utils
+    AppleScript = Infrastructure::AppleScript
+  end
+end

data/lib/omnifocus_mcp/utils/apple_script_envelope.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "../parsers/apple_script_envelope"
+
+module OmnifocusMcp
+  module Utils
+    AppleScriptEnvelope = Parsers::AppleScriptEnvelope
+  end
+end

data/lib/omnifocus_mcp/utils/apple_script_helpers.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "../infrastructure/apple_script"
+
+module OmnifocusMcp
+  module Utils
+    AppleScriptHelpers = Infrastructure::AppleScript
+  end
+end

data/lib/omnifocus_mcp/utils/blank.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module OmnifocusMcp
+  module Utils
+    # Lightweight "blank" predicate without pulling in ActiveSupport.
+    #
+    # A value is *blank* when it is `nil` or its `to_s` is the empty string.
+    # The variadic form returns `true` only when **every** argument is blank,
+    # which is exactly the shape the audit's hot spots want:
+    #
+    #     Utils::Blank.blank?(args[:id], args[:name])
+    #     # => true when both the id and the name are missing or empty
+    #
+    # Replaces 12+ hand-rolled `x.nil? || x.to_s.empty?` chains across the
+    # codebase (audit item #19).
+    module Blank
+      module_function
+
+      def blank?(*values)
+        return true if values.empty?
+
+        values.all? { |v| v.to_s.empty? }
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/utils/date_filter.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "date"
+
+module OmnifocusMcp
+  module Utils
+    # Parses MCP date-filter wire values and converts them to days-from-today.
+    #
+    # Named filters are modeled as symbols (`:today`, `:tomorrow`, …) after
+    # parsing; only string input is accepted at the MCP boundary. Numeric and
+    # ISO-date inputs resolve directly to day offsets.
+    #
+    module DateFilter
+      STRING_TO_NAMED = {
+        "today" => :today,
+        "tomorrow" => :tomorrow,
+        "this week" => :this_week,
+        "next week" => :next_week
+      }.freeze
+
+      ISO_DATE_RE = /\A\d{4}-\d{2}-\d{2}\z/
+
+      # Parse an MCP wire value into a Ruby-native filter (Symbol or Numeric).
+      #
+      # `today:` defaults to `Date.today` so ISO dates are resolved relative to a
+      # pinned reference date in tests.
+      class << self
+        def parse(input, today: Date.today)
+          return input if input.is_a?(Numeric)
+          return input if input.is_a?(Symbol)
+
+          raise_invalid!(input) unless input.is_a?(String) && !input.empty?
+
+          normalized = input.strip.downcase
+          return STRING_TO_NAMED[normalized] if STRING_TO_NAMED.key?(normalized)
+          return (parse_iso_date(normalized:, original: input) - today).to_i if ISO_DATE_RE.match?(normalized)
+
+          raise_invalid!(input)
+        end
+
+        # Convert a parsed filter to a days-from-`today` Integer for query scripts.
+        def to_days(filter)
+          case filter
+          when :today     then 0
+          when :tomorrow  then 1
+          when :this_week then 7
+          when :next_week then 14
+          when Numeric    then filter
+          else
+            raise ArgumentError, "expected Symbol or Numeric date filter, got #{filter.inspect}"
+          end
+        end
+
+        # MCP boundary helper: parse and convert to days in one step.
+        def resolve(input, today: Date.today)
+          to_days(parse(input, today: today))
+        end
+
+        private
+
+        def parse_iso_date(normalized:, original:)
+          Date.iso8601(normalized)
+        rescue Date::Error
+          raise_invalid!(original)
+        end
+
+        def raise_invalid!(input)
+          raise ArgumentError,
+                "Invalid date filter value: \"#{input}\". " \
+                'Use a number, "today", "tomorrow", "this week", "next week", ' \
+                "or an ISO date (YYYY-MM-DD)."
+        end
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/utils/date_formatting.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "../infrastructure/apple_script_date_builder"
+
+module OmnifocusMcp
+  module Utils
+    DateFormatting = Infrastructure::AppleScriptDateBuilder
+  end
+end

data/lib/omnifocus_mcp/utils/iso_date.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "date"
+
+require_relative "blank"
+
+module OmnifocusMcp
+  module Utils
+    # Normalizes date strings to ISO 8601 for machine-oriented output (query
+    # results, resource JSON). Human-readable formatting lives in
+    # {Tools::Definitions::DateFormatter}.
+    #
+    module IsoDate
+      module_function
+
+      # Return a YYYY-MM-DD string, or +nil+ when the input is blank or
+      # unparseable.
+      def to_date_only(value)
+        return nil if Blank.blank?(value)
+
+        Date.parse(value.to_s).strftime("%Y-%m-%d")
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end