flycal-cli 0.7.7 → 1.0

data/lib/{flycal_cli/cli.rb → flycal/cli/app.rb}

@@ -9,8 +9,9 @@ require "active_support/core_ext/time"
 require "tty-prompt"
 require "tty-spinner"
 
-module FlycalCli
-  class Cli < Thor
+module Flycal
+module Cli
+  class App < 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",
@@ -44,7 +45,7 @@ module FlycalCli
         Auth.login
         puts "\n✓ Authentication completed successfully!"
         puts "\nRun 'flycal config' to set the default calendar."
-      rescue FlycalCli::Error => e
+      rescue Flycal::Error => e
         puts "Error: #{e.message}"
         exit 1
       end
@@ -137,16 +138,20 @@ module FlycalCli
         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
+        flycal search --groupBy "rui|solver" --format json
+        flycal search -c "Work|Personal"
+        flycal search --calendar Work --calendar Personal
     LONGDESC
-    option :calendar, type: :string, aliases: "-c", desc: "Calendar name or ID"
+    option :calendar, type: :string, aliases: "-c", repeatable: true,
+           desc: "Calendar name or ID (repeatable, or pipe-separated: Work|Personal)"
+
     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 text in event (OR with |, e.g. rui|solver)"
     option :groupBy, type: :string,
-           desc: "Grouping: day, week, month, or description (default: auto from timeframe)"
+           desc: "Grouping: day, week, month, or a string like rui|solver (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"
@@ -158,6 +163,8 @@ module FlycalCli
     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)"
+    option :nocache, type: :boolean, default: false,
+           desc: "Bypass cache and refresh from Google"
     def search
       apply_locale_override
 
@@ -166,7 +173,7 @@ module FlycalCli
       if mock_mode
         begin
           mock_config = Mock::Config.from_options(options)
-        rescue FlycalCli::Error => e
+        rescue Flycal::Error => e
           puts "Error: #{e.message}"
           exit 1
         end
@@ -182,7 +189,7 @@ module FlycalCli
                    else
                      DurationParser.add_to_time(options[:in], time_min)
                    end
-      rescue FlycalCli::Error => e
+      rescue Flycal::Error => e
         puts "Error: #{e.message}"
         exit 1
       end
@@ -196,7 +203,7 @@ module FlycalCli
         if mock_config
           Mock::CalendarService.new(mock_config)
         else
-          CalendarService.new(Auth.credentials)
+          flycal_client.calendar
         end
 
       calendar_ids =
@@ -229,10 +236,49 @@ module FlycalCli
         mock_template: mock_config&.template_name
       )
 
+      fingerprint = {
+        command: "search",
+        time_min: time_min,
+        time_max: time_max,
+        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
+      }
+      cache_key = Flycal::CacheKey.generate("search", fingerprint)
+      ttl = Flycal::CacheKey::DEFAULT_TTL_MINUTES
+      nocache = options[:nocache]
+
       begin
-        output = Pipeline::SearchPipeline.new(service).run(params)
-        print output
-      rescue FlycalCli::Error => e
+        output = nil
+        status = nil
+
+        unless nocache
+          cached = FileCache.read(cache_key, ttl_minutes: ttl)
+          if cached
+            output = cached
+            status = "HIT"
+          end
+        end
+
+        if output.nil?
+          FileCache.delete(cache_key) if nocache
+          output = Pipeline::SearchPipeline.new(service).run(params)
+          FileCache.write(cache_key, strip_cache_marker_from_output(output, params[:format]))
+          status = "MISS"
+        end
+
+        print annotate_cli_output(output, status, cache_key, params[:format])
+      rescue Flycal::Error => e
         puts "Error: #{e.message}"
         exit 1
       end
@@ -262,7 +308,11 @@ module FlycalCli
            desc: "Start (default: now). Dates, or relative: monday, next monday, tomorrow, lunedi..."
     option :template, type: :string, aliases: "-T",
            desc: "Slot template name from config (default: first template, usually work)"
-    option :calendar, type: :string, aliases: "-c", desc: "Calendar name or ID"
+    option :calendar, type: :string, aliases: "-c", repeatable: true,
+           desc: "Calendar name or ID (repeatable, or pipe-separated: Work|Personal)"
+    option :nocache, type: :boolean, default: false,
+           desc: "Bypass cache and refresh from Google"
+
     def slots
       apply_locale_override
       unless Auth.logged_in?
@@ -292,7 +342,7 @@ module FlycalCli
         time_max = DurationParser.add_to_time(in_value, time_min)
         hours = parse_workhours(template["hours"])
         days = parse_template_days(template["days"])
-      rescue FlycalCli::Error => e
+      rescue Flycal::Error => e
         puts "Error: #{e.message}"
         exit 1
       end
@@ -302,8 +352,8 @@ module FlycalCli
         exit 1
       end
 
-      creds = Auth.credentials
-      service = CalendarService.new(creds)
+      client = flycal_client
+      service = client.calendar
 
       exclude_calendar_ids = resolve_slots_exclude_calendar_ids(service, slot_cfg, options[:calendar])
       if exclude_calendar_ids.empty?
@@ -311,53 +361,118 @@ module FlycalCli
         exit 1
       end
 
-      calendars = service.list_calendars
-      calendar_meta = exclude_calendar_ids.filter_map do |id|
-        cal = calendars.find { |c| c.id == id }
-        name = cal&.summary || id
-        { id: id, name: name }
-      end
-
-      fetch_from = time_min - free_before
-      events = exclude_calendar_ids.flat_map do |calendar_id|
-        service.list_events(
-          calendar_id,
-          time_min: fetch_from,
-          time_max: time_max
-        )
-      rescue Google::Apis::Errors::Error => e
-        warn Locale.t("errors.calendar_fetch", calendar: calendar_id, message: e.message)
-        []
+      format = (options[:format] || "text").to_s.strip.downcase
+      format = "text" if format.empty?
+
+      unless %w[json text].include?(format)
+        puts "Error: Unsupported format #{format.inspect}. Available: text, json"
+        exit 1
       end
 
-      finder = SlotFinder.new(
-        events: events,
-        time_min: time_min,
-        time_max: time_max,
-        slot_duration_seconds: slot_duration,
+      fingerprint = {
+        command: "slots",
+        calendar_ids: exclude_calendar_ids,
+        duration: duration_value,
+        from: from_value,
+        in: in_value,
+        free_before: slot_cfg["free_before"] || "0m",
+        free_after: slot_cfg["free_after"] || "0m",
+        template: template_name,
+        locale: Locale.current_locale,
+        calendar: options[:calendar],
         hours: hours,
         days: days,
-        free_before_seconds: free_before,
-        free_after_seconds: free_after
-      )
+        time_min: time_min,
+        time_max: time_max,
+        format: format
+      }
+      cache_key = Flycal::CacheKey.generate("slots", fingerprint)
+      ttl = Flycal::CacheKey::DEFAULT_TTL_MINUTES
+      nocache = options[:nocache]
+
+      output = nil
+      status = nil
+      unless nocache
+        cached = FileCache.read(cache_key, ttl_minutes: ttl)
+        if cached
+          output = cached
+          status = "HIT"
+        end
+      end
 
-      slots_by_day = finder.slots_by_day
-      slot_count = slots_by_day.values.sum(&:size)
-      puts SlotFormatter.format_header(
-        from: time_min,
-        to: time_max,
-        duration: duration_value,
-        calendars: calendar_meta,
-        count: slot_count,
-        template: template_name
-      )
-      puts ""
-      output = SlotFormatter.format_output(slots_by_day)
-      if output.empty?
-        puts Locale.t("slots.no_available")
-      else
-        puts output
-        copy_slots_to_clipboard(output)
+      if output.nil?
+        FileCache.delete(cache_key) if nocache
+
+        calendars = client.list_calendars
+        calendar_meta = exclude_calendar_ids.filter_map do |id|
+          cal = calendars.find { |c| c.id == id }
+          name = cal&.summary || id
+          { id: id, name: name }
+        end
+
+        fetch_from = time_min - free_before
+        events = exclude_calendar_ids.flat_map do |calendar_id|
+          client.list_events(
+            calendar_id,
+            time_min: fetch_from,
+            time_max: time_max
+          )
+        rescue Google::Apis::Error => e
+          warn Locale.t("errors.calendar_fetch", calendar: calendar_id, message: e.message)
+          []
+        end
+
+        finder = SlotFinder.new(
+          events: events,
+          time_min: time_min,
+          time_max: time_max,
+          slot_duration_seconds: slot_duration,
+          hours: hours,
+          days: days,
+          free_before_seconds: free_before,
+          free_after_seconds: free_after
+        )
+
+        slots_by_day = finder.slots_by_day
+
+        output =
+          if format == "json"
+            SlotFormatter.format_json(
+              slots_by_day: slots_by_day,
+              time_min: time_min,
+              time_max: time_max,
+              duration: duration_value,
+              template: template_name,
+              calendars: calendar_meta,
+              locale: Locale.current_locale,
+              calendar_option: options[:calendar],
+              from_option: options[:from],
+              in_option: options[:in],
+              free_before: slot_cfg["free_before"],
+              free_after: slot_cfg["free_after"],
+              empty_message: Locale.t("slots.no_available")
+            )
+          else
+            SlotFormatter.format_text(
+              slots_by_day: slots_by_day,
+              time_min: time_min,
+              time_max: time_max,
+              duration: duration_value,
+              calendars: calendar_meta,
+              template: template_name,
+              empty_message: Locale.t("slots.no_available")
+            )
+          end
+
+        FileCache.write(cache_key, strip_cache_marker_from_output(output, format))
+        status = "MISS"
+      end
+
+      print annotate_cli_output(output, status, cache_key, format)
+
+      if format == "text"
+        body = extract_slots_body_for_clipboard(output)
+        copy_slots_to_clipboard(body) unless body.empty?
       end
     end
 
@@ -375,7 +490,7 @@ module FlycalCli
     desc "version", "Show current flycal-cli version"
     def version
       apply_locale_override
-      puts "flycal #{FlycalCli::VERSION}"
+      puts "flycal #{Flycal::VERSION}"
     end
 
     default_task :help
@@ -394,6 +509,38 @@ module FlycalCli
       Locale.override!(options[:locale])
     end
 
+    def annotate_cli_output(output, status, cache_key, format)
+      fmt = format.to_s.strip.downcase
+      if fmt == "json"
+        payload = JSON.parse(output)
+        Flycal::CacheAnnotator.annotate_payload!(payload, status, cache_key)
+        JSON.pretty_generate(payload) + "\n"
+      else
+        Flycal::CacheAnnotator.annotate_text(output, status, cache_key)
+      end
+    end
+
+    def strip_cache_marker_from_output(output, format)
+      fmt = format.to_s.strip.downcase
+      if fmt == "json"
+        payload = JSON.parse(output)
+        JSON.pretty_generate(Flycal::CacheAnnotator.strip_for_storage(payload)) + "\n"
+      else
+        lines = output.to_s.sub(/\n\z/, "").split("\n")
+        lines.reject! { |l| l.start_with?("Cache:") }
+        "#{lines.join("\n")}\n"
+      end
+    end
+
+    def extract_slots_body_for_clipboard(text)
+      lines = text.to_s.split("\n")
+      lines.reject! { |l| l.start_with?("Cache:") }
+      blank_idx = lines.index { |l| l == "" }
+      return "" unless blank_idx
+
+      lines[(blank_idx + 1)..].join("\n").strip
+    end
+
     def with_config_interrupt_handling
       yield
     rescue Interrupt
@@ -402,12 +549,11 @@ module FlycalCli
     end
 
     def load_calendars
-      creds = Auth.credentials
-      service = CalendarService.new(creds)
+      client = flycal_client
 
       spinner = TTY::Spinner.new("#{Locale.t('common.loading_calendars')} ", format: :dots)
       spinner.auto_spin
-      calendars = service.list_calendars
+      calendars = client.list_calendars
       spinner.stop("✓")
 
       if calendars.empty?
@@ -418,6 +564,13 @@ module FlycalCli
       calendars
     end
 
+    def flycal_client
+      creds = Auth.credentials
+      raise Flycal::Error, Locale.t("errors.not_connected") if creds.nil?
+
+      Flycal.connect(credentials: creds)
+    end
+
     def calendar_choices(calendars, highlight_ids: [])
       highlights = Array(highlight_ids).compact
       calendars.to_h do |cal|
@@ -491,24 +644,11 @@ module FlycalCli
     end
 
     def resolve_calendar_refs(calendars, refs)
-      Array(refs).filter_map do |ref|
-        resolve_calendar_ref(calendars, ref)
-      end.uniq
+      Flycal::CalendarQuery.resolve_ids(calendars, refs)
     end
 
     def resolve_calendar_ref(calendars, ref)
-      ref = ref.to_s.strip
-      return nil if ref.empty?
-
-      exact = calendars.find { |cal| cal.id == ref }
-      return exact.id if exact
-
-      matches = calendars.select do |cal|
-        cal.id == ref ||
-          (cal.summary && cal.summary.downcase.include?(ref.downcase))
-      end
-
-      matches.first&.id
+      Flycal::CalendarQuery.resolve_ref(calendars, ref)
     end
 
     def resolve_slots_exclude_calendar_ids(service, slot_cfg, calendar_override)
@@ -516,21 +656,27 @@ module FlycalCli
       calendars = service.list_calendars
 
       refs = if configured.nil? || (configured.is_a?(Array) && configured.empty?)
-               fallback = calendar_override || Config.calendar_default
-               fallback ? [fallback] : []
+               override_refs = Flycal::CalendarQuery.refs(calendar_override)
+               if override_refs.any?
+                 override_refs
+               else
+                 fallback = Config.calendar_default
+                 fallback ? [ fallback ] : []
+               end
              else
                configured
              end
 
-      ids = resolve_calendar_refs(calendars, refs)
+      ids = Flycal::CalendarQuery.resolve_ids(calendars, refs)
       return ids unless ids.empty?
 
-      fallback = calendar_override || Config.calendar_default
-      if fallback
-        resolve_calendar_refs(calendars, [fallback])
+      fallback_refs = Flycal::CalendarQuery.refs(calendar_override)
+      fallback_refs = [ Config.calendar_default ].compact if fallback_refs.empty?
+      if fallback_refs.any?
+        Flycal::CalendarQuery.resolve_ids(calendars, fallback_refs)
       else
         primary = calendars.find(&:primary)
-        primary ? [primary.id] : calendars.first(1).map(&:id)
+        primary ? [ primary.id ] : calendars.first(1).map(&:id)
       end
     end
 
@@ -542,7 +688,7 @@ module FlycalCli
 
     def resolve_slots_template(slot_cfg, requested_name)
       templates = slot_cfg["templates"]
-      raise FlycalCli::Error, "slots.templates is missing in config.yml." unless templates.is_a?(Hash) && !templates.empty?
+      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?
@@ -550,7 +696,7 @@ module FlycalCli
       template = templates[name]
       unless template.is_a?(Hash)
         available = templates.keys.join(", ")
-        raise FlycalCli::Error, "Unknown slots template #{name.inspect}. Available: #{available}"
+        raise Flycal::Error, "Unknown slots template #{name.inspect}. Available: #{available}"
       end
 
       [name, template]
@@ -558,10 +704,10 @@ module FlycalCli
 
     def parse_template_days(values)
       days = Array(values).map(&:to_i)
-      raise FlycalCli::Error, "slots template days cannot be empty." if days.empty?
+      raise Flycal::Error, "slots template days cannot be empty." if days.empty?
 
       invalid = days.reject { |d| d.between?(1, 7) }
-      raise FlycalCli::Error, "Invalid template days #{invalid.inspect}. Use 1 (Mon) .. 7 (Sun)." unless invalid.empty?
+      raise Flycal::Error, "Invalid template days #{invalid.inspect}. Use 1 (Mon) .. 7 (Sun)." unless invalid.empty?
 
       days.uniq
     end
@@ -576,12 +722,12 @@ module FlycalCli
 
     def parse_hour_minute(value)
       match = value.to_s.strip.match(/\A(\d{1,2}):(\d{2})\z/)
-      raise FlycalCli::Error, "Invalid time format #{value.inspect}. Use HH:MM (e.g. 9:00, 18:30)." unless match
+      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 FlycalCli::Error, "Invalid time #{value.inspect}. Hour must be 0-23 and minute 0-59."
+        raise Flycal::Error, "Invalid time #{value.inspect}. Hour must be 0-23 and minute 0-59."
       end
 
       [hour, minute]
@@ -590,18 +736,18 @@ module FlycalCli
     def parse_workhours(values)
       ranges = Array(values).map do |item|
         start_str, end_str = item.to_s.strip.split("-", 2)
-        raise FlycalCli::Error, "Invalid hours item #{item.inspect}. Use format like '9-13' or '14:30-18:00'." if start_str.nil? || end_str.nil?
+        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 FlycalCli::Error, "Invalid hours range #{item.inspect}: end must be after start." if end_minutes <= start_minutes
+        raise Flycal::Error, "Invalid hours range #{item.inspect}: end must be after start." if end_minutes <= start_minutes
 
         [sh, sm, eh, em]
       end
 
-      raise FlycalCli::Error, "template hours cannot be empty in config.yml." if ranges.empty?
+      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
@@ -610,7 +756,7 @@ module FlycalCli
       str = value.to_s.strip
       if str.match?(/\A\d{1,2}\z/)
         hour = str.to_i
-        raise FlycalCli::Error, "Invalid hour #{value.inspect}. Must be 0-23." unless hour.between?(0, 23)
+        raise Flycal::Error, "Invalid hour #{value.inspect}. Must be 0-23." unless hour.between?(0, 23)
 
         return [hour, 0]
       end
@@ -618,29 +764,27 @@ module FlycalCli
       parse_hour_minute(str)
     end
 
-    def resolve_calendar_ids(service, calendar_name)
+    def resolve_calendar_ids(service, calendar_option)
       calendar_lists = service.list_calendars
+      refs = Flycal::CalendarQuery.refs(calendar_option)
 
-      if calendar_name.nil? || calendar_name.empty?
+      if refs.empty?
         default_id = Config.calendar_default
-        if default_id
-          return [default_id]
-        end
-        # Use primary calendar if available
+        return [ default_id ] if default_id
+
         primary = calendar_lists.find(&:primary)
-        return [primary.id] if primary
-        # Otherwise first calendar
-        return [calendar_lists.first.id] if calendar_lists.any?
+        return [ primary.id ] if primary
+        return [ calendar_lists.first.id ] if calendar_lists.any?
+
         return []
       end
 
-      # Search by name or ID
-      matches = calendar_lists.select do |cal|
-        cal.id == calendar_name ||
-          (cal.summary && cal.summary.downcase.include?(calendar_name.downcase))
-      end
+      ids = Flycal::CalendarQuery.resolve_ids(calendar_lists, refs)
+      return ids unless ids.empty?
 
-      matches.map(&:id)
+      # Fall back to treating unresolved refs as literal calendar IDs
+      refs
     end
   end
 end
+end

data/lib/{flycal_cli → flycal/cli}/auth.rb

@@ -5,7 +5,8 @@ require "googleauth"
 require "googleauth/stores/file_token_store"
 require "fileutils"
 
-module FlycalCli
+module Flycal
+module Cli
   class Auth
     SCOPE = "https://www.googleapis.com/auth/calendar.readonly"
     REDIRECT_PORT = 9292
@@ -42,7 +43,7 @@ module FlycalCli
 
       def login
         unless Config.credentials_exist?
-          raise FlycalCli::Error,
+          raise Flycal::Error,
                 "Credentials file not found. Create #{Config.credentials_path} with OAuth credentials from Google Cloud Console.\n" \
                 "Go to: https://console.cloud.google.com/apis/credentials\n" \
                 "Create 'Desktop app' credentials and download the JSON as credentials.json"
@@ -65,7 +66,7 @@ module FlycalCli
 
         # Start local server to receive the auth code
         code = start_redirect_server(authorizer)
-        raise FlycalCli::Error, "Authentication cancelled or failed" if code.nil? || code.empty?
+        raise Flycal::Error, "Authentication cancelled or failed" if code.nil? || code.empty?
 
         authorizer.get_and_store_credentials_from_code(
           user_id: "flycal_user",
@@ -130,3 +131,4 @@ module FlycalCli
     end
   end
 end
+end

data/lib/{flycal_cli → flycal/cli}/clipboard.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-module FlycalCli
+module Flycal
+module Cli
   # Cross-platform clipboard helper.
   # Prefers: pbcopy (macOS) → wl-copy (Wayland) → xclip (X11) → clip (Windows).
   module Clipboard
@@ -52,3 +53,4 @@ module FlycalCli
     end
   end
 end
+end

data/lib/{flycal_cli → flycal/cli}/config.rb

@@ -3,13 +3,14 @@
 require "yaml"
 require "fileutils"
 
-module FlycalCli
+module Flycal
+module Cli
   class Config
     CONFIG_DIR = File.expand_path("~/.flycal")
     CONFIG_FILE = File.join(CONFIG_DIR, "config.yml")
     CREDENTIALS_FILE = File.join(CONFIG_DIR, "credentials.json")
     TOKENS_FILE = File.join(CONFIG_DIR, "tokens.yml")
-    DEFAULTS_FILE = File.expand_path("../../config/defaults.yml", __dir__)
+    DEFAULTS_FILE = File.expand_path("../../../config/defaults.yml", __dir__)
 
     class << self
       def load
@@ -195,3 +196,4 @@ module FlycalCli
     end
   end
 end
+end