flycal-cli 0.7.7 → 1.1

data/lib/{flycal_cli → flycal}/mock/event_generator.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-module FlycalCli
+module Flycal
   module Mock
     # Builds deterministic fake calendar events from a Mock::Config.
     class EventGenerator
       EventStart = Struct.new(:date_time, :date, keyword_init: true)
       EventEnd = Struct.new(:date_time, :date, keyword_init: true)
-      Event = Struct.new(:summary, :description, :start, :end, keyword_init: true)
+      Event = Struct.new(:summary, :description, :start, :end, :status, :transparency, keyword_init: true)
 
       def initialize(config)
         @config = config
@@ -24,7 +24,9 @@ module FlycalCli
             summary: title,
             description: title,
             start: EventStart.new(date_time: start_at, date: nil),
-            end: EventEnd.new(date_time: end_at, date: nil)
+            end: EventEnd.new(date_time: end_at, date: nil),
+            status: "confirmed",
+            transparency: "opaque"
           )
         end.sort_by { |e| e.start.date_time }
       end
@@ -60,7 +62,7 @@ module FlycalCli
         window_end = day.to_time + (to_h * 3600) + (to_m * 60)
         latest_start = window_end - duration_seconds
         if latest_start < window_start
-          raise FlycalCli::Error, "Mock event duration does not fit in the daily hours window."
+          raise Flycal::Error, "Mock event duration does not fit in the daily hours window."
         end
 
         span = (latest_start - window_start).to_i

data/lib/flycal/mock/slot_scenario.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Flycal
+  module Mock
+    # Generates mock busy events, then computes the free slots those events imply.
+    class SlotScenario
+      DEFAULT_MOCK = {
+        mockCalendar: "mock-calendar",
+        mockEventCount: 8,
+        mockEventFrom: "2026-08-24",
+        mockEventTo: "2026-08-28",
+        mockEventDurationMin: "30m",
+        mockEventDurationMax: "90m",
+        mockEventHoursFrom: "09:00",
+        mockEventHoursTo: "20:00",
+        mockEventDescriptionPatterns: "standup,review"
+      }.freeze
+
+      attr_reader :seed, :events, :query, :slots_by_day, :expected_count, :config
+
+      def self.generate(mock: {}, slots: {})
+        new(mock: mock, slots: slots)
+      end
+
+      def initialize(mock: {}, slots: {})
+        mock_opts = DEFAULT_MOCK.merge(symbolize(mock))
+        @seed = Integer(mock_opts[:mockSeed] || (Random.new_seed & 0xFFFFFFFF))
+        mock_opts[:mockSeed] = @seed
+
+        @config = Config.from_options(mock_opts)
+        @events = EventGenerator.new(@config).generate
+        @query = SlotQuery.resolve(
+          { calendar_ids: [ @config.calendar_name ] }.merge(symbolize(slots))
+        )
+        finder = SlotFinder.new(
+          events: @events,
+          time_min: @query[:time_min],
+          time_max: @query[:time_max],
+          slot_duration_seconds: @query[:slot_duration_seconds],
+          hours: @query[:hours],
+          days: @query[:days],
+          free_before_seconds: @query[:free_before_seconds],
+          free_after_seconds: @query[:free_after_seconds]
+        )
+        @slots_by_day = finder.slots_by_day
+        @expected_count = @slots_by_day.values.sum(&:size)
+      end
+
+      def to_h
+        {
+          seed: seed,
+          expected_count: expected_count,
+          events: events.map { |event| serialize_event(event) },
+          slots_by_day: slots_by_day
+        }
+      end
+
+      private
+
+      def serialize_event(event)
+        {
+          summary: event.summary,
+          start: event.start.date_time,
+          end: event.end.date_time
+        }
+      end
+
+      def symbolize(hash)
+        hash.each_with_object({}) do |(key, value), out|
+          out[key.to_sym] = value
+        end
+      end
+    end
+  end
+end

data/lib/flycal/mock.rb

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

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
@@ -119,18 +129,7 @@ module FlycalCli
       end
 
       def format_time(value)
-        return nil if value.nil?
-        return value.iso8601 if value.respond_to?(:iso8601)
-
-        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")
+        TimeFormat.iso8601(value)
       end
 
       def blank_to_nil(value)

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
@@ -32,14 +32,15 @@ module FlycalCli
         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")
+        from_str = TimeFormat.unified(time_min)&.strftime("%a %Y-%m-%d %H:%M") || "-"
+        to_str = TimeFormat.unified(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]
@@ -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
@@ -104,13 +105,14 @@ module FlycalCli
         return "-" if dt.nil?
         return dt if dt.is_a?(String)
 
-        "#{Locale.day_abbr(dt)} #{dt.strftime("%Y-%m-%d %H:%M")}"
+        t = TimeFormat.unified(dt)
+        "#{Locale.day_abbr(t)} #{t.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
+        t = TimeFormat.unified(dt)
         "#{Locale.day_abbr(t)} #{t.strftime("%Y-%m-%d")}"
       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
@@ -17,8 +17,8 @@ module FlycalCli
       free_after_seconds: 0
     )
       @events = events
-      @time_min = time_min
-      @time_max = time_max
+      @time_min = TimeFormat.unified(time_min)
+      @time_max = TimeFormat.unified(time_max)
       @slot_duration_seconds = slot_duration_seconds
       @hours = hours
       @days = Array(days).map(&:to_i)
@@ -151,23 +151,23 @@ module FlycalCli
     end
 
     def round_up_15(time)
-      sec = time.to_i
-      remainder = sec % STEP_SECONDS
+      time = to_time(time)
+      remainder = time.to_i % STEP_SECONDS
       return time if remainder.zero?
 
-      Time.at(sec + (STEP_SECONDS - remainder))
+      time + (STEP_SECONDS - remainder)
     end
 
     def round_down_15(time)
-      sec = time.to_i
-      Time.at(sec - (sec % STEP_SECONDS))
+      time = to_time(time)
+      remainder = time.to_i % STEP_SECONDS
+      return time if remainder.zero?
+
+      time - remainder
     end
 
     def to_time(value)
-      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)
+      TimeFormat.unified(value)
     end
   end
 end

data/lib/flycal/slot_formatter.rb

@@ -0,0 +1,196 @@
+# 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,
+        to_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),
+            "to_option" => blank_to_nil(to_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)
+        TimeFormat.iso8601(value)
+      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)
+        time = TimeFormat.unified(time)
+        return "" unless time
+        return time.strftime("%-H") if time.min.zero?
+
+        minutes = sprintf("%02d", time.min)
+        "#{time.hour}.#{minutes}"
+      end
+    end
+  end
+end