flycal-cli 0.7.4 → 1.0

data/lib/flycal/pipeline/retriever.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Flycal
+  module Pipeline
+    # First pipeline layer: fetch calendar events for the requested timeframe.
+    class Retriever
+      def initialize(calendar_service)
+        @service = calendar_service
+      end
+
+      # Expects params: :calendar_ids, :time_min, :time_max, optional :description
+      # Writes: :events (normalized), :calendar_names
+      def call(params)
+        calendar_ids = Array(params[:calendar_ids])
+        time_min = params[:time_min]
+        time_max = params[:time_max]
+        query = params[:description]
+
+        calendar_list = @service.list_calendars
+        calendar_names = calendar_list.to_h { |c| [c.id, c.summary || c.id] }
+        params[:calendar_names] = calendar_names
+
+        raw = @service.list_all_events(
+          calendar_ids,
+          time_min: time_min,
+          time_max: time_max,
+          query: query
+        )
+
+        params[:events] = raw.map { |item| normalize_event(item, calendar_names) }
+        params
+      end
+
+      private
+
+      def normalize_event(item, calendar_names)
+        event = item[:event]
+        cal_id = item[:calendar_id]
+        start_at = to_time(event.start&.date_time || event.start&.date)
+        end_at = to_time(event.end&.date_time || event.end&.date)
+        minutes =
+          if start_at && end_at && end_at > start_at
+            (end_at - start_at) / 60.0
+          else
+            0.0
+          end
+
+        {
+          calendar_id: cal_id,
+          calendar_name: calendar_names[cal_id] || cal_id,
+          summary: event.summary,
+          description: event.description,
+          start_at: start_at,
+          end_at: end_at,
+          duration_minutes: minutes,
+          all_day: !event.start&.date.nil? && event.start&.date_time.nil?,
+          raw: event
+        }
+      end
+
+      def to_time(value)
+        return nil if value.nil?
+        return value if value.is_a?(Time)
+        return value.to_time if value.respond_to?(:to_time) && !value.is_a?(String)
+
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/flycal/pipeline/search_pipeline.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Flycal
+  module Pipeline
+    # Orchestrates Retriever → Aggregator → Renderer for search.
+    class SearchPipeline
+      def initialize(calendar_service)
+        @service = calendar_service
+      end
+
+      def run(params)
+        Retriever.new(@service).call(params)
+        Aggregator.new.call(params)
+        Renderer.for(params[:format]).render(params)
+      end
+    end
+  end
+end

data/lib/flycal/pipeline/text_renderer.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Flycal
+  module Pipeline
+    # Shell text output — preserves the historical flycal search formatting.
+    class TextRenderer < Renderer
+      HOURS_PER_WORKING_DAY = Aggregator::HOURS_PER_WORKING_DAY
+
+      def render(params)
+        lines = []
+        lines.concat(event_lines(params))
+        lines << ""
+        lines.concat(summary_lines(params))
+        lines.join("\n") + "\n"
+      end
+
+      private
+
+      def event_lines(params)
+        Array(params[:events]).map do |ev|
+          start_str = format_datetime(ev[:start_at])
+          end_str = format_datetime(ev[:end_at])
+          desc = ev[:summary] || "(no title)"
+          if ev[:summary].nil? && ev[:description]
+            desc = ev[:description].to_s.slice(0, 80)
+          end
+          "#{ev[:calendar_name]} | #{start_str} | #{end_str} | #{desc}"
+        end
+      end
+
+      def summary_lines(params)
+        totals = params[:totals] || {}
+        time_min = params[:time_min]
+        time_max = params[:time_max]
+        from_str = time_min.strftime("%a %Y-%m-%d %H:%M")
+        to_str = time_max.strftime("%a %Y-%m-%d %H:%M")
+
+        lines = []
+        lines << "---"
+        lines << "From: #{from_str} | To: #{to_str}"
+        lines << "Events found: #{totals[:event_count]}"
+        lines << "Total time occupied: #{format_duration(totals[:total_minutes].to_f)}"
+        lines << "Cache: #{params[:cache_status]}" if params[:cache_status]
+        lines << "Mock seed: #{params[:mock_seed]}" if params[:use_mock] && !params[:mock_seed].nil?
+
+        case params[:group_by]
+        when "week"
+          lines << ""
+          lines << "By week:"
+          lines.concat(week_group_lines(params[:groups]))
+        when "month"
+          lines << ""
+          lines << "By month:"
+          lines.concat(month_group_lines(params[:groups]))
+        when "day"
+          if explicit_time_group_by?(params, "day")
+            lines << ""
+            lines << "By day:"
+            lines.concat(day_group_lines(params[:groups]))
+          end
+        when "string"
+          lines << ""
+          lines << "By string:"
+          lines.concat(string_group_lines(params[:groups]))
+        end
+
+        lines
+      end
+
+      def explicit_time_group_by?(params, value)
+        params[:group_by_option].to_s.strip.downcase == value
+      end
+
+      def day_group_lines(groups)
+        Array(groups).map do |g|
+          day_str = format_date_with_day(g[:start_at])
+          "  #{bold(g[:index])}. #{day_str}: #{format_hours_and_days(g[:hours], g[:working_days])}"
+        end
+      end
+
+      def week_group_lines(groups)
+        Array(groups).map do |g|
+          start_str = format_date_with_day(g[:start_at])
+          end_str = format_date_with_day(g[:period_label_end])
+          "  #{bold(g[:index])}. #{start_str} - #{end_str}: #{format_hours_and_days(g[:hours], g[:working_days])}"
+        end
+      end
+
+      def month_group_lines(groups)
+        Array(groups).map do |g|
+          start_str = format_date_with_day(g[:start_at])
+          end_str = format_date_with_day(g[:period_label_end])
+          "  #{g[:index]}. #{g[:month_name]} (#{start_str} - #{end_str}): #{format_hours_and_days(g[:hours], g[:working_days])}"
+        end
+      end
+
+      def string_group_lines(groups)
+        Array(groups).map do |g|
+          label = g[:string] || g[:key]
+          "  #{bold(g[:index])}. #{label}: #{g[:event_count]} events, #{format_hours_and_days(g[:hours], g[:working_days])}"
+        end
+      end
+
+      def format_datetime(dt)
+        return "-" if dt.nil?
+        return dt if dt.is_a?(String)
+
+        "#{Locale.day_abbr(dt)} #{dt.strftime("%Y-%m-%d %H:%M")}"
+      end
+
+      def format_date_with_day(dt)
+        return "-" if dt.nil?
+
+        t = dt.respond_to?(:to_time) ? dt.to_time : dt
+        "#{Locale.day_abbr(t)} #{t.strftime("%Y-%m-%d")}"
+      end
+
+      def format_duration(total_minutes)
+        hours = (total_minutes / 60).floor
+        mins = (total_minutes % 60).round
+        working_days = (total_minutes / 60.0 / HOURS_PER_WORKING_DAY).round(1)
+        "#{bold(hours)}h #{bold(mins)}min (#{bold(working_days)} working days)"
+      end
+
+      def format_hours_and_days(hours, working_days)
+        "#{bold(hours)}h (#{bold(working_days)} working days)"
+      end
+
+      def bold(str)
+        "\e[1m#{str}\e[0m"
+      end
+    end
+  end
+end

data/lib/flycal/pipeline.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Flycal
+  module Pipeline
+  end
+end

data/lib/{flycal_cli → flycal}/slot_finder.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module FlycalCli
+module Flycal
   class SlotFinder
     DEFAULT_HOURS = [[9, 0, 18, 0]].freeze
     DEFAULT_DAYS = [1, 2, 3, 4, 5].freeze

data/lib/flycal/slot_formatter.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Flycal
+  class SlotFormatter
+    class << self
+      def format_header(from:, to:, duration:, calendars:, count:, template: nil)
+        lines = []
+        lines << Locale.t(
+          "slots.header",
+          count: underline(count),
+          from: underline(Locale.format_long_date(from)),
+          to: underline(Locale.format_long_date(to)),
+          duration: underline(duration),
+          template: underline(template.to_s)
+        )
+        calendars.each do |cal|
+          lines << "- #{cal[:name]}"
+        end
+        lines << "link: #{google_calendar_day_url(from)}"
+        lines.join("\n")
+      end
+
+      def format_output(slots_by_day)
+        lines = []
+
+        slots_by_day.sort_by(&:first).each do |date, slots|
+          lines << "" unless lines.empty?
+          lines << underline(day_header(date))
+          slots.each do |start_at, end_at|
+            lines << slot_range(start_at, end_at)
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      # Full shell text for slots (header + body). Used by CLI and JSON `text` key.
+      def format_text(
+        slots_by_day:,
+        time_min:,
+        time_max:,
+        duration:,
+        calendars:,
+        template: nil,
+        empty_message: nil
+      )
+        count = slots_by_day.values.sum(&:size)
+        header = format_header(
+          from: time_min,
+          to: time_max,
+          duration: duration,
+          calendars: calendars,
+          count: count,
+          template: template
+        )
+        body = format_output(slots_by_day)
+        body = empty_message.to_s if body.empty? && empty_message
+
+        parts = [ header, "" ]
+        parts << body unless body.to_s.empty?
+        "#{parts.join("\n").rstrip}\n"
+      end
+
+      # Pretty JSON for --format json (EmCP / API friendly).
+      def format_json(**kwargs)
+        JSON.pretty_generate(payload_hash(**kwargs)) + "\n"
+      end
+
+      # Structured hash used by CLI JSON output and HTTP API.
+      def payload_hash(
+        slots_by_day:,
+        time_min:,
+        time_max:,
+        duration:,
+        template:,
+        calendars:,
+        locale: nil,
+        calendar_option: nil,
+        from_option: nil,
+        in_option: nil,
+        free_before: nil,
+        free_after: nil,
+        empty_message: nil
+      )
+        items = []
+        groups = slots_by_day.sort_by(&:first).map do |date, slots|
+          slot_items = slots.map { |start_at, end_at| serialize_slot(start_at, end_at, date) }
+          items.concat(slot_items)
+          {
+            "type" => "day",
+            "key" => date.iso8601,
+            "date" => date.iso8601,
+            "from" => format_iso(slots.map(&:first).min),
+            "to" => format_iso(slots.map(&:last).max),
+            "slots_found" => slot_items.size,
+            "items" => slot_items
+          }
+        end
+
+        text = format_text(
+          slots_by_day: slots_by_day,
+          time_min: time_min,
+          time_max: time_max,
+          duration: duration,
+          calendars: calendars,
+          template: template,
+          empty_message: empty_message
+        )
+
+        {
+          "params" => {
+            "command" => "slots",
+            "from" => format_iso(time_min),
+            "to" => format_iso(time_max),
+            "duration" => duration,
+            "template" => template,
+            "calendar" => blank_to_nil(calendar_option),
+            "calendar_ids" => Array(calendars).map { |c| c[:id] },
+            "format" => "json",
+            "locale" => locale || Locale.current_locale,
+            "from_option" => blank_to_nil(from_option),
+            "in_option" => blank_to_nil(in_option),
+            "free_before" => free_before,
+            "free_after" => free_after
+          }.compact,
+          "info" => {
+            "slots_found" => items.size,
+            "from" => format_iso(time_min),
+            "to" => format_iso(time_max),
+            "duration" => duration,
+            "template" => template,
+            "calendars" => Array(calendars).map { |c| { "id" => c[:id], "name" => c[:name] } },
+            "link" => google_calendar_day_url(time_min)
+          },
+          "text" => strip_ansi(text).split("\n"),
+          "items" => items,
+          "groups" => groups
+        }
+      end
+
+      def strip_ansi(text)
+        text.to_s.gsub(/\e\[[0-9;]*m/, "")
+      end
+
+      private
+
+      def serialize_slot(start_at, end_at, date)
+        {
+          "date" => date.iso8601,
+          "start" => { "dateTime" => format_iso(start_at) },
+          "end" => { "dateTime" => format_iso(end_at) },
+          "duration_seconds" => (end_at - start_at).to_i
+        }
+      end
+
+      def format_iso(value)
+        return nil if value.nil?
+        return value.iso8601 if value.respond_to?(:iso8601)
+
+        value.to_s
+      end
+
+      def blank_to_nil(value)
+        str = value.to_s
+        str.empty? ? nil : str
+      end
+
+      def underline(str)
+        "\e[4m#{str}\e[0m"
+      end
+
+      def google_calendar_day_url(from)
+        t = from.respond_to?(:to_time) ? from.to_time : from
+        "https://calendar.google.com/calendar/r/day/#{t.year}/#{t.month}/#{t.day}"
+      end
+
+      def day_header(date)
+        "#{Locale.day_name(date)} #{date.day}/#{date.month}"
+      end
+
+      def slot_range(start_at, end_at)
+        "#{format_time(start_at)} - #{format_time(end_at)}"
+      end
+
+      def format_time(time)
+        return time.strftime("%-H") if time.min.zero?
+
+        minutes = sprintf("%02d", time.min)
+        "#{time.hour}.#{minutes}"
+      end
+    end
+  end
+end

data/lib/flycal/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Flycal
+  # Kept for Zeitwerk (`lib/flycal/version.rb` → Flycal::Version).
+  # Canonical version string lives on Flycal::VERSION (see lib/flycal.rb).
+  module Version
+    def self.to_s
+      Flycal::VERSION
+    end
+  end
+end

data/lib/flycal.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Flycal core namespace.
+# Under Rails, Zeitwerk autoloads lib/flycal/*.
+# The CLI gem entrypoint (flycal_cli/lib/flycal_cli.rb) eager-requires what it needs.
+module Flycal
+  VERSION = "1.0"
+
+  def self.connect(credentials:)
+    Client.new(credentials: credentials)
+  end
+end

data/lib/flycal_cli.rb

@@ -1,17 +1,40 @@
 # frozen_string_literal: true
 
-require "flycal_cli/version"
-require "flycal_cli/config"
-require "flycal_cli/locale"
-require "flycal_cli/auth"
-require "flycal_cli/duration_parser"
-require "flycal_cli/date_time_parser"
-require "flycal_cli/clipboard"
-require "flycal_cli/calendar_service"
-require "flycal_cli/slot_finder"
-require "flycal_cli/slot_formatter"
-require "flycal_cli/cli"
+# Gem entrypoint for the flycal-cli package.
+core_lib = File.expand_path("../../lib", __dir__)
+$LOAD_PATH.unshift(core_lib) unless $LOAD_PATH.include?(core_lib)
+cli_lib = File.expand_path(".", __dir__)
+$LOAD_PATH.unshift(cli_lib) unless $LOAD_PATH.include?(cli_lib)
 
-module FlycalCli
-  class Error < StandardError; end
-end
+# Eager-load Flycal core (outside Rails/Zeitwerk).
+require "flycal/version"
+require "flycal/error"
+require "flycal/locale"
+require "flycal/credentials"
+require "flycal/event_mapper"
+require "flycal/cache_key"
+require "flycal/cache_annotator"
+require "flycal/client"
+require "flycal/duration_parser"
+require "flycal/date_time_parser"
+require "flycal/description_query"
+require "flycal/calendar_query"
+require "flycal/calendar_service"
+require "flycal/slot_finder"
+require "flycal/slot_formatter"
+require "flycal/mock"
+require "flycal/mock/config"
+require "flycal/mock/event_generator"
+require "flycal/mock/calendar_service"
+require "flycal/pipeline"
+require "flycal/pipeline/params"
+require "flycal/pipeline/retriever"
+require "flycal/pipeline/aggregator"
+require "flycal/pipeline/renderer"
+require "flycal/pipeline/text_renderer"
+require "flycal/pipeline/json_renderer"
+require "flycal/pipeline/search_pipeline"
+
+require "flycal/cli"
+
+FlycalCli = Flycal::Cli unless defined?(FlycalCli)

data/mcp/tools.json

@@ -358,7 +358,8 @@
           "to": ["--to", "{value}"],
           "in": ["--in", "{value}"],
           "description": ["--description", "{value}"],
-          "locale": ["--locale", "{value}"]
+          "locale": ["--locale", "{value}"],
+          "format": ["--format", "{value}"]
         },
         "examples": [
           ["flycal", "search"],
@@ -410,6 +411,14 @@
           "enum": ["en", "it"],
           "required": false,
           "description": "Optional locale override."
+        },
+        "format": {
+          "cli": ["--format"],
+          "type": "string",
+          "enum": ["text", "json"],
+          "required": false,
+          "default": "text",
+          "description": "Output format: text (shell) or json (pretty-printed)."
         }
       },
       "inputSchema": {
@@ -440,6 +449,11 @@
             "type": "string",
             "enum": ["en", "it"],
             "description": "--locale. Optional locale override (en, it)."
+          },
+          "format": {
+            "type": "string",
+            "enum": ["text", "json"],
+            "description": "--format. Output format (default: text). json returns params/info/items/groups."
           }
         }
       }
@@ -447,7 +461,7 @@
     {
       "name": "flycal_slots",
       "title": "Find free time slots",
-      "description": "Find continuous free ranges using a slots.templates schedule (days + hours). Default template = first key (usually work). Busy events come from slots.exclude_calendars (or calendar_default if empty). Respects free_before/free_after. Prints header + availability; copies availability list to clipboard when a clipboard tool exists.",
+      "description": "Find continuous free ranges using a slots.templates schedule (days + hours). Default template = first key (usually work). Busy events come from slots.exclude_calendars (or calendar_default if empty). Respects free_before/free_after. Output: text (header + availability, clipboard) or JSON via --format json.",
       "interactive": false,
       "requires_auth": true,
       "command": {
@@ -459,14 +473,16 @@
           "in": ["--in", "{value}"],
           "template": ["--template", "{value}"],
           "calendar": ["--calendar", "{value}"],
-          "locale": ["--locale", "{value}"]
+          "locale": ["--locale", "{value}"],
+          "format": ["--format", "{value}"]
         },
         "examples": [
           ["flycal", "slots"],
           ["flycal", "slots", "--in", "5 days"],
           ["flycal", "slots", "--from", "monday", "--in", "5 days", "--locale", "it"],
           ["flycal", "slots", "--in", "12 days", "--template", "dinner"],
-          ["flycal", "slots", "--from", "next monday", "--duration", "1h", "--template", "work"]
+          ["flycal", "slots", "--from", "next monday", "--duration", "1h", "--template", "work"],
+          ["flycal", "slots", "--format", "json", "--in", "5 days"]
         ]
       },
       "parameters": {
@@ -518,15 +534,21 @@
           "enum": ["en", "it"],
           "required": false,
           "description": "Optional locale override."
+        },
+        "format": {
+          "cli": ["--format"],
+          "type": "string",
+          "enum": ["text", "json"],
+          "required": false,
+          "default": "text",
+          "description": "Output format: text (shell + clipboard) or json (params/info/items/groups)."
         }
       },
       "output": {
-        "format": "text/plain",
+        "format": "text/plain or application/json",
         "includes": [
-          "count + from/to + duration + template",
-          "bullet list of considered calendars",
-          "link: Google Calendar day URL at --from",
-          "availability ranges grouped by day (copied to clipboard without header)"
+          "text: count + from/to + duration + template, calendars, link, ranges by day (clipboard)",
+          "json: params, info (slots_found, calendars, link), flat items, groups by day"
         ],
         "example": "found 6 slots\nfrom sat 1 August 2026 to sat 8 August 2026\nwith duration 45min, template dinner\nconsidering calendars\n- Work\n- Personal\nlink: https://calendar.google.com/calendar/r/day/2026/8/1\n\nsaturday 1/8\n19 - 23"
       },
@@ -559,6 +581,11 @@
             "type": "string",
             "enum": ["en", "it"],
             "description": "--locale. Optional locale override (en, it)."
+          },
+          "format": {
+            "type": "string",
+            "enum": ["text", "json"],
+            "description": "--format. text (default) or json."
           }
         }
       }

data/mockTemplates/mock1.json

@@ -0,0 +1,11 @@
+{
+  "mockCalendar": "mock1",
+  "mockEventDescriptionPatterns": "work,personal,event",
+  "mockEventCount": 100,
+  "mockEventFrom": "2026-01-01",
+  "mockEventTo": "2026-01-31",
+  "mockEventDurationMin": "4h",
+  "mockEventDurationMax": "4h",
+  "mockEventHoursFrom": "09:00",
+  "mockEventHoursTo": "17:00"
+}

data/mocks/mock1.json

@@ -0,0 +1,11 @@
+{
+  "mockCalendar": "mock1",
+  "mockEventDescriptionPatterns": "work,personal,event",
+  "mockEventCount": 100,
+  "mockEventFrom": "2026-01-01",
+  "mockEventTo": "2026-01-31",
+  "mockEventDurationMin": "4h",
+  "mockEventDurationMax": "4h",
+  "mockEventHoursFrom": "09:00",
+  "mockEventHoursTo": "17:00"
+}