flycal-cli 1.0 → 1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0683f1fd5316c424662349a75956309890f9fe5d38fd0cd50a4e158f9a7085e1'
-  data.tar.gz: b7507dee7df050d2e4f11bfb80002f82c2d4cb2689daff89c1d4be62f244b5e1
+  metadata.gz: fcbd8c2cfb6f90272cf8cc8cfa489bc99a7487efca11f68560b2d7f96ac92f34
+  data.tar.gz: 21e92239db0dc5b3f587abdd1e859b5e67e67293706f6ec1f50ca34ca4fe0e1d
 SHA512:
-  metadata.gz: ccabe113d4314bacfd16f3072986d9686919acf4c489a7d8cf9ec05e2bb6dddec59576a859cc210485f9ef56afe7ad9a8522432ba37f0976ae10e5385ffe6e93
-  data.tar.gz: 6fb81eb48cb1bc8ed7ea84b8764eb8c677f1a6b346c5a0841a9498aecd63a06b73f1c801e8dee0f915d3ebf20901e74195356d83a3323edf3ef2725c85fdb4d3
+  metadata.gz: 2524fb58d1faecdf6ac6643761315f2586f6fe10b4535f2f50b87418f871665f13c84110c3d627ad2131bb9b2ef95aa171c0e6e1e41b52f87d7b76fd7261493c
+  data.tar.gz: 906c85b9dd3711aa16874a6f41be9851be1accbd07d131b09fb9f6173ed26d0e081f6607b457d606f538ea8861ab98dcff89b6cdab4f482b79ffe0c8af41eb7b

data/config/defaults.yml

@@ -1,30 +1,4 @@
 calendar_default: ~
 locale: en
-slots:
-  templates:
-    work:
-      days:
-        - 1
-        - 2
-        - 3
-        - 4
-        - 5
-      hours:
-        - 9:30-13:00
-        - 14:00-18:30
-    dinner:
-      days:
-        - 1
-        - 2
-        - 3
-        - 4
-        - 5
-        - 6
-      hours:
-        - 19-23
-  exclude_calendars: []
-  defaults:
-    from: now
-    default_duration: 45min
-  free_before: 0m
-  free_after: 15m
+# `slots` is injected from Flycal::DefaultSlots at load/setup time.
+# After first write, the CLI reads templates from this file on disk.

data/lib/flycal/cli/app.rb

@@ -334,14 +334,15 @@ module Cli
       from_value = "now" if from_value.empty?
 
       begin
-        template_name, template = resolve_slots_template(slot_cfg, options[:template])
+        resolved = SlotTemplates.resolve(name: options[:template], catalog: slot_cfg["templates"])
+        template_name = resolved[:name]
+        hours = resolved[:hours]
+        days = resolved[:days]
         slot_duration = DurationParser.to_seconds(duration_value)
         free_before = DurationParser.to_seconds(slot_cfg["free_before"] || "0m")
         free_after = DurationParser.to_seconds(slot_cfg["free_after"] || "0m")
         time_min = parse_slots_from(from_value)
         time_max = DurationParser.add_to_time(in_value, time_min)
-        hours = parse_workhours(template["hours"])
-        days = parse_template_days(template["days"])
       rescue Flycal::Error => e
         puts "Error: #{e.message}"
         exit 1
@@ -686,32 +687,6 @@ module Cli
       DateTimeParser.parse(value)
     end
 
-    def resolve_slots_template(slot_cfg, requested_name)
-      templates = slot_cfg["templates"]
-      raise Flycal::Error, "slots.templates is missing in config.yml." unless templates.is_a?(Hash) && !templates.empty?
-
-      name = requested_name.to_s.strip
-      name = templates.keys.first.to_s if name.empty?
-
-      template = templates[name]
-      unless template.is_a?(Hash)
-        available = templates.keys.join(", ")
-        raise Flycal::Error, "Unknown slots template #{name.inspect}. Available: #{available}"
-      end
-
-      [name, template]
-    end
-
-    def parse_template_days(values)
-      days = Array(values).map(&:to_i)
-      raise Flycal::Error, "slots template days cannot be empty." if days.empty?
-
-      invalid = days.reject { |d| d.between?(1, 7) }
-      raise Flycal::Error, "Invalid template days #{invalid.inspect}. Use 1 (Mon) .. 7 (Sun)." unless invalid.empty?
-
-      days.uniq
-    end
-
     def copy_slots_to_clipboard(text)
       tool = Clipboard.copy(SlotFormatter.strip_ansi(text))
       return unless tool
@@ -720,50 +695,6 @@ module Cli
       puts Locale.t("slots.copied_to_clipboard", tool: tool)
     end
 
-    def parse_hour_minute(value)
-      match = value.to_s.strip.match(/\A(\d{1,2}):(\d{2})\z/)
-      raise Flycal::Error, "Invalid time format #{value.inspect}. Use HH:MM (e.g. 9:00, 18:30)." unless match
-
-      hour = match[1].to_i
-      minute = match[2].to_i
-      unless hour.between?(0, 23) && minute.between?(0, 59)
-        raise Flycal::Error, "Invalid time #{value.inspect}. Hour must be 0-23 and minute 0-59."
-      end
-
-      [hour, minute]
-    end
-
-    def parse_workhours(values)
-      ranges = Array(values).map do |item|
-        start_str, end_str = item.to_s.strip.split("-", 2)
-        raise Flycal::Error, "Invalid hours item #{item.inspect}. Use format like '9-13' or '14:30-18:00'." if start_str.nil? || end_str.nil?
-
-        sh, sm = parse_hour_minute_flexible(start_str)
-        eh, em = parse_hour_minute_flexible(end_str)
-        start_minutes = (sh * 60) + sm
-        end_minutes = (eh * 60) + em
-        raise Flycal::Error, "Invalid hours range #{item.inspect}: end must be after start." if end_minutes <= start_minutes
-
-        [sh, sm, eh, em]
-      end
-
-      raise Flycal::Error, "template hours cannot be empty in config.yml." if ranges.empty?
-
-      ranges.sort_by { |sh, sm, _eh, _em| (sh * 60) + sm }
-    end
-
-    def parse_hour_minute_flexible(value)
-      str = value.to_s.strip
-      if str.match?(/\A\d{1,2}\z/)
-        hour = str.to_i
-        raise Flycal::Error, "Invalid hour #{value.inspect}. Must be 0-23." unless hour.between?(0, 23)
-
-        return [hour, 0]
-      end
-
-      parse_hour_minute(str)
-    end
-
     def resolve_calendar_ids(service, calendar_option)
       calendar_lists = service.list_calendars
       refs = Flycal::CalendarQuery.refs(calendar_option)

data/lib/flycal/cli/config.rb

@@ -159,7 +159,8 @@ module Cli
         @default_values ||= begin
           raise "Defaults file not found: #{DEFAULTS_FILE}" unless File.exist?(DEFAULTS_FILE)
 
-          YAML.load_file(DEFAULTS_FILE) || {}
+          file = YAML.load_file(DEFAULTS_FILE) || {}
+          file.merge("slots" => Flycal::DefaultSlots.config_fragment)
         end
       end
 

data/lib/flycal/client.rb

@@ -66,75 +66,24 @@ 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, 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)
+      Locale.override!(q[:locale])
 
-      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 }
-      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
-
+      calendar_meta, loaded_events = load_slot_events(q, events)
       finder = SlotFinder.new(
-        events: events,
+        events: loaded_events,
         time_min: q[:time_min],
         time_max: q[:time_max],
         slot_duration_seconds: q[:slot_duration_seconds],
@@ -154,33 +103,39 @@ module Flycal
         locale: q[:locale],
         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")
       )
+    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)
+      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/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

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/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)
@@ -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

@@ -79,6 +79,7 @@ module Flycal
         locale: nil,
         calendar_option: nil,
         from_option: nil,
+        to_option: nil,
         in_option: nil,
         free_before: nil,
         free_after: nil,
@@ -121,6 +122,7 @@ module Flycal
             "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
@@ -156,10 +158,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 +184,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,74 @@
+# 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?
+
+        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,
+          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
+
+      private
+
+      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

data/lib/flycal/slot_templates.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Flycal
+  # Named and custom slot windows. YAML/JSON shape matches ~/.flycal/config.yml:
+  #
+  #   days: [1, 2, 3, 4, 5]
+  #   hours:
+  #     - 9:30-13:00
+  #     - 14:00-18:30
+  module SlotTemplates
+    BUILTIN = {
+      "work" => {
+        "days" => [ 1, 2, 3, 4, 5 ],
+        "hours" => [ "9:30-13:00", "14:00-18:30" ]
+      },
+      "dinner" => {
+        "days" => [ 1, 2, 3, 4, 5, 6 ],
+        "hours" => [ "19-23" ]
+      }
+    }.freeze
+
+    module_function
+
+    def names(catalog = nil)
+      normalize_catalog(catalog || DefaultSlots.templates).keys
+    end
+
+    # Resolve a named template, or a custom YAML-shaped hash.
+    # +custom+ wins over +name+ when present.
+    def resolve(name: nil, custom: nil, catalog: nil)
+      if custom_present?(custom)
+        parsed = parse(custom)
+        return parsed.merge(name: "custom")
+      end
+
+      source = normalize_catalog(catalog || DefaultSlots.templates)
+      raise Error, "slots.templates is missing." if source.empty?
+      key = name.to_s.strip
+      key = source.keys.first.to_s if key.empty?
+      definition = source[key]
+      unless definition
+        raise Error, "Unknown slots template #{key.inspect}. Available: #{source.keys.join(", ")}"
+      end
+
+      parse(definition).merge(name: key)
+    end
+
+    def parse(definition)
+      data = indifferent(definition)
+      days = parse_days(data[:days])
+      hours = parse_hours(data[:hours])
+      { days: days, hours: hours }
+    end
+
+    def parse_days(values)
+      days = Array(values).map(&:to_i)
+      raise Error, "slots template days cannot be empty." if days.empty?
+
+      invalid = days.reject { |d| d.between?(1, 7) }
+      raise Error, "Invalid template days #{invalid.inspect}. Use 1 (Mon) .. 7 (Sun)." unless invalid.empty?
+
+      days.uniq
+    end
+
+    def parse_hours(values)
+      return values if values.is_a?(Array) && values.first.is_a?(Array)
+
+      ranges = Array(values).map { |item| parse_hour_range(item) }
+      raise Error, "template hours cannot be empty." if ranges.empty?
+
+      ranges.sort_by { |sh, sm, _eh, _em| (sh * 60) + sm }
+    end
+
+    def parse_hour_range(item)
+      start_str, end_str = item.to_s.strip.split("-", 2)
+      if start_str.nil? || end_str.nil? || start_str.empty? || end_str.empty?
+        raise Error, "Invalid hours item #{item.inspect}. Use format like '9-13' or '14:30-18:00'."
+      end
+
+      sh, sm = parse_clock(start_str)
+      eh, em = parse_clock(end_str)
+      start_minutes = (sh * 60) + sm
+      end_minutes = (eh * 60) + em
+      raise Error, "Invalid hours range #{item.inspect}: end must be after start." if end_minutes <= start_minutes
+
+      [ sh, sm, eh, em ]
+    end
+
+    def parse_clock(value)
+      str = value.to_s.strip
+      if str.match?(/\A\d{1,2}\z/)
+        hour = str.to_i
+        raise Error, "Invalid hour #{value.inspect}. Must be 0-23." unless hour.between?(0, 23)
+
+        return [ hour, 0 ]
+      end
+
+      hour_s, minute_s = str.split(":", 2)
+      hour = hour_s.to_i
+      minute = minute_s.to_i
+      unless hour.between?(0, 23) && minute.between?(0, 59)
+        raise Error, "Invalid time #{value.inspect}. Use HH:MM (e.g. 9:00, 18:30)."
+      end
+
+      [ hour, minute ]
+    end
+
+    def custom_present?(custom)
+      return false if custom.nil?
+      return false if custom.respond_to?(:blank?) && custom.blank?
+      return false if custom.respond_to?(:empty?) && custom.empty?
+
+      true
+    end
+
+    def normalize_catalog(catalog)
+      indifferent(catalog).each_with_object({}) do |(key, value), out|
+        out[key.to_s] = value
+      end
+    end
+
+    def indifferent(value)
+      return {} if value.nil?
+      return value.with_indifferent_access if value.respond_to?(:with_indifferent_access)
+
+      value
+    end
+  end
+end

data/lib/flycal/time_format.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "time"
+require "date"
+
+module Flycal
+  # Single clock for every datetime Flycal emits (JSON + text).
+  #
+  # Instants are converted to process-local Time so start/end/from/to never mix
+  # offsets (e.g. +02:00 vs +00:00) in the same payload.
+  module TimeFormat
+    module_function
+
+    def iso8601(value)
+      time = unified(value)
+      time&.iso8601
+    end
+
+    def unified(value)
+      time = coerce(value)
+      return nil unless time
+
+      Time.at(time.to_f)
+    end
+
+    def coerce(value)
+      return nil if value.nil?
+      return value if value.is_a?(Time)
+      return value.to_time if value.respond_to?(:to_time)
+
+      Time.parse(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/flycal.rb

@@ -4,7 +4,7 @@
 # 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"
+  VERSION = "1.1"
 
   def self.connect(credentials:)
     Client.new(credentials: credentials)

data/lib/flycal_cli.rb

@@ -10,6 +10,7 @@ $LOAD_PATH.unshift(cli_lib) unless $LOAD_PATH.include?(cli_lib)
 require "flycal/version"
 require "flycal/error"
 require "flycal/locale"
+require "flycal/time_format"
 require "flycal/credentials"
 require "flycal/event_mapper"
 require "flycal/cache_key"
@@ -21,11 +22,15 @@ require "flycal/description_query"
 require "flycal/calendar_query"
 require "flycal/calendar_service"
 require "flycal/slot_finder"
+require "flycal/slot_templates"
+require "flycal/default_slots"
+require "flycal/slot_query"
 require "flycal/slot_formatter"
 require "flycal/mock"
 require "flycal/mock/config"
 require "flycal/mock/event_generator"
 require "flycal/mock/calendar_service"
+require "flycal/mock/slot_scenario"
 require "flycal/pipeline"
 require "flycal/pipeline/params"
 require "flycal/pipeline/retriever"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flycal-cli
 version: !ruby/object:Gem::Version
-  version: '1.0'
+  version: '1.1'
 platform: ruby
 authors:
 - flycal-cli
@@ -149,6 +149,7 @@ files:
 - lib/flycal/client.rb
 - lib/flycal/credentials.rb
 - lib/flycal/date_time_parser.rb
+- lib/flycal/default_slots.rb
 - lib/flycal/description_query.rb
 - lib/flycal/duration_parser.rb
 - lib/flycal/error.rb
@@ -158,6 +159,7 @@ files:
 - lib/flycal/mock/calendar_service.rb
 - lib/flycal/mock/config.rb
 - lib/flycal/mock/event_generator.rb
+- lib/flycal/mock/slot_scenario.rb
 - lib/flycal/pipeline.rb
 - lib/flycal/pipeline/aggregator.rb
 - lib/flycal/pipeline/json_renderer.rb
@@ -168,6 +170,9 @@ files:
 - lib/flycal/pipeline/text_renderer.rb
 - lib/flycal/slot_finder.rb
 - lib/flycal/slot_formatter.rb
+- lib/flycal/slot_query.rb
+- lib/flycal/slot_templates.rb
+- lib/flycal/time_format.rb
 - lib/flycal/version.rb
 - lib/flycal_cli.rb
 - locales/en.json