flycal-cli 0.7.4 → 0.7.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bfdf39ef3561cb1c12829bd2d28dfaf9c2062df7f4c4a163ee99e057af9d413
-  data.tar.gz: 8f0ee70cc004bfd8e29a1fd4c5d7b5d852c22a3958f2de596cc2c77f9ed044f8
+  metadata.gz: db8d0ab49b0872b92c469825aff6a0a944f9012eed76c8bc0768bc82156de1f9
+  data.tar.gz: 16e758564b7adee8f7ea53b79c856865105afc26aa8489abe73313906f35ceb5
 SHA512:
-  metadata.gz: 8069638ac5162722bc332a577833da48fb92161ee0b2ca39d6c7c31d1c4aeedecaebcc6bf696f0f9945306bbc4e99b8921718867356b5be87a9d1c22b10ff53e
-  data.tar.gz: 0bdca914927e92b873e91d42b7a061502a9558a858e392d1df1c93509c7ec85a281c5f47e309e011fd1ef734259c991a6d3fa761ecd520b5e6913a4d6f83590f
+  metadata.gz: 9485b33d254189f6f96d4c96f9e8867b047b35354fc60f63da86b8bd84612686afb559b6d5d937b98f41ac091777fd32a25ef1d0827a0cc6f4eb7f11be2287e5
+  data.tar.gz: c9b338282c8fa1ecc7a6b979d6c7c8632fcfe03ae598affdb27b98e603545dfb85e688d9d1180569bea2106094322fb9b664f48db89a731dade13d6c80ed2fe9

data/README.md

@@ -141,9 +141,16 @@ flycal config
 | `--from` / `-f` | today midnight | Absolute or relative date |
 | `--to` / `-t` | +30 days | Ignored if `--in` is set |
 | `--in` / `-i` | — | Duration from `--from` |
-| `--description` / `-d` | — | Contains filter on title/description |
+| `--description` / `-d` | — | Contains filter; OR terms with `\|` (e.g. `rui\|solver`) |
+| `--groupBy` | auto | `day`, `week`, `month`, or `description` (split `--description` terms) |
 | `--calendar` / `-c` | `calendar_default` | Name or ID |
 | `--locale` | config / `en` | `en` or `it` |
+| `--format` | `text` | Output format: `text` or `json` |
+| `--mockTemplate` | — | Load mock defaults from `mocks/` or `mockTemplates/<name>.json` (no Google API) |
+| `--mockCalendar` | from template | Generated mock calendar name/id (required in template or CLI) |
+| `--mockSeed` | random | Reproducible mock distribution (printed in summary) |
+
+Mock templates live in `mocks/` or `mockTemplates/` (example: `mock1.json` with `mockCalendar`). CLI mock flags override template values. Search `--from` / `--to` keep the normal defaults (today → +30 days), independent of the mock generation window.
 
 Relative dates work in English and Italian: `today`/`oggi`, `tomorrow`/`domani`, `monday`/`lunedi`, `next monday`/`prossimo lunedi`, `last friday`/`scorso venerdi`.
 

data/lib/flycal_cli/calendar_service.rb

@@ -57,14 +57,11 @@ module FlycalCli
         end
       end
 
-      # Filter: only events where summary or description contains the search string (case-insensitive)
+      # Filter: summary/description contains any OR term from query ("a|b"), case-insensitive.
       if query && !query.to_s.strip.empty?
-        q = query.strip.downcase
         all_events.select! do |item|
           event = item[:event]
-          summary = (event.summary || "").downcase
-          description = (event.description || "").downcase
-          summary.include?(q) || description.include?(q)
+          DescriptionQuery.match?(event.summary, event.description, query)
         end
       end
 

data/lib/flycal_cli/cli.rb

@@ -13,6 +13,8 @@ module FlycalCli
   class Cli < Thor
     package_name "flycal"
     class_option :locale, type: :string, desc: "Override locale for this command (e.g. en, it)"
+    class_option :format, type: :string, default: "text",
+                 desc: "Output format: text or json"
 
     def self.exit_on_failure?
       true
@@ -119,20 +121,56 @@ module FlycalCli
                           Format: 30days, 48hours, 2months, 1year (no space).
                           With space use quotes: --in "30 days"
 
+      Mock mode (no Google API; triggered by --mockCalendar or --mockTemplate):
+        --mockTemplate NAME   Load defaults from mocks/ or mockTemplates/NAME.json
+        --mockCalendar NAME   Mock calendar id/name (required here or in template)
+        --mockSeed N          Reproducible random distribution
+        --mockEventCount N
+        --mockEventFrom/--mockEventTo
+        --mockEventDescriptionPatterns a,b,c
+        --mockEventDurationMin/--mockEventDurationMax
+        --mockEventHoursFrom/--mockEventHoursTo
+
       Examples:
         flycal search
         flycal search --in 30days -d placeholder
         flycal search -i 1months --description placeholder
         flycal search -f 2025-03-01 --in 2months
+        flycal search --mockTemplate mock1 --description work --calendar mock1
+        flycal search -d "rui|solver" --groupBy description --format json
     LONGDESC
     option :calendar, type: :string, aliases: "-c", desc: "Calendar name or ID"
     option :from, type: :string, aliases: "-f", desc: "Start (default: today midnight)"
     option :to, type: :string, aliases: "-t", desc: "End (default: 23:59 of day 30)"
     option :in, type: :string, aliases: "-i", desc: "Duration: 30days, 48hours, 2months, 1year (overrides --to)"
-    option :description, type: :string, aliases: "-d", desc: "Filter by text in event"
+    option :description, type: :string, aliases: "-d",
+           desc: "Filter text in event (OR with |, e.g. rui|solver)"
+    option :groupBy, type: :string,
+           desc: "Grouping: day, week, month, or description (default: auto from timeframe)"
+    option :mockTemplate, type: :string, desc: "Load mock defaults from mocks/<name>.json"
+    option :mockCalendar, type: :string, desc: "Use a generated mock calendar (skips Google API)"
+    option :mockSeed, type: :numeric, desc: "Seed for reproducible mock events"
+    option :mockEventDescriptionPatterns, type: :string, desc: "Comma-separated title patterns (e.g. work,personal)"
+    option :mockEventCount, type: :numeric, desc: "Number of mock events to generate"
+    option :mockEventFrom, type: :string, desc: "Mock events start date"
+    option :mockEventTo, type: :string, desc: "Mock events end date"
+    option :mockEventDurationMin, type: :string, desc: "Min mock event duration (e.g. 4h)"
+    option :mockEventDurationMax, type: :string, desc: "Max mock event duration (e.g. 4h)"
+    option :mockEventHoursFrom, type: :string, desc: "Daily start window for mock events (HH:MM)"
+    option :mockEventHoursTo, type: :string, desc: "Daily end window for mock events (HH:MM)"
     def search
       apply_locale_override
-      unless Auth.logged_in?
+
+      mock_mode = Mock::Config.enabled?(options)
+      mock_config = nil
+      if mock_mode
+        begin
+          mock_config = Mock::Config.from_options(options)
+        rescue FlycalCli::Error => e
+          puts "Error: #{e.message}"
+          exit 1
+        end
+      elsif !Auth.logged_in?
         puts "You are not connected. Run 'flycal login' first."
         exit 1
       end
@@ -154,24 +192,50 @@ module FlycalCli
         exit 1
       end
 
-      creds = Auth.credentials
-      service = CalendarService.new(creds)
+      service =
+        if mock_config
+          Mock::CalendarService.new(mock_config)
+        else
+          CalendarService.new(Auth.credentials)
+        end
 
-      calendar_ids = resolve_calendar_ids(service, options[:calendar])
+      calendar_ids =
+        if mock_config && options[:calendar].to_s.empty?
+          [mock_config.calendar_name]
+        else
+          resolve_calendar_ids(service, options[:calendar])
+        end
       if calendar_ids.empty?
         puts "No calendars found."
         exit 1
       end
 
-      events = service.list_all_events(
-        calendar_ids,
+      params = Pipeline::Params.new(
+        command: "search",
         time_min: time_min,
         time_max: time_max,
-        query: options[:description]
+        calendar_ids: calendar_ids,
+        description: options[:description],
+        calendar: options[:calendar],
+        from_option: options[:from],
+        to_option: options[:to],
+        in_option: options[:in],
+        group_by_option: options[:groupBy],
+        format: options[:format] || "text",
+        locale: Locale.current_locale,
+        use_mock: !mock_config.nil?,
+        mock_seed: mock_config&.seed,
+        mock_calendar: mock_config&.calendar_name,
+        mock_template: mock_config&.template_name
       )
 
-      print_events(service, events)
-      print_search_summary(events, time_min: time_min, time_max: time_max)
+      begin
+        output = Pipeline::SearchPipeline.new(service).run(params)
+        print output
+      rescue FlycalCli::Error => e
+        puts "Error: #{e.message}"
+        exit 1
+      end
     end
 
     desc "slots", "Find available time slots in your calendar"
@@ -318,8 +382,6 @@ module FlycalCli
 
     private
 
-    HOURS_PER_WORKING_DAY = 8
-
     def bold(str)
       "\e[1m#{str}\e[0m"
     end
@@ -580,141 +642,5 @@ module FlycalCli
 
       matches.map(&:id)
     end
-
-    def print_events(service, events)
-      # Use calendar list for names (avoids extra API calls)
-      calendar_list = service.list_calendars
-      calendar_names = calendar_list.to_h { |c| [c.id, c.summary || c.id] }
-
-      events.each do |item|
-        cal_id = item[:calendar_id]
-        event = item[:event]
-        cal_name = calendar_names[cal_id] || cal_id
-
-        start_time = event.start&.date_time || event.start&.date
-        end_time = event.end&.date_time || event.end&.date
-
-        start_str = format_datetime(start_time)
-        end_str = format_datetime(end_time)
-        desc = event.summary || "(no title)"
-        desc = event.description&.slice(0, 80) if event.summary.nil? && event.description
-
-        puts "#{cal_name} | #{start_str} | #{end_str} | #{desc}"
-      end
-    end
-
-    def format_datetime(dt)
-      return "-" if dt.nil?
-
-      if dt.is_a?(String)
-        dt
-      else
-        "#{Locale.day_abbr(dt)} #{dt.strftime("%Y-%m-%d %H:%M")}"
-      end
-    end
-
-    def format_date_with_day(dt)
-      return "-" if dt.nil?
-
-      t = dt.respond_to?(:to_time) ? dt.to_time : dt
-      "#{Locale.day_abbr(t)} #{t.strftime("%Y-%m-%d")}"
-    end
-
-    def print_search_summary(events, time_min:, time_max:)
-      event_ranges = extract_event_ranges(events)
-      total_minutes = event_ranges.sum { |s, e| (e - s) / 60 }
-
-      from_str = time_min.strftime("%a %Y-%m-%d %H:%M")
-      to_str = time_max.strftime("%a %Y-%m-%d %H:%M")
-
-      puts "\n---"
-      puts "From: #{from_str} | To: #{to_str}"
-      puts "Events found: #{events.size}"
-      puts "Total time occupied: #{format_duration(total_minutes)}"
-
-      frame_days = (time_max - time_min) / 86400.0
-      if frame_days > 30
-        print_monthly_breakdown(event_ranges, time_min, time_max)
-      elsif frame_days > 7
-        print_weekly_breakdown(event_ranges, time_min, time_max)
-      end
-    end
-
-    def extract_event_ranges(events)
-      events.filter_map do |item|
-        event = item[:event]
-        start_t = event.start&.date_time || event.start&.date
-        end_t = event.end&.date_time || event.end&.date
-        next if start_t.nil? || end_t.nil?
-
-        start_t = start_t.to_time if start_t.respond_to?(:to_time)
-        end_t = end_t.to_time if end_t.respond_to?(:to_time)
-        [start_t, end_t]
-      end
-    end
-
-    def format_duration(total_minutes)
-      hours = (total_minutes / 60).floor
-      mins = (total_minutes % 60).round
-      working_days = (total_minutes / 60.0 / HOURS_PER_WORKING_DAY).round(1)
-      "#{bold(hours)}h #{bold(mins)}min (#{bold(working_days)} working days)"
-    end
-
-    def format_hours_and_days(hours, working_days)
-      "#{bold(hours)}h (#{bold(working_days)} working days)"
-    end
-
-    def minutes_in_period(event_ranges, period_start, period_end)
-      event_ranges.sum do |ev_start, ev_end|
-        overlap_start = [ev_start, period_start].max
-        overlap_end = [ev_end, period_end].min
-        overlap_sec = overlap_end - overlap_start
-        overlap_sec > 0 ? overlap_sec / 60.0 : 0
-      end
-    end
-
-    def print_weekly_breakdown(event_ranges, time_min, time_max)
-      puts "\nBy week:"
-      week_num = 1
-      current = time_min.to_date.beginning_of_week(:monday)
-      while current.to_time < time_max
-        week_start = [current.to_time, time_min].max
-        week_end_date = current.end_of_week(:monday)
-        week_end = [week_end_date.to_time + 1.day, time_max].min
-        mins = minutes_in_period(event_ranges, week_start, week_end)
-        hours = (mins / 60).round(1)
-        working_days = (mins / 60.0 / HOURS_PER_WORKING_DAY).round(1)
-        start_str = format_date_with_day(week_start)
-        end_str = format_date_with_day(week_end_date)
-        puts "  #{bold(week_num)}. #{start_str} - #{end_str}: #{format_hours_and_days(hours, working_days)}"
-        week_num += 1
-        current = current + 7.days
-      end
-    end
-
-    def print_monthly_breakdown(event_ranges, time_min, time_max)
-      puts "\nBy month:"
-      month_num = 1
-      current = time_min.to_date.beginning_of_month
-      end_date = time_max.to_date
-
-      while current <= end_date
-        month_start = current.beginning_of_month.to_time
-        month_end = (current.end_of_month + 1.day).to_time
-        period_start = [month_start, time_min].max
-        period_end = [month_end, time_max].min
-
-        mins = minutes_in_period(event_ranges, period_start, period_end)
-        hours = (mins / 60).round(1)
-        working_days = (mins / 60.0 / HOURS_PER_WORKING_DAY).round(1)
-        month_name = "#{Locale.month_name(current)} #{current.year}"
-        start_str = format_date_with_day(period_start)
-        last_day = (period_end.to_date - 1.day)
-        end_str = format_date_with_day(last_day)
-        puts "  #{month_num}. #{month_name} (#{start_str} - #{end_str}): #{format_hours_and_days(hours, working_days)}"
-        month_num += 1
-        current = current.next_month.beginning_of_month
-      end
-    end
   end
 end

data/lib/flycal_cli/description_query.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module FlycalCli
+  # Shared helpers for --description filtering and --groupBy description.
+  #
+  # OR terms are separated by "|" (also "," for grouping convenience).
+  # Matching is case-insensitive against event summary and description.
+  module DescriptionQuery
+    module_function
+
+    def patterns(query)
+      query.to_s.split(/[|,]/).map(&:strip).reject(&:empty?)
+    end
+
+    def match?(event_summary, event_description, query)
+      terms = patterns(query)
+      return true if terms.empty?
+
+      summary = event_summary.to_s.downcase
+      description = event_description.to_s.downcase
+      terms.any? { |term| summary.include?(term.downcase) || description.include?(term.downcase) }
+    end
+
+    def match_term?(event_summary, event_description, term)
+      needle = term.to_s.downcase
+      return false if needle.empty?
+
+      event_summary.to_s.downcase.include?(needle) ||
+        event_description.to_s.downcase.include?(needle)
+    end
+  end
+end

data/lib/flycal_cli/mock/calendar_service.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module FlycalCli
+  module Mock
+    # Duck-typed CalendarService backed by generated mock events (no Google API).
+    class CalendarService
+      Calendar = Struct.new(:id, :summary, :primary, keyword_init: true)
+
+      def initialize(config)
+        @config = config
+        @calendar_id = config.calendar_name
+        @events = EventGenerator.new(config).generate
+      end
+
+      def list_calendars
+        [Calendar.new(id: @calendar_id, summary: @calendar_id, primary: true)]
+      end
+
+      def list_all_events(calendar_ids, time_min:, time_max:, query: nil)
+        ids = Array(calendar_ids)
+        return [] unless ids.empty? || ids.include?(@calendar_id)
+
+        items = @events.filter_map do |event|
+          start_at = event.start.date_time
+          end_at = event.end.date_time
+          next if start_at.nil? || end_at.nil?
+          next if end_at <= time_min || start_at >= time_max
+
+          { calendar_id: @calendar_id, event: event }
+        end
+
+        if query && !query.to_s.strip.empty?
+          items.select! do |item|
+            event = item[:event]
+            DescriptionQuery.match?(event.summary, event.description, query)
+          end
+        end
+
+        items
+      end
+    end
+  end
+end

data/lib/flycal_cli/mock/config.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FlycalCli
+  module Mock
+    # Resolves mock options from CLI and/or a JSON template under mocks/.
+    class Config
+      TEMPLATE_KEYS = %w[
+        mockCalendar
+        mockEventDescriptionPatterns
+        mockEventCount
+        mockEventFrom
+        mockEventTo
+        mockEventDurationMin
+        mockEventDurationMax
+        mockEventHoursFrom
+        mockEventHoursTo
+        mockSeed
+      ].freeze
+
+      attr_reader :calendar_name, :seed, :patterns, :count,
+                  :range_from, :range_to, :duration_min_seconds, :duration_max_seconds,
+                  :hours_from, :hours_to, :template_name, :raw
+
+      def self.enabled?(options)
+        !options[:mockTemplate].to_s.empty? || !options[:mockCalendar].to_s.empty?
+      end
+
+      def self.from_options(options)
+        new(options)
+      end
+
+      def initialize(options)
+        merged = load_template(options[:mockTemplate])
+        TEMPLATE_KEYS.each do |key|
+          sym = key.to_sym
+          value = options[sym]
+          next if value.nil? || value.to_s.empty?
+
+          merged[key] = value
+        end
+
+        @template_name = options[:mockTemplate].to_s.empty? ? nil : options[:mockTemplate].to_s
+        calendar = merged["mockCalendar"].to_s
+        calendar = options[:mockCalendar].to_s if calendar.empty?
+        @calendar_name = calendar
+        raise FlycalCli::Error,
+              "Mock mode requires mockCalendar in the template (or --mockCalendar)." if @calendar_name.empty?
+
+        @raw = merged
+        @patterns = split_patterns(merged["mockEventDescriptionPatterns"])
+        @count = Integer(merged["mockEventCount"])
+        @range_from = parse_date(merged["mockEventFrom"], end_of_day: false)
+        @range_to = parse_date(merged["mockEventTo"], end_of_day: true)
+        @duration_min_seconds = DurationParser.to_seconds(merged["mockEventDurationMin"].to_s)
+        @duration_max_seconds = DurationParser.to_seconds(merged["mockEventDurationMax"].to_s)
+        @hours_from = parse_hour_minute(merged["mockEventHoursFrom"])
+        @hours_to = parse_hour_minute(merged["mockEventHoursTo"])
+        @seed = resolve_seed(merged["mockSeed"])
+
+        validate!
+      end
+
+      def to_h
+        {
+          mock_calendar: calendar_name,
+          mock_seed: seed,
+          mock_template: template_name,
+          mock_event_description_patterns: patterns.join(","),
+          mock_event_count: count,
+          mock_event_from: range_from,
+          mock_event_to: range_to,
+          mock_event_duration_min: duration_min_seconds,
+          mock_event_duration_max: duration_max_seconds,
+          mock_event_hours_from: hours_from,
+          mock_event_hours_to: hours_to
+        }
+      end
+
+      private
+
+      def load_template(name)
+        return {} if name.to_s.empty?
+
+        path = find_template_path(name)
+        raise FlycalCli::Error, "Mock template not found: #{name.inspect} (looked in ./mocks, ./mockTemplates, and gem paths)." unless path
+
+        data = JSON.parse(File.read(path))
+        raise FlycalCli::Error, "Mock template #{name.inspect} must be a JSON object." unless data.is_a?(Hash)
+
+        data
+      rescue JSON::ParserError => e
+        raise FlycalCli::Error, "Invalid mock template JSON (#{name}): #{e.message}"
+      end
+
+      def find_template_path(name)
+        base = name.to_s.sub(/\.json\z/, "")
+        gem_root = File.expand_path("../../..", __dir__)
+        candidates = [
+          File.join(Dir.pwd, "mocks", "#{base}.json"),
+          File.join(Dir.pwd, "mockTemplates", "#{base}.json"),
+          File.join(gem_root, "mocks", "#{base}.json"),
+          File.join(gem_root, "mockTemplates", "#{base}.json")
+        ]
+        candidates.find { |p| File.file?(p) }
+      end
+
+      def split_patterns(value)
+        list = value.to_s.split(",").map(&:strip).reject(&:empty?)
+        raise FlycalCli::Error, "mockEventDescriptionPatterns must list at least one pattern." if list.empty?
+
+        list
+      end
+
+      def parse_date(value, end_of_day:)
+        raise FlycalCli::Error, "Missing mock date." if value.to_s.empty?
+
+        DateTimeParser.parse(value.to_s, end_of_day: end_of_day)
+      end
+
+      def parse_hour_minute(value)
+        str = value.to_s.strip
+        match = str.match(/\A(\d{1,2}):(\d{2})\z/)
+        raise FlycalCli::Error, "Invalid mock hour #{value.inspect}. Use HH:MM (e.g. 09:00)." unless match
+
+        hour = match[1].to_i
+        min = match[2].to_i
+        unless hour.between?(0, 23) && min.between?(0, 59)
+          raise FlycalCli::Error, "Invalid mock hour #{value.inspect}. Use HH:MM (e.g. 09:00)."
+        end
+
+        [hour, min]
+      end
+
+      def resolve_seed(value)
+        return Integer(value) unless value.nil? || value.to_s.empty?
+
+        Random.new_seed & 0xFFFFFFFF
+      end
+
+      def validate!
+        missing = []
+        missing << "mockEventDescriptionPatterns" if patterns.empty?
+        missing << "mockEventCount" if count <= 0
+        missing << "mockEventFrom" if range_from.nil?
+        missing << "mockEventTo" if range_to.nil?
+        missing << "mockEventDurationMin" if duration_min_seconds <= 0
+        missing << "mockEventDurationMax" if duration_max_seconds <= 0
+        raise FlycalCli::Error, "Missing mock parameters: #{missing.join(", ")}" unless missing.empty?
+
+        if duration_min_seconds > duration_max_seconds
+          raise FlycalCli::Error, "mockEventDurationMin must be <= mockEventDurationMax."
+        end
+        if range_from > range_to
+          raise FlycalCli::Error, "mockEventFrom must be before mockEventTo."
+        end
+
+        from_mins = hours_from[0] * 60 + hours_from[1]
+        to_mins = hours_to[0] * 60 + hours_to[1]
+        if from_mins >= to_mins
+          raise FlycalCli::Error, "mockEventHoursFrom must be before mockEventHoursTo."
+        end
+        if duration_min_seconds > (to_mins - from_mins) * 60
+          raise FlycalCli::Error,
+                "mockEventDurationMin does not fit in mockEventHoursFrom..mockEventHoursTo window."
+        end
+      end
+    end
+  end
+end

data/lib/flycal_cli/mock/event_generator.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module FlycalCli
+  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)
+
+      def initialize(config)
+        @config = config
+        @rng = Random.new(config.seed)
+      end
+
+      def generate
+        counters = Hash.new(0)
+        Array.new(@config.count) do
+          pattern = @config.patterns.sample(random: @rng)
+          counters[pattern] += 1
+          title = "#{pattern}#{counters[pattern]}"
+          start_at, end_at = random_range
+          Event.new(
+            summary: title,
+            description: title,
+            start: EventStart.new(date_time: start_at, date: nil),
+            end: EventEnd.new(date_time: end_at, date: nil)
+          )
+        end.sort_by { |e| e.start.date_time }
+      end
+
+      private
+
+      def random_range
+        day = random_day
+        duration = random_duration_seconds
+        start_at = random_start_on(day, duration)
+        [start_at, start_at + duration]
+      end
+
+      def random_day
+        from_date = @config.range_from.to_date
+        to_date = @config.range_to.to_date
+        span = (to_date - from_date).to_i
+        from_date + @rng.rand(0..span)
+      end
+
+      def random_duration_seconds
+        min = @config.duration_min_seconds
+        max = @config.duration_max_seconds
+        return min if min == max
+
+        @rng.rand(min..max)
+      end
+
+      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)
+        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."
+        end
+
+        span = (latest_start - window_start).to_i
+        window_start + @rng.rand(0..span)
+      end
+    end
+  end
+end

data/lib/flycal_cli/mock.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "flycal_cli/mock/config"
+require "flycal_cli/mock/event_generator"
+require "flycal_cli/mock/calendar_service"
+
+module FlycalCli
+  module Mock
+  end
+end