flycal-cli 0.7.7 → 1.1

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/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Flycal
+  # Kept for Zeitwerk (`lib/flycal/version.rb` → Flycal::Version).
+  # Canonical version string lives on Flycal::VERSION (see lib/flycal.rb).
+  module Version
+    def self.to_s
+      Flycal::VERSION
+    end
+  end
+end

data/lib/flycal.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Flycal core namespace.
+# 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.1"
+
+  def self.connect(credentials:)
+    Client.new(credentials: credentials)
+  end
+end

data/lib/flycal_cli.rb

@@ -1,20 +1,45 @@
 # frozen_string_literal: true
 
-require "flycal_cli/version"
-require "flycal_cli/config"
-require "flycal_cli/locale"
-require "flycal_cli/auth"
-require "flycal_cli/duration_parser"
-require "flycal_cli/date_time_parser"
-require "flycal_cli/clipboard"
-require "flycal_cli/description_query"
-require "flycal_cli/calendar_service"
-require "flycal_cli/slot_finder"
-require "flycal_cli/slot_formatter"
-require "flycal_cli/mock"
-require "flycal_cli/pipeline"
-require "flycal_cli/cli"
+# Gem entrypoint for the flycal-cli package.
+core_lib = File.expand_path("../../lib", __dir__)
+$LOAD_PATH.unshift(core_lib) unless $LOAD_PATH.include?(core_lib)
+cli_lib = File.expand_path(".", __dir__)
+$LOAD_PATH.unshift(cli_lib) unless $LOAD_PATH.include?(cli_lib)
 
-module FlycalCli
-  class Error < StandardError; end
-end
+# Eager-load Flycal core (outside Rails/Zeitwerk).
+require "flycal/version"
+require "flycal/error"
+require "flycal/locale"
+require "flycal/time_format"
+require "flycal/credentials"
+require "flycal/event_mapper"
+require "flycal/cache_key"
+require "flycal/cache_annotator"
+require "flycal/client"
+require "flycal/duration_parser"
+require "flycal/date_time_parser"
+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"
+require "flycal/pipeline/aggregator"
+require "flycal/pipeline/renderer"
+require "flycal/pipeline/text_renderer"
+require "flycal/pipeline/json_renderer"
+require "flycal/pipeline/search_pipeline"
+
+require "flycal/cli"
+
+FlycalCli = Flycal::Cli unless defined?(FlycalCli)

data/mcp/tools.json

@@ -461,7 +461,7 @@
     {
       "name": "flycal_slots",
       "title": "Find free time slots",
-      "description": "Find continuous free ranges using a slots.templates schedule (days + hours). Default template = first key (usually work). Busy events come from slots.exclude_calendars (or calendar_default if empty). Respects free_before/free_after. Prints header + availability; copies availability list to clipboard when a clipboard tool exists.",
+      "description": "Find continuous free ranges using a slots.templates schedule (days + hours). Default template = first key (usually work). Busy events come from slots.exclude_calendars (or calendar_default if empty). Respects free_before/free_after. Output: text (header + availability, clipboard) or JSON via --format json.",
       "interactive": false,
       "requires_auth": true,
       "command": {
@@ -473,14 +473,16 @@
           "in": ["--in", "{value}"],
           "template": ["--template", "{value}"],
           "calendar": ["--calendar", "{value}"],
-          "locale": ["--locale", "{value}"]
+          "locale": ["--locale", "{value}"],
+          "format": ["--format", "{value}"]
         },
         "examples": [
           ["flycal", "slots"],
           ["flycal", "slots", "--in", "5 days"],
           ["flycal", "slots", "--from", "monday", "--in", "5 days", "--locale", "it"],
           ["flycal", "slots", "--in", "12 days", "--template", "dinner"],
-          ["flycal", "slots", "--from", "next monday", "--duration", "1h", "--template", "work"]
+          ["flycal", "slots", "--from", "next monday", "--duration", "1h", "--template", "work"],
+          ["flycal", "slots", "--format", "json", "--in", "5 days"]
         ]
       },
       "parameters": {
@@ -532,15 +534,21 @@
           "enum": ["en", "it"],
           "required": false,
           "description": "Optional locale override."
+        },
+        "format": {
+          "cli": ["--format"],
+          "type": "string",
+          "enum": ["text", "json"],
+          "required": false,
+          "default": "text",
+          "description": "Output format: text (shell + clipboard) or json (params/info/items/groups)."
         }
       },
       "output": {
-        "format": "text/plain",
+        "format": "text/plain or application/json",
         "includes": [
-          "count + from/to + duration + template",
-          "bullet list of considered calendars",
-          "link: Google Calendar day URL at --from",
-          "availability ranges grouped by day (copied to clipboard without header)"
+          "text: count + from/to + duration + template, calendars, link, ranges by day (clipboard)",
+          "json: params, info (slots_found, calendars, link), flat items, groups by day"
         ],
         "example": "found 6 slots\nfrom sat 1 August 2026 to sat 8 August 2026\nwith duration 45min, template dinner\nconsidering calendars\n- Work\n- Personal\nlink: https://calendar.google.com/calendar/r/day/2026/8/1\n\nsaturday 1/8\n19 - 23"
       },
@@ -573,6 +581,11 @@
             "type": "string",
             "enum": ["en", "it"],
             "description": "--locale. Optional locale override (en, it)."
+          },
+          "format": {
+            "type": "string",
+            "enum": ["text", "json"],
+            "description": "--format. text (default) or json."
           }
         }
       }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flycal-cli
 version: !ruby/object:Gem::Version
-  version: 0.7.7
+  version: '1.1'
 platform: ruby
 authors:
 - flycal-cli
@@ -134,31 +134,47 @@ files:
 - README.md
 - bin/flycal
 - config/defaults.yml
+- lib/flycal.rb
+- lib/flycal/cache_annotator.rb
+- lib/flycal/cache_key.rb
+- lib/flycal/calendar_query.rb
+- lib/flycal/calendar_service.rb
+- lib/flycal/cli.rb
+- lib/flycal/cli/app.rb
+- lib/flycal/cli/auth.rb
+- lib/flycal/cli/clipboard.rb
+- lib/flycal/cli/config.rb
+- lib/flycal/cli/file_cache.rb
+- lib/flycal/cli/locale.rb
+- 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
+- lib/flycal/event_mapper.rb
+- lib/flycal/locale.rb
+- lib/flycal/mock.rb
+- 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
+- lib/flycal/pipeline/params.rb
+- lib/flycal/pipeline/renderer.rb
+- lib/flycal/pipeline/retriever.rb
+- lib/flycal/pipeline/search_pipeline.rb
+- 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
-- lib/flycal_cli/auth.rb
-- lib/flycal_cli/calendar_service.rb
-- lib/flycal_cli/cli.rb
-- lib/flycal_cli/clipboard.rb
-- lib/flycal_cli/config.rb
-- lib/flycal_cli/date_time_parser.rb
-- lib/flycal_cli/description_query.rb
-- lib/flycal_cli/duration_parser.rb
-- lib/flycal_cli/locale.rb
-- lib/flycal_cli/mock.rb
-- lib/flycal_cli/mock/calendar_service.rb
-- lib/flycal_cli/mock/config.rb
-- lib/flycal_cli/mock/event_generator.rb
-- lib/flycal_cli/pipeline.rb
-- lib/flycal_cli/pipeline/aggregator.rb
-- lib/flycal_cli/pipeline/json_renderer.rb
-- lib/flycal_cli/pipeline/params.rb
-- lib/flycal_cli/pipeline/renderer.rb
-- lib/flycal_cli/pipeline/retriever.rb
-- lib/flycal_cli/pipeline/search_pipeline.rb
-- lib/flycal_cli/pipeline/text_renderer.rb
-- lib/flycal_cli/slot_finder.rb
-- lib/flycal_cli/slot_formatter.rb
-- lib/flycal_cli/version.rb
 - locales/en.json
 - locales/it.json
 - mcp/README.md

data/lib/flycal_cli/mock.rb

@@ -1,10 +0,0 @@
-# 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

data/lib/flycal_cli/pipeline.rb

@@ -1,14 +0,0 @@
-# frozen_string_literal: true
-
-require "flycal_cli/pipeline/params"
-require "flycal_cli/pipeline/retriever"
-require "flycal_cli/pipeline/aggregator"
-require "flycal_cli/pipeline/renderer"
-require "flycal_cli/pipeline/text_renderer"
-require "flycal_cli/pipeline/json_renderer"
-require "flycal_cli/pipeline/search_pipeline"
-
-module FlycalCli
-  module Pipeline
-  end
-end

data/lib/flycal_cli/slot_formatter.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-module FlycalCli
-  class SlotFormatter
-    class << self
-      def format_header(from:, to:, duration:, calendars:, count:, template: nil)
-        lines = []
-        lines << Locale.t(
-          "slots.header",
-          count: underline(count),
-          from: underline(Locale.format_long_date(from)),
-          to: underline(Locale.format_long_date(to)),
-          duration: underline(duration),
-          template: underline(template.to_s)
-        )
-        calendars.each do |cal|
-          lines << "- #{cal[:name]}"
-        end
-        lines << "link: #{google_calendar_day_url(from)}"
-        lines.join("\n")
-      end
-
-      def format_output(slots_by_day)
-        lines = []
-
-        slots_by_day.sort_by(&:first).each do |date, slots|
-          lines << "" unless lines.empty?
-          lines << underline(day_header(date))
-          slots.each do |start_at, end_at|
-            lines << slot_range(start_at, end_at)
-          end
-        end
-
-        lines.join("\n")
-      end
-
-      def strip_ansi(text)
-        text.to_s.gsub(/\e\[[0-9;]*m/, "")
-      end
-
-      private
-
-      def underline(str)
-        "\e[4m#{str}\e[0m"
-      end
-
-      def google_calendar_day_url(from)
-        t = from.respond_to?(:to_time) ? from.to_time : from
-        "https://calendar.google.com/calendar/r/day/#{t.year}/#{t.month}/#{t.day}"
-      end
-
-      def day_header(date)
-        "#{Locale.day_name(date)} #{date.day}/#{date.month}"
-      end
-
-      def slot_range(start_at, end_at)
-        "#{format_time(start_at)} - #{format_time(end_at)}"
-      end
-
-      def format_time(time)
-        return time.strftime("%-H") if time.min.zero?
-
-        minutes = sprintf("%02d", time.min)
-        "#{time.hour}.#{minutes}"
-      end
-    end
-  end
-end

data/lib/flycal_cli/version.rb

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-
-module FlycalCli
-  VERSION = '0.7.7'
-end