flycal-cli 0.7.7 → 1.0

data/lib/{flycal_cli → flycal}/pipeline/aggregator.rb

@@ -4,7 +4,7 @@ require "active_support/core_ext/date"
 require "active_support/core_ext/integer"
 require "active_support/core_ext/time"
 
-module FlycalCli
+module Flycal
   module Pipeline
     # Second pipeline layer: group events and compute aggregate metrics.
     #
@@ -14,10 +14,10 @@ module FlycalCli
     #   month — timeframe > 30 days
     #
     # Override with params[:group_by_option] / --groupBy:
-    #   day | week | month | description
+    #   day | week | month | <any other string> (split on | for string grouping)
     class Aggregator
       HOURS_PER_WORKING_DAY = 8
-      ALLOWED_GROUP_BY = %w[day week month description].freeze
+      TIME_GROUP_BY = %w[day week month].freeze
 
       def call(params)
         time_min = params[:time_min]
@@ -49,7 +49,7 @@ module FlycalCli
           case group_by
           when "week" then weekly_groups(events, ranges, time_min, time_max)
           when "month" then monthly_groups(events, ranges, time_min, time_max)
-          when "description" then description_groups(events, params[:description])
+          when "string" then string_groups(events, params[:group_by_option])
           else daily_groups(events, ranges, time_min, time_max)
           end
 
@@ -57,21 +57,18 @@ module FlycalCli
       end
 
       def self.resolve_group_by(timeframe_days, explicit = nil)
-        key = explicit.to_s.strip.downcase
-        unless key.empty?
-          unless ALLOWED_GROUP_BY.include?(key)
-            raise FlycalCli::Error,
-                  "Unsupported groupBy #{explicit.inspect}. Available: #{ALLOWED_GROUP_BY.join(", ")}"
+        raw = explicit.to_s.strip
+        if raw.empty?
+          if timeframe_days > 30
+            "month"
+          elsif timeframe_days > 7
+            "week"
+          else
+            "day"
           end
-          return key
-        end
-
-        if timeframe_days > 30
-          "month"
-        elsif timeframe_days > 7
-          "week"
         else
-          "day"
+          key = raw.downcase
+          TIME_GROUP_BY.include?(key) ? key : "string"
         end
       end
 
@@ -163,11 +160,11 @@ module FlycalCli
         groups
       end
 
-      def description_groups(events, description_query)
-        patterns = DescriptionQuery.patterns(description_query)
+      def string_groups(events, group_by_string)
+        patterns = DescriptionQuery.patterns(group_by_string)
         if patterns.empty?
-          raise FlycalCli::Error,
-                "groupBy description requires --description with at least one term (e.g. rui|solver)."
+          raise Flycal::Error,
+                "groupBy string requires at least one term (e.g. --groupBy \"rui|solver\")."
         end
 
         patterns.each_with_index.map do |pattern, idx|
@@ -183,13 +180,13 @@ module FlycalCli
             period_label_end: nil,
             total_minutes: minutes,
             events: matched,
-            description: pattern
+            string: pattern
           )
         end
       end
 
       def build_group(index:, key:, start_at:, end_at:, period_label_end:, total_minutes:, events:,
-                      month_name: nil, description: nil)
+                      month_name: nil, string: nil)
         {
           index: index,
           key: key,
@@ -197,7 +194,7 @@ module FlycalCli
           end_at: end_at,
           period_label_end: period_label_end,
           month_name: month_name,
-          description: description,
+          string: string,
           event_count: events.size,
           total_minutes: total_minutes,
           hours: (total_minutes / 60.0).round(1),

data/lib/{flycal_cli → flycal}/pipeline/json_renderer.rb

@@ -2,7 +2,7 @@
 
 require "json"
 
-module FlycalCli
+module Flycal
   module Pipeline
     # Pretty-printed JSON output for search (API / tooling friendly).
     class JsonRenderer < Renderer
@@ -10,6 +10,7 @@ module FlycalCli
         payload = {
           "params" => build_params(params),
           "info" => build_info(params),
+          "text" => lines_for_output(TextRenderer.new.render(params)),
           "items" => Array(params[:events]).map { |ev| serialize_event(ev) },
           "groups" => build_groups(params)
         }
@@ -19,6 +20,14 @@ module FlycalCli
 
       private
 
+      def strip_ansi(text)
+        text.to_s.gsub(/\e\[[0-9;]*m/, "")
+      end
+
+      def lines_for_output(text)
+        strip_ansi(text).split("\n")
+      end
+
       def build_params(params)
         out = {
           "command" => params[:command] || "search",
@@ -57,6 +66,7 @@ module FlycalCli
           "total_working_days" => totals[:working_days].to_f
         }
         info["mock_seed"] = params[:mock_seed] if params[:use_mock] && !params[:mock_seed].nil?
+        info["cache"] = params[:cache_status] if params[:cache_status]
         info
       end
 
@@ -72,11 +82,11 @@ module FlycalCli
             "events_found" => group[:event_count] || Array(group[:events]).size,
             "items" => Array(group[:events]).map { |ev| serialize_event(ev) }
           }.tap do |g|
-            if type == "description"
-              g["description"] = group[:description] || group[:key]
+            if type == "string"
+              g["string"] = group[:string] || group[:key]
             else
-              g["from"] = format_group_boundary(group[:start_at])
-              g["to"] = format_group_boundary(group[:end_at])
+              g["from"] = format_time(group[:start_at])
+              g["to"] = format_time(group[:end_at])
             end
             g["month_name"] = group[:month_name] if group[:month_name]
           end
@@ -118,6 +128,7 @@ module FlycalCli
         end
       end
 
+      # Google Calendar-style ISO-8601 datetime, e.g. 2026-07-29T14:41:00+00:00
       def format_time(value)
         return nil if value.nil?
         return value.iso8601 if value.respond_to?(:iso8601)
@@ -125,14 +136,6 @@ module FlycalCli
         value.to_s
       end
 
-      # Compact local datetime used on group boundaries: YYYYMMDDTHHMMSS
-      def format_group_boundary(value)
-        return nil if value.nil?
-
-        t = value.respond_to?(:to_time) ? value.to_time : value
-        t.strftime("%Y%m%dT%H%M%S")
-      end
-
       def blank_to_nil(value)
         str = value.to_s
         str.empty? ? nil : str

data/lib/{flycal_cli → flycal}/pipeline/params.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module FlycalCli
+module Flycal
   module Pipeline
     # Mutable bag of CLI + derived parameters passed through the pipeline.
     class Params

data/lib/{flycal_cli → flycal}/pipeline/renderer.rb

@@ -1,19 +1,19 @@
 # frozen_string_literal: true
 
-module FlycalCli
+module Flycal
   module Pipeline
     # Third pipeline layer: render aggregated results to a chosen format.
     class Renderer
       FORMATS = {
-        "text" => "FlycalCli::Pipeline::TextRenderer",
-        "json" => "FlycalCli::Pipeline::JsonRenderer"
+        "text" => "Flycal::Pipeline::TextRenderer",
+        "json" => "Flycal::Pipeline::JsonRenderer"
       }.freeze
 
       def self.for(format)
         key = format.to_s.strip.downcase
         key = "text" if key.empty?
         class_name = FORMATS[key]
-        raise FlycalCli::Error, "Unsupported format #{format.inspect}. Available: #{FORMATS.keys.join(", ")}" unless class_name
+        raise Flycal::Error, "Unsupported format #{format.inspect}. Available: #{FORMATS.keys.join(", ")}" unless class_name
 
         Object.const_get(class_name).new
       end

data/lib/{flycal_cli → flycal}/pipeline/retriever.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module FlycalCli
+module Flycal
   module Pipeline
     # First pipeline layer: fetch calendar events for the requested timeframe.
     class Retriever

data/lib/{flycal_cli → flycal}/pipeline/search_pipeline.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module FlycalCli
+module Flycal
   module Pipeline
     # Orchestrates Retriever → Aggregator → Renderer for search.
     class SearchPipeline

data/lib/{flycal_cli → flycal}/pipeline/text_renderer.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module FlycalCli
+module Flycal
   module Pipeline
     # Shell text output — preserves the historical flycal search formatting.
     class TextRenderer < Renderer
@@ -40,6 +40,7 @@ module FlycalCli
         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]
@@ -52,21 +53,21 @@ module FlycalCli
           lines << "By month:"
           lines.concat(month_group_lines(params[:groups]))
         when "day"
-          if explicit_group_by?(params, "day")
+          if explicit_time_group_by?(params, "day")
             lines << ""
             lines << "By day:"
             lines.concat(day_group_lines(params[:groups]))
           end
-        when "description"
+        when "string"
           lines << ""
-          lines << "By description:"
-          lines.concat(description_group_lines(params[:groups]))
+          lines << "By string:"
+          lines.concat(string_group_lines(params[:groups]))
         end
 
         lines
       end
 
-      def explicit_group_by?(params, value)
+      def explicit_time_group_by?(params, value)
         params[:group_by_option].to_s.strip.downcase == value
       end
 
@@ -93,9 +94,9 @@ module FlycalCli
         end
       end
 
-      def description_group_lines(groups)
+      def string_group_lines(groups)
         Array(groups).map do |g|
-          label = g[:description] || g[:key]
+          label = g[:string] || g[:key]
           "  #{bold(g[:index])}. #{label}: #{g[:event_count]} events, #{format_hours_and_days(g[:hours], g[:working_days])}"
         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,20 +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/description_query"
-require "flycal_cli/calendar_service"
-require "flycal_cli/slot_finder"
-require "flycal_cli/slot_formatter"
-require "flycal_cli/mock"
-require "flycal_cli/pipeline"
-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

@@ -461,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": {
@@ -473,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": {
@@ -532,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"
       },
@@ -573,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."
           }
         }
       }