flycal-cli 1.0 → 1.2

data/lib/flycal/client.rb

@@ -66,121 +66,96 @@ module Flycal
     # Resolved slots inputs (defaults applied) suitable for CacheKey.generate.
     # Does not call Google APIs.
     def resolve_slots_query(params = {})
-      p = params.respond_to?(:with_indifferent_access) ? params.with_indifferent_access : params
-      calendar_ids = Array(p[:calendar_ids]).map(&:to_s).reject(&:empty?)
-      raise Flycal::Error, "calendar_ids are required" if calendar_ids.empty?
-
-      duration_value = p[:duration].presence || "45min"
-      in_value = p[:in].presence || "1 week"
-      from_value = p[:from].presence || "now"
-      free_before_value = p[:free_before].presence || "0m"
-      free_after_value = p[:free_after].presence || "0m"
-      template_name = p[:template].presence || "work"
-      locale = p[:locale].presence || Locale.current_locale
-
-      slot_duration = DurationParser.to_seconds(duration_value)
-      free_before = DurationParser.to_seconds(free_before_value)
-      free_after = DurationParser.to_seconds(free_after_value)
-      time_min = DateTimeParser.parse(from_value.to_s, locale: locale)
-      time_max = DurationParser.add_to_time(in_value, time_min)
-      raise Flycal::Error, "'from' must be before end of window" if time_min >= time_max
-
-      hours = normalize_hours(p[:hours]) || SlotFinder::DEFAULT_HOURS
-      days = normalize_days(p[:days]) || SlotFinder::DEFAULT_DAYS
-
-      {
-        command: "slots",
-        calendar_ids: calendar_ids,
-        duration: duration_value,
-        from: from_value,
-        in: in_value,
-        free_before: free_before_value,
-        free_after: free_after_value,
-        template: template_name,
-        locale: locale,
-        calendar: p[:calendar],
-        hours: hours,
-        days: days,
-        time_min: time_min,
-        time_max: time_max,
-        slot_duration_seconds: slot_duration,
-        free_before_seconds: free_before,
-        free_after_seconds: free_after,
-        format: p[:format].presence || "json"
-      }
+      SlotQuery.resolve(params)
     end
 
     # Find free slots. +params+ keys (string/symbol):
-    #   calendar_ids (required), duration (e.g. "45min"), from, in,
-    #   free_before, free_after, hours ([[9,0,18,0]]), days ([1..5]),
-    #   template (label), locale, calendar (label for meta)
-    # Returns a Hash suitable for JSON rendering.
-    def slots(params = {})
+    #   calendar_ids (required), duration, from, to, in,
+    #   free_before, free_after, hours, days,
+    #   template (work|dinner), template_custom ({ days:, hours: } YAML shape),
+    #   locale, timezone (IANA, default Europe/Rome or the Google calendar TZ),
+    #   calendar (label for meta)
+    # Pass +events:+ to skip Google (tests / mock).
+    def slots(params = {}, events: nil)
+      previous_locale = Thread.current[:flycal_locale_override]
       p = params.respond_to?(:with_indifferent_access) ? params.with_indifferent_access : params
-      q = resolve_slots_query(p)
 
-      calendars = list_calendars
-      calendar_meta = q[:calendar_ids].filter_map do |id|
-        cal = calendars.find { |c| c.id == id }
-        { id: id, name: cal&.summary || id }
+      calendar_list = nil
+      unless events
+        calendar_list = begin
+          list_calendars
+        rescue StandardError
+          nil
+        end
       end
 
-      fetch_from = q[:time_min] - q[:free_before_seconds]
-      events = q[:calendar_ids].flat_map do |calendar_id|
-        list_events(calendar_id, time_min: fetch_from, time_max: q[:time_max])
-      rescue StandardError => e
-        warn "Flycal slots: skip calendar #{calendar_id}: #{e.message}"
-        []
-      end
-
-      finder = SlotFinder.new(
-        events: events,
-        time_min: q[:time_min],
-        time_max: q[:time_max],
-        slot_duration_seconds: q[:slot_duration_seconds],
-        hours: q[:hours],
-        days: q[:days],
-        free_before_seconds: q[:free_before_seconds],
-        free_after_seconds: q[:free_after_seconds]
+      timezone = TimeFormat.resolve(
+        explicit: p[:timezone],
+        calendars: calendar_list,
+        calendar_ids: p[:calendar_ids]
       )
 
-      SlotFormatter.payload_hash(
-        slots_by_day: finder.slots_by_day,
-        time_min: q[:time_min],
-        time_max: q[:time_max],
-        duration: q[:duration],
-        template: q[:template],
-        calendars: calendar_meta,
-        locale: q[:locale],
-        calendar_option: q[:calendar],
-        from_option: p[:from],
-        in_option: p[:in],
-        free_before: q[:free_before],
-        free_after: q[:free_after],
-        empty_message: Locale.t("slots.no_available")
-      )
+      TimeFormat.with_zone(timezone) do
+        q = resolve_slots_query(p.merge(timezone: timezone))
+        Locale.override!(q[:locale])
+
+        calendar_meta, loaded_events = load_slot_events(q, events, calendars: calendar_list)
+        finder = SlotFinder.new(
+          events: loaded_events,
+          time_min: q[:time_min],
+          time_max: q[:time_max],
+          slot_duration_seconds: q[:slot_duration_seconds],
+          hours: q[:hours],
+          days: q[:days],
+          free_before_seconds: q[:free_before_seconds],
+          free_after_seconds: q[:free_after_seconds]
+        )
+
+        SlotFormatter.payload_hash(
+          slots_by_day: finder.slots_by_day,
+          time_min: q[:time_min],
+          time_max: q[:time_max],
+          duration: q[:duration],
+          template: q[:template],
+          calendars: calendar_meta,
+          locale: q[:locale],
+          timezone: timezone,
+          calendar_option: q[:calendar],
+          from_option: p[:from],
+          to_option: p[:to],
+          in_option: p[:in],
+          free_before: q[:free_before],
+          free_after: q[:free_after],
+          empty_message: Locale.t("slots.no_available")
+        )
+      end
+    ensure
+      Thread.current[:flycal_locale_override] = previous_locale
     end
 
     private
 
-    def normalize_hours(value)
-      return nil if value.blank?
-      return value if value.is_a?(Array) && value.first.is_a?(Array)
+    def load_slot_events(query, events, calendars: nil)
+      if events
+        meta = query[:calendar_ids].map { |id| { id: id, name: id } }
+        return [ meta, Array(events) ]
+      end
 
-      # "9:00-18:00" or ["9:00-18:00", "14:00-17:00"]
-      Array(value).map do |window|
-        start_s, end_s = window.to_s.split("-", 2).map(&:strip)
-        sh, sm = start_s.split(":").map(&:to_i)
-        eh, em = end_s.split(":").map(&:to_i)
-        [ sh, sm, eh, em ]
+      calendars ||= list_calendars
+      meta = query[:calendar_ids].filter_map do |id|
+        cal = calendars.find { |c| c.id == id }
+        { id: id, name: cal&.summary || id }
       end
-    end
 
-    def normalize_days(value)
-      return nil if value.blank?
-      return value.map(&:to_i) if value.is_a?(Array)
+      fetch_from = query[:time_min] - query[:free_before_seconds]
+      loaded = query[:calendar_ids].flat_map do |calendar_id|
+        list_events(calendar_id, time_min: fetch_from, time_max: query[:time_max])
+      rescue StandardError => e
+        warn "Flycal slots: skip calendar #{calendar_id}: #{e.message}"
+        []
+      end
 
-      value.to_s.split(",").map(&:strip).reject(&:empty?).map(&:to_i)
+      [ meta, loaded ]
     end
   end
 end

data/lib/flycal/date_time_parser.rb

@@ -69,7 +69,7 @@ module Flycal
         end
       end
 
-      def parse_or_default(str, default: Time.now, end_of_day: false, locale: nil)
+      def parse_or_default(str, default: TimeFormat.now, end_of_day: false, locale: nil)
         return default if str.nil? || str.to_s.strip.empty?
 
         parse(str, end_of_day: end_of_day, locale: locale)
@@ -83,13 +83,13 @@ module Flycal
 
         case normalized
         when "now", "adesso", "ora"
-          return Time.now
+          return TimeFormat.now
         when "today", "oggi"
-          return time_for_date(Date.today, end_of_day: end_of_day)
+          return time_for_date(TimeFormat.today, end_of_day: end_of_day)
         when "tomorrow", "domani"
-          return time_for_date(Date.today + 1, end_of_day: end_of_day)
+          return time_for_date(TimeFormat.today + 1, end_of_day: end_of_day)
         when "yesterday", "ieri"
-          return time_for_date(Date.today - 1, end_of_day: end_of_day)
+          return time_for_date(TimeFormat.today - 1, end_of_day: end_of_day)
         end
 
         weekday = parse_weekday_phrase(normalized)
@@ -117,7 +117,7 @@ module Flycal
         wday = WEEKDAYS[day_token]
         return nil unless wday
 
-        today = Date.today
+        today = TimeFormat.today
 
         if qualifier.nil? || THIS_WORDS.include?(qualifier)
           next_weekday(today, wday, inclusive: true)
@@ -142,9 +142,10 @@ module Flycal
 
       def time_for_date(date, end_of_day:)
         return end_of_day_for(date) if end_of_day
-        return [date.to_time, Time.now].max if date == Date.today
+        midnight = TimeFormat.local(date.year, date.month, date.day)
+        return [ midnight, TimeFormat.now ].max if date == TimeFormat.today
 
-        date.to_time
+        midnight
       end
 
       def formats_for(locale)
@@ -192,13 +193,13 @@ module Flycal
           return time_for_date(date, end_of_day: end_of_day)
         end
 
-        Time.local(year, month, day, hour, min || 0, sec || 0)
+        TimeFormat.local(year, month, day, hour, min || 0, sec || 0)
       rescue ArgumentError
         raise Flycal::Error, "Invalid date: #{year}-#{month}-#{day}"
       end
 
       def end_of_day_for(date)
-        Time.local(date.year, date.month, date.day, 23, 59, 59)
+        TimeFormat.local(date.year, date.month, date.day, 23, 59, 59)
       end
 
       def time_component?(value)

data/lib/flycal/default_slots.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Flycal
+  # Built-in slot windows shared by Flycal core, HTTP API, and CLI setup.
+  #
+  # CLI writes this fragment into ~/.flycal/config.yml on first load/setup, then
+  # reads templates from disk. API and MCP always read from this class, never
+  # from the user's home file.
+  module DefaultSlots
+    DEFAULTS = {
+      "from" => "now",
+      "default_duration" => "45min"
+    }.freeze
+
+    FREE_BEFORE = "0m"
+    FREE_AFTER = "15m"
+    EXCLUDE_CALENDARS = [].freeze
+
+    module_function
+
+    def templates
+      SlotTemplates::BUILTIN
+    end
+
+    def names
+      SlotTemplates.names(templates)
+    end
+
+    def defaults
+      DEFAULTS
+    end
+
+    def free_before
+      FREE_BEFORE
+    end
+
+    def free_after
+      FREE_AFTER
+    end
+
+    def exclude_calendars
+      EXCLUDE_CALENDARS
+    end
+
+    # YAML-shaped Hash written into ~/.flycal/config.yml under `slots:`.
+    def config_fragment
+      {
+        "templates" => deep_dup(templates),
+        "exclude_calendars" => exclude_calendars.dup,
+        "defaults" => deep_dup(defaults),
+        "free_before" => free_before,
+        "free_after" => free_after
+      }
+    end
+
+    # JSON-friendly payload for API / MCP `slots_templates`.
+    def as_json
+      {
+        "templates" => deep_dup(templates),
+        "defaults" => deep_dup(defaults),
+        "free_before" => free_before,
+        "free_after" => free_after
+      }
+    end
+
+    def deep_dup(value)
+      case value
+      when Hash
+        value.transform_values { |item| deep_dup(item) }
+      when Array
+        value.map { |item| deep_dup(item) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/flycal/mock/event_generator.rb

@@ -6,7 +6,7 @@ module Flycal
     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 Flycal
             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
@@ -56,8 +58,8 @@ module Flycal
       def random_start_on(day, duration_seconds)
         from_h, from_m = @config.hours_from
         to_h, to_m = @config.hours_to
-        window_start = day.to_time + (from_h * 3600) + (from_m * 60)
-        window_end = day.to_time + (to_h * 3600) + (to_m * 60)
+        window_start = TimeFormat.local(day.year, day.month, day.day, from_h, from_m)
+        window_end = TimeFormat.local(day.year, day.month, day.day, to_h, to_m)
         latest_start = window_end - duration_seconds
         if latest_start < window_start
           raise Flycal::Error, "Mock event duration does not fit in the daily hours window."

data/lib/flycal/mock/slot_scenario.rb

@@ -0,0 +1,78 @@
+# 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)
+        timezone = TimeFormat.resolve(explicit: slots[:timezone] || slots["timezone"])
+        TimeFormat.with_zone(timezone) do
+          @events = EventGenerator.new(@config).generate
+          @query = SlotQuery.resolve(
+            { calendar_ids: [ @config.calendar_name ], timezone: timezone }.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
+      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/pipeline/json_renderer.rb

@@ -128,12 +128,8 @@ module Flycal
         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)
-
-        value.to_s
+        TimeFormat.iso8601(value)
       end
 
       def blank_to_nil(value)

data/lib/flycal/pipeline/text_renderer.rb

@@ -32,8 +32,8 @@ module Flycal
         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 << "---"
@@ -105,13 +105,14 @@ module Flycal
         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/slot_finder.rb

@@ -17,8 +17,8 @@ module Flycal
       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)
@@ -69,11 +69,11 @@ module Flycal
 
     def day_intervals(date)
       @hours.map do |start_h, start_m, end_h, end_m|
-        start_at = Time.local(date.year, date.month, date.day, start_h, start_m, 0)
-        end_at = Time.local(date.year, date.month, date.day, end_h, end_m, 0)
-        start_at = [@time_min, start_at].max
-        end_at = [@time_max, end_at].min
-        [start_at, end_at]
+        start_at = TimeFormat.local(date.year, date.month, date.day, start_h, start_m, 0)
+        end_at = TimeFormat.local(date.year, date.month, date.day, end_h, end_m, 0)
+        start_at = [ @time_min, start_at ].max
+        end_at = [ @time_max, end_at ].min
+        [ start_at, end_at ]
       end
     end
 
@@ -151,23 +151,23 @@ module Flycal
     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

@@ -77,8 +77,10 @@ module Flycal
         template:,
         calendars:,
         locale: nil,
+        timezone: nil,
         calendar_option: nil,
         from_option: nil,
+        to_option: nil,
         in_option: nil,
         free_before: nil,
         free_after: nil,
@@ -120,7 +122,9 @@ module Flycal
             "calendar_ids" => Array(calendars).map { |c| c[:id] },
             "format" => "json",
             "locale" => locale || Locale.current_locale,
+            "timezone" => timezone || TimeFormat.zone_name,
             "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
@@ -131,6 +135,7 @@ module Flycal
             "to" => format_iso(time_max),
             "duration" => duration,
             "template" => template,
+            "timezone" => timezone || TimeFormat.zone_name,
             "calendars" => Array(calendars).map { |c| { "id" => c[:id], "name" => c[:name] } },
             "link" => google_calendar_day_url(time_min)
           },
@@ -156,10 +161,7 @@ module Flycal
       end
 
       def format_iso(value)
-        return nil if value.nil?
-        return value.iso8601 if value.respond_to?(:iso8601)
-
-        value.to_s
+        TimeFormat.iso8601(value)
       end
 
       def blank_to_nil(value)
@@ -185,6 +187,8 @@ module Flycal
       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)

data/lib/flycal/slot_query.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/hash/indifferent_access"
+
+module Flycal
+  # Resolves slots search params (template, window, duration) without calling Google.
+  class SlotQuery
+    class << self
+      def resolve(params = {})
+        p = params.respond_to?(:with_indifferent_access) ? params.with_indifferent_access : params
+        calendar_ids = Array(p[:calendar_ids]).map(&:to_s).reject(&:empty?)
+        raise Error, "calendar_ids are required" if calendar_ids.empty?
+
+        timezone = TimeFormat.resolve(explicit: p[:timezone])
+        TimeFormat.with_zone(timezone) { build(p, calendar_ids, timezone) }
+      end
+
+      private
+
+      def build(p, calendar_ids, timezone)
+        duration_value = p[:duration].presence || "45min"
+        from_value = p[:from].presence || "now"
+        free_before_value = p[:free_before].presence || "0m"
+        free_after_value = p[:free_after].presence || "0m"
+        locale = p[:locale].presence || Locale.current_locale
+
+        template = SlotTemplates.resolve(
+          name: p[:template],
+          custom: p[:template_custom],
+          catalog: p[:template_catalog]
+        )
+
+        slot_duration = DurationParser.to_seconds(duration_value)
+        free_before = DurationParser.to_seconds(free_before_value)
+        free_after = DurationParser.to_seconds(free_after_value)
+        time_min = DateTimeParser.parse(from_value.to_s, locale: locale)
+        time_max = resolve_time_max(p, time_min, locale)
+        raise Error, "'from' must be before end of window" if time_min >= time_max
+
+        hours = p[:hours].present? ? SlotTemplates.parse_hours(p[:hours]) : template[:hours]
+        days = p[:days].present? ? SlotTemplates.parse_days(p[:days]) : template[:days]
+        in_value = p[:in].presence
+
+        {
+          command: "slots",
+          calendar_ids: calendar_ids,
+          duration: duration_value,
+          from: from_value,
+          to: p[:to],
+          in: in_value,
+          free_before: free_before_value,
+          free_after: free_after_value,
+          template: template[:name],
+          locale: locale,
+          timezone: timezone,
+          calendar: p[:calendar],
+          hours: hours,
+          days: days,
+          time_min: time_min,
+          time_max: time_max,
+          slot_duration_seconds: slot_duration,
+          free_before_seconds: free_before,
+          free_after_seconds: free_after,
+          format: p[:format].presence || "json"
+        }
+      end
+
+      def resolve_time_max(params, time_min, locale)
+        if params[:in].present?
+          DurationParser.add_to_time(params[:in], time_min)
+        elsif params[:to].present?
+          DateTimeParser.parse(params[:to].to_s, end_of_day: true, locale: locale)
+        else
+          DurationParser.add_to_time("1 week", time_min)
+        end
+      end
+    end
+  end
+end