flycal-cli 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 980bab82020402b0031c0fc3d84a240626a8a26145cc8a86973390777b21db12
-  data.tar.gz: b26c8bc3fec6e7f68a291d4e6124fc41680c15e5204a1217d6331d5c097cdf91
+  metadata.gz: b7333fcbb8ba227c7694b96cba4b35893e324c13e38bdc6d996e69f54cc3d64a
+  data.tar.gz: aab159e8f8e68368db1e45d1a799dd93386f79a0f2f9c29bb92aba776bcefa21
 SHA512:
-  metadata.gz: bce52224114636c4a330ebcdd6740409add46791789544e42cd04380d080056d5b9dddabe8ad0a4a395448958c23631702c05864b3617d3e4ee9fe9eda616b3b
-  data.tar.gz: fa998fbf3213fabd004a58e4d709fd05f28eee1951b9efef4c7c9ccc17fcf903af73d8e9cf7e0345569b774c8369f6422cdf4f018cd7ca1dc92e5126f0730aa8
+  metadata.gz: 2036031048ebcb74e1954ff1d574051945407bdef922f161f4b1ad7e8be7cd1f3dfdec6dea2efe671502a1310ba834cee44426d837a3b7dfee4fb76fbd504117
+  data.tar.gz: 40646b4ce7bfaa3256a35c435cdf6dcb3913aaf2a3811370219e32c510fc88d7469d652b573973016d96b9e1d5f49cca8da159bfad7d787742dc8c0bba9239d0

data/README.md

@@ -128,8 +128,8 @@ flycal search -i 2months -d placeholder
 
 **Options:**
 
-- `--from` / `-f` — Start date/time. Default: midnight of current day. Format: `2025-01-01` or `2025-01-01T09:00`
-- `--to` / `-t` — End date/time. Default: 23:59 of the 30th day from today. Format: same as `--from`
+- `--from` / `-f` — Start date/time. Default: midnight of current day. Formats: `YYYY-MM-DD`, locale forms (`DD-MM-YYYY` for `it`, `MM-DD-YYYY` for `en`, `/` or `-`), or with time `YYYY-MM-DDTHH:MM`
+- `--to` / `-t` — End date/time. Default: 23:59 of the 30th day from today. Same formats as `--from`
 - `--in` / `-i` — Duration from `--from`, overrides `--to`. Format: `30days`, `48hours`, `2months`, `1year` (no space). With space use quotes: `--in "30 days"`
 - `--calendar` / `-c` — Calendar name or ID. Default: calendar set via `flycal config`
 - `--description` / `-d` — Filter events by text. Matches events where the string appears in title or description (case-insensitive, contains)
@@ -153,28 +153,56 @@ For time frames longer than 7 days, a weekly breakdown is added (week number, st
 
 ### slots
 
-Find free time slots in your calendar (weekdays, 9:00–18:00). Output is a simple list for copy/paste into email or other tools.
+Find free time slots in your calendar. Output is a simple list for copy/paste into email or other tools.
 
 ```bash
-flycal slots --in "3 days" --duration 1h
-flycal slots --in 1week --duration 30min
-flycal slots --in "48 hours" --duration 1hour -c Work
+flycal slots
+flycal slots --duration 1h
+flycal slots --from 2026-08-01 --in "2 weeks" --duration 1h
+flycal slots --from 01/08/2026 --in 3days --duration 30min
+flycal slots --in 1week -c Work
 ```
 
 **Options:**
 
-- `--duration` — Minimum slot length. Examples: `1h`, `1 hour`, `30 minutes`, `90min`
-- `--in` / `-i` — Search window from now. Examples: `3 days`, `1 week`, `48 hours` (use quotes when the value contains a space)
+- `--duration` — Slot length. Default: `slots.defaults.default_duration` in config (`45min`). Examples: `1h`, `30 minutes`
+- `--from` / `-f` — Start date/time. Default: `slots.defaults.from` in config (`now`). If a date without time is today, starts from the current time.
+- `--in` / `-i` — Search window from `--from`. Default: `1 week`.
 - `--calendar` / `-c` — Calendar name or ID used as fallback when `exclude_calendars` is not configured
 
+**Output:**
+
+Always starts with a header and clickable calendar links (OSC 8), then the availability list:
+
+```
+found 3 slots
+from wed 29 July 2026 to wed 5 August 2026
+with duration 45min
+for calendars
+Incode - Antonio
+Personal
+https://calendar.google.com/calendar/r/day/2026/7/29
+
+friday 15/7
+10-12
+13-15.30
+```
+
+If `pbcopy` is available (macOS), the slot list without the header is also copied to the clipboard.
+
 Slot search windows are configured in `~/.flycal/config.yml`:
 
 ```yaml
 slots:
+  defaults:
+    from: now
+    default_duration: 45min
+  free_before: 0m
+  free_after: 15m
   exclude_calendars:
     - user@example.com
     - user@gmail.com
-  workhours:
+  hours:
     - 9:30-13:00
     - 14:00-18:30
   weekdays_only: true
@@ -183,8 +211,12 @@ locale: en
 
 Missing keys are filled from `config/defaults.yml` in the gem and saved to your `config.yml` on first read.
 
+- `defaults.from` — default `--from` for slots (`now` or a date string)
+- `defaults.default_duration` — default slot length when `--duration` is omitted
+- `free_before` — buffer before each slot; busy intervals are extended backward so no event may fall in this window before a slot
+- `free_after` — buffer after each slot; gaps must fit `duration + free_after`, but output shows slots of `duration` only
 - `exclude_calendars` lists calendars whose events block free slots; if empty or not set, events from `calendar_default` are used
-- `workhours` accepts one or more ranges (`H-H`, `HH:MM-HH:MM`, mixed)
+- `hours` accepts one or more ranges (`H-H`, `HH:MM-HH:MM`, mixed)
 - `weekdays_only: true` limits slots to Monday-Friday
 - `weekdays_only: false` includes weekends
 - `locale` supports `en` and `it` (default is `en`)

data/config/defaults.yml

@@ -1,7 +1,12 @@
 locale: en
 slots:
+  defaults:
+    from: now
+    default_duration: 45min
+  free_before: 0m
+  free_after: 15m
   exclude_calendars: []
-  workhours:
+  hours:
     - 9:30-13:00
     - 14:00-18:30
   weekdays_only: true

data/lib/flycal_cli/cli.rb

@@ -137,12 +137,12 @@ module FlycalCli
         exit 1
       end
 
-      time_min = options[:from].to_s.empty? ? Date.today.to_time : parse_datetime(options[:from])
+      time_min = options[:from].to_s.empty? ? Date.today.to_time : DateTimeParser.parse(options[:from])
       begin
         time_max = if options[:in].to_s.empty?
-                     options[:to].to_s.empty? ? (Date.today + 30).to_time + 86400 - 1 : parse_datetime(options[:to], end_of_day: true)
+                     options[:to].to_s.empty? ? (Date.today + 30).to_time + 86400 - 1 : DateTimeParser.parse(options[:to], end_of_day: true)
                    else
-                     parse_duration_in(options[:in], time_min)
+                     DurationParser.add_to_time(options[:in], time_min)
                    end
       rescue FlycalCli::Error => e
         puts "Error: #{e.message}"
@@ -178,14 +178,22 @@ module FlycalCli
     long_desc <<-LONGDESC
       List free time slots long enough for a given duration.
 
+      Defaults:
+        --from      from config (default: now)
+        --in        1 week
+        --duration  from config (default: 45min)
+
       Examples:
-        flycal slots --in "3 days" --duration 1h
-        flycal slots --in 1week --duration 30min -c Work
+        flycal slots
+        flycal slots --duration 1h
+        flycal slots --from 2026-08-01 --in "2 weeks" --duration 1h
     LONGDESC
-    option :duration, type: :string, required: true,
-           desc: "Minimum slot length (e.g. 1h, 30 minutes, 1 hour)"
-    option :in, type: :string, aliases: "-i", required: true,
-           desc: "Search window from now (e.g. 3 days, 1 week, 48 hours)"
+    option :duration, type: :string,
+           desc: "Slot length (default from config: slots.defaults.default_duration)"
+    option :in, type: :string, aliases: "-i", default: "1 week",
+           desc: "Search window from --from (default: 1 week)"
+    option :from, type: :string, aliases: "-f",
+           desc: "Start date/time (default from config: slots.defaults.from)"
     option :calendar, type: :string, aliases: "-c", desc: "Calendar name or ID"
     def slots
       apply_locale_override
@@ -194,12 +202,26 @@ module FlycalCli
         exit 1
       end
 
+      slot_cfg = Config.slots_config
+      defaults = slot_cfg.fetch("defaults", {})
+      in_value = options[:in].to_s.strip
+      in_value = "1 week" if in_value.empty?
+
+      duration_value = options[:duration].to_s.strip
+      duration_value = defaults["default_duration"].to_s.strip if duration_value.empty?
+      duration_value = "45min" if duration_value.empty?
+
+      from_value = options[:from].to_s.strip
+      from_value = defaults["from"].to_s.strip if from_value.empty?
+      from_value = "now" if from_value.empty?
+
       begin
-        slot_duration = DurationParser.to_seconds(options[:duration])
-        time_min = Time.now
-        time_max = DurationParser.add_to_time(options[:in], time_min)
-        slot_cfg = Config.slots_config
-        workhours = parse_workhours(slot_cfg["workhours"])
+        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)
+        workhours = parse_workhours(slot_cfg["hours"])
         weekdays_only = !!slot_cfg["weekdays_only"]
       rescue FlycalCli::Error => e
         puts "Error: #{e.message}"
@@ -220,10 +242,18 @@ 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: time_min,
+          time_min: fetch_from,
           time_max: time_max
         )
       rescue Google::Apis::Errors::Error => e
@@ -237,11 +267,28 @@ module FlycalCli
         time_max: time_max,
         slot_duration_seconds: slot_duration,
         workhours: workhours,
-        weekdays_only: weekdays_only
+        weekdays_only: weekdays_only,
+        free_before_seconds: free_before,
+        free_after_seconds: free_after
       )
 
-      output = SlotFormatter.format_output(finder.slots_by_day)
-      puts output.empty? ? Locale.t("slots.no_available") : output
+      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
+      )
+      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)
+      end
     end
 
     desc "update", "Update flycal-cli to the latest gem version"
@@ -419,38 +466,24 @@ module FlycalCli
       end
     end
 
-    def parse_datetime(str, end_of_day: false)
-      return nil if str.nil? || str.empty?
+    def parse_slots_from(value)
+      return Time.now if value.to_s.strip.downcase == "now"
 
-      if str.include?("T")
-        Time.parse(str)
-      else
-        d = Date.parse(str)
-        t = d.to_time
-        end_of_day ? t + 86400 - 1 : t  # 23:59:59 for --to when date-only
-      end
+      DateTimeParser.parse(value)
     end
 
-    def parse_duration_in(str, from_time)
-      # Support both "30days" and "30 days" (no space avoids shell splitting)
-      m = str.to_s.strip.match(/\A(\d+)\s*(day|days|d|hour|hours|h|month|months|m|year|years|y)\z/i)
-      raise FlycalCli::Error, "Invalid --in format. Use: 30days, 48hours, 2months, 1year (no space, or quote: --in \"30 days\")" unless m
+    def copy_slots_to_clipboard(text)
+      return unless pbcopy_available?
 
-      n = m[1].to_i
-      unit = m[2].downcase
+      IO.popen("pbcopy", "w") { |io| io.write(text) }
+      puts ""
+      puts Locale.t("slots.copied_to_clipboard")
+    rescue StandardError
+      nil
+    end
 
-      case unit
-      when "hour", "hours", "h"
-        from_time + n * 3600
-      when "day", "days", "d"
-        from_time + n * 86400
-      when "month", "months", "m"
-        (from_time.to_date >> n).to_time + (from_time.hour * 3600 + from_time.min * 60 + from_time.sec)
-      when "year", "years", "y"
-        (from_time.to_date >> (n * 12)).to_time + (from_time.hour * 3600 + from_time.min * 60 + from_time.sec)
-      else
-        raise FlycalCli::Error, "Invalid unit: #{unit}. Use: days, hours, months, years"
-      end
+    def pbcopy_available?
+      system("which", "pbcopy", out: File::NULL, err: File::NULL)
     end
 
     def parse_hour_minute(value)
@@ -469,18 +502,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 workhours item #{item.inspect}. Use format like '9-13' or '14:30-18:00'." if start_str.nil? || end_str.nil?
+        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?
 
         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 workhours range #{item.inspect}: end must be after start." if end_minutes <= start_minutes
+        raise FlycalCli::Error, "Invalid hours range #{item.inspect}: end must be after start." if end_minutes <= start_minutes
 
         [sh, sm, eh, em]
       end
 
-      raise FlycalCli::Error, "slots.workhours cannot be empty in config.yml." if ranges.empty?
+      raise FlycalCli::Error, "slots.hours cannot be empty in config.yml." if ranges.empty?
 
       ranges.sort_by { |sh, sm, _eh, _em| (sh * 60) + sm }
     end

data/lib/flycal_cli/config.rb

@@ -93,6 +93,11 @@ module FlycalCli
           changed = true
         end
 
+        if normalized.key?("workhours") && !normalized.key?("hours")
+          normalized["hours"] = normalized.delete("workhours")
+          changed = true
+        end
+
         return [data, false] unless changed
 
         data = data.dup

data/lib/flycal_cli/date_time_parser.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+require "active_support/core_ext/time"
+require "active_support/core_ext/date"
+
+module FlycalCli
+  # Parses CLI date/time arguments in a locale-aware way.
+  #
+  # Always accepts ISO-like forms:
+  #   YYYY-MM-DD, YYYY/MM/DD
+  #   YYYY-MM-DDTHH:MM, YYYY-MM-DD HH:MM(:SS)
+  #
+  # With locale +it+: DD-MM-YYYY / DD/MM/YYYY (+ optional time)
+  # With locale +en+ (default): MM-DD-YYYY / MM/DD/YYYY (+ optional time)
+  class DateTimeParser
+    TIME_SUFFIX = '(?:\s+|T)(\d{1,2}):(\d{2})(?::(\d{2}))?'.freeze
+
+    class << self
+      def parse(str, end_of_day: false, locale: nil)
+        value = str.to_s.strip
+        raise FlycalCli::Error, invalid_message(str) if value.empty?
+
+        loc = (locale || Locale.current_locale).to_s
+        formats = formats_for(loc)
+
+        formats.each do |pattern, order|
+          match = value.match(pattern)
+          next unless match
+
+          year, month, day, hour, min, sec = extract_parts(match, order)
+          return build_time(year, month, day, hour, min, sec, end_of_day: end_of_day)
+        end
+
+        # Last resort: ISO8601 / Time.parse for full timestamps
+        begin
+          return Time.iso8601(value)
+        rescue ArgumentError
+          # fall through
+        end
+
+        begin
+          parsed = Time.parse(value)
+          return end_of_day && !time_component?(value) ? end_of_day_for(parsed.to_date) : parsed
+        rescue ArgumentError
+          raise FlycalCli::Error, invalid_message(str)
+        end
+      end
+
+      def parse_or_default(str, default: Time.now, end_of_day: false, locale: nil)
+        return default if str.nil? || str.to_s.strip.empty?
+
+        parse(str, end_of_day: end_of_day, locale: locale)
+      end
+
+      private
+
+      def formats_for(locale)
+        iso = [
+          [/\A(\d{4})[-\/](\d{1,2})[-\/](\d{1,2})#{TIME_SUFFIX}\z/i, %i[year month day hour min sec]],
+          [/\A(\d{4})[-\/](\d{1,2})[-\/](\d{1,2})\z/, %i[year month day]]
+        ]
+
+        local =
+          if locale == "it"
+            [
+              [/\A(\d{1,2})[-\/](\d{1,2})[-\/](\d{4})#{TIME_SUFFIX}\z/i, %i[day month year hour min sec]],
+              [/\A(\d{1,2})[-\/](\d{1,2})[-\/](\d{4})\z/, %i[day month year]]
+            ]
+          else
+            [
+              [/\A(\d{1,2})[-\/](\d{1,2})[-\/](\d{4})#{TIME_SUFFIX}\z/i, %i[month day year hour min sec]],
+              [/\A(\d{1,2})[-\/](\d{1,2})[-\/](\d{4})\z/, %i[month day year]]
+            ]
+          end
+
+        iso + local
+      end
+
+      def extract_parts(match, order)
+        parts = {}
+        order.each_with_index do |key, idx|
+          parts[key] = match[idx + 1]
+        end
+
+        [
+          parts[:year].to_i,
+          parts[:month].to_i,
+          parts[:day].to_i,
+          parts[:hour]&.to_i,
+          parts[:min]&.to_i,
+          parts[:sec]&.to_i
+        ]
+      end
+
+      def build_time(year, month, day, hour, min, sec, end_of_day:)
+        date = Date.new(year, month, day)
+
+        if hour.nil?
+          return end_of_day_for(date) if end_of_day
+          return [date.to_time, Time.now].max if date == Date.today
+
+          return date.to_time
+        end
+
+        Time.local(year, month, day, hour, min || 0, sec || 0)
+      rescue ArgumentError
+        raise FlycalCli::Error, "Invalid date: #{year}-#{month}-#{day}"
+      end
+
+      def end_of_day_for(date)
+        Time.local(date.year, date.month, date.day, 23, 59, 59)
+      end
+
+      def time_component?(value)
+        value.match?(/T|\d{1,2}:\d{2}/)
+      end
+
+      def invalid_message(str)
+        if Locale.current_locale.to_s == "it"
+          "Data non valida: #{str.inspect}. Usa YYYY-MM-DD, DD-MM-YYYY (anche con /) o con orario."
+        else
+          "Invalid date: #{str.inspect}. Use YYYY-MM-DD, MM-DD-YYYY (also with /), or with time."
+        end
+      end
+    end
+  end
+end

data/lib/flycal_cli/duration_parser.rb

@@ -10,7 +10,9 @@ module FlycalCli
       "m" => :minutes, "min" => :minutes, "mins" => :minutes, "minute" => :minutes, "minutes" => :minutes,
       "h" => :hours, "hr" => :hours, "hour" => :hours, "hours" => :hours,
       "d" => :days, "day" => :days, "days" => :days,
-      "w" => :weeks, "week" => :weeks, "weeks" => :weeks
+      "w" => :weeks, "week" => :weeks, "weeks" => :weeks,
+      "month" => :months, "months" => :months,
+      "y" => :years, "year" => :years, "years" => :years
     }.freeze
 
     class << self
@@ -21,11 +23,18 @@ module FlycalCli
         raise FlycalCli::Error, invalid_message(str) unless match
 
         value = match[1].to_f
-        unit = UNITS[match[2]]
+        unit_key = match[2]
+        unit = UNITS[unit_key]
         raise FlycalCli::Error, invalid_message(str) unless unit
-
-        duration = value.public_send(unit)
-        duration
+        # Ambiguous bare "m": treat as minutes (not months)
+        unit = :minutes if unit_key == "m"
+
+        # months/years are Integer-only ActiveSupport extensions
+        if %i[months years].include?(unit)
+          value.to_i.public_send(unit)
+        else
+          value.public_send(unit)
+        end
       end
 
       def to_seconds(str)
@@ -39,7 +48,7 @@ module FlycalCli
       private
 
       def invalid_message(str)
-        "Invalid duration: #{str.inspect}. Examples: 1h, 1 hour, 30 minutes, 3 days"
+        "Invalid duration: #{str.inspect}. Examples: 1h, 30 minutes, 3 days, 1 week, 2 months, 1 year"
       end
     end
   end

data/lib/flycal_cli/locale.rb

@@ -31,6 +31,12 @@ module FlycalCli
       months[idx] || date_or_time.strftime("%B")
     end
 
+    def format_long_date(date_or_time)
+      t = date_or_time.respond_to?(:to_time) ? date_or_time.to_time : date_or_time
+      d = t.to_date
+      "#{day_abbr(d).downcase} #{d.day} #{month_name(d)} #{d.year}"
+    end
+
     def current_locale
       Thread.current[:flycal_locale_override] || Config.locale
     rescue StandardError

data/lib/flycal_cli/slot_finder.rb

@@ -3,6 +3,7 @@
 module FlycalCli
   class SlotFinder
     DEFAULT_WORKHOURS = [[9, 0, 18, 0]].freeze
+    STEP_SECONDS = 900
 
     def initialize(
       events:,
@@ -10,7 +11,9 @@ module FlycalCli
       time_max:,
       slot_duration_seconds:,
       workhours: DEFAULT_WORKHOURS,
-      weekdays_only: true
+      weekdays_only: true,
+      free_before_seconds: 0,
+      free_after_seconds: 0
     )
       @events = events
       @time_min = time_min
@@ -18,6 +21,8 @@ module FlycalCli
       @slot_duration_seconds = slot_duration_seconds
       @workhours = workhours
       @weekdays_only = weekdays_only
+      @free_before_seconds = free_before_seconds
+      @free_after_seconds = free_after_seconds
     end
 
     def slots_by_day
@@ -30,7 +35,9 @@ module FlycalCli
 
           busy = busy_intervals_for(date, day_start, day_end)
           gaps = free_gaps(day_start, day_end, busy)
-          slots.concat(gaps.filter_map { |start_at, end_at| slot_if_fits(start_at, end_at) })
+          gaps.each do |gap_start, gap_end|
+            slots.concat(slots_in_gap(gap_start, gap_end))
+          end
         end
         result[date] = slots unless slots.empty?
       end
@@ -74,7 +81,14 @@ module FlycalCli
       intervals = @events.filter_map do |event|
         interval_for_event(event, date, day_start, day_end)
       end
-      merge_intervals(intervals)
+      merge_intervals(intervals.map { |start_at, end_at| pad_busy_interval(start_at, end_at) })
+    end
+
+    def pad_busy_interval(start_at, end_at)
+      [
+        start_at - @free_before_seconds,
+        end_at + @free_after_seconds
+      ]
     end
 
     def interval_for_event(event, date, day_start, day_end)
@@ -127,26 +141,27 @@ module FlycalCli
       gaps
     end
 
-    def slot_if_fits(start_at, end_at)
+    def slots_in_gap(start_at, end_at)
       rounded_start = round_up_15(start_at)
       rounded_end = round_down_15(end_at)
-      return nil if rounded_start >= rounded_end
-      return nil if (rounded_end - rounded_start) < @slot_duration_seconds
+      return [] if rounded_start >= rounded_end
+      return [] if (rounded_end - rounded_start) < @slot_duration_seconds
 
-      [rounded_start, rounded_end]
+      # One continuous free range (not sliding windows of fixed duration)
+      [[rounded_start, rounded_end]]
     end
 
     def round_up_15(time)
       sec = time.to_i
-      remainder = sec % 900
+      remainder = sec % STEP_SECONDS
       return time if remainder.zero?
 
-      Time.at(sec + (900 - remainder))
+      Time.at(sec + (STEP_SECONDS - remainder))
     end
 
     def round_down_15(time)
       sec = time.to_i
-      Time.at(sec - (sec % 900))
+      Time.at(sec - (sec % STEP_SECONDS))
     end
 
     def to_time(value)

data/lib/flycal_cli/slot_formatter.rb

@@ -3,6 +3,22 @@
 module FlycalCli
   class SlotFormatter
     class << self
+      def format_header(from:, to:, duration:, calendars:, count:)
+        lines = []
+        lines << Locale.t(
+          "slots.header",
+          count: count,
+          from: underline(Locale.format_long_date(from)),
+          to: underline(Locale.format_long_date(to)),
+          duration: underline(duration)
+        )
+        calendars.each do |cal|
+          lines << cal[:name].to_s
+        end
+        lines << google_calendar_day_url(from)
+        lines.join("\n")
+      end
+
       def format_output(slots_by_day)
         lines = []
 
@@ -19,6 +35,15 @@ module FlycalCli
 
       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

data/lib/flycal_cli/version.rb

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

data/lib/flycal_cli.rb

@@ -5,6 +5,7 @@ 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/calendar_service"
 require "flycal_cli/slot_finder"
 require "flycal_cli/slot_formatter"

data/locales/en.json

@@ -30,7 +30,9 @@
   },
   "slots": {
     "no_available": "No available slots found.",
-    "no_calendar": "No calendar found. Run 'flycal config' to set a default."
+    "no_calendar": "No calendar found. Run 'flycal config' to set a default.",
+    "header": "found %{count} slots\nfrom %{from} to %{to}\nwith duration %{duration}\nfor calendars",
+    "copied_to_clipboard": "✓ Slot list copied to clipboard (pbcopy)"
   },
   "errors": {
     "not_connected": "You are not connected. Run 'flycal login' first.",

data/locales/it.json

@@ -30,7 +30,9 @@
   },
   "slots": {
     "no_available": "Nessuno slot disponibile.",
-    "no_calendar": "Nessun calendario trovato. Esegui 'flycal config' per impostare il predefinito."
+    "no_calendar": "Nessun calendario trovato. Esegui 'flycal config' per impostare il predefinito.",
+    "header": "trovati %{count} slot\nda %{from} a %{to}\ncon durata %{duration}\nper i calendari",
+    "copied_to_clipboard": "✓ Lista slot copiata negli appunti (pbcopy)"
   },
   "errors": {
     "not_connected": "Non sei connesso. Esegui prima 'flycal login'.",

data/mcp/README.md

@@ -0,0 +1,29 @@
+# flycal MCP catalog
+
+This directory contains a machine-readable description of **flycal-cli** commands for MCP (Model Context Protocol) servers.
+
+## File
+
+- [`tools.json`](./tools.json) — tools catalog with MCP-style `inputSchema`, CLI argv templates, auth/interactivity flags, and config keys.
+
+## How an MCP server can use it
+
+1. Load `tools.json` at startup.
+2. Register each entry in `tools` with your MCP SDK (`server.tool(...)`), using `name`, `description`, and `inputSchema`.
+3. On tool call, build the argv:
+   - static tools → `command.argv`
+   - parameterized tools → start from `command.argv_template`, then append pairs from `command.option_map` for each provided argument
+   - if `locale` is set → append `--locale <value>`
+4. Run `flycal` as a subprocess and return stdout as text content.
+5. Skip or gate tools with `"interactive": true` (`flycal_login`, `flycal_config`) unless a TTY is available.
+
+## Suggested tools to expose
+
+| MCP tool | CLI | Notes |
+|---|---|---|
+| `flycal_search` | `flycal search ...` | Primary read tool |
+| `flycal_slots` | `flycal slots --in ... --duration ...` | Free slots |
+| `flycal_calendars` | `flycal calendars` | List name + id |
+| `flycal_version` | `flycal version` | Health / version check |
+
+Interactive / side-effect tools (`login`, `logout`, `config`, `update`) are documented in the catalog but are usually better left to the user terminal.

data/mcp/tools.json

@@ -0,0 +1,318 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "flycal-cli",
+  "title": "flycal CLI MCP tools catalog",
+  "description": "Machine-readable catalog of flycal-cli commands for MCP servers. Each tool maps to a CLI invocation via the `command` template. Non-interactive tools are safe to run from an MCP host; interactive tools require a TTY and should be surfaced as guidance only or refused unless the client can attach a terminal.",
+  "version": "0.5.0",
+  "binary": "flycal",
+  "homepage": "https://github.com/magnum/flycal-cli",
+  "locale": {
+    "global_option": "--locale",
+    "supported": ["en", "it"],
+    "default": "en",
+    "config_key": "locale"
+  },
+  "config": {
+    "path": "~/.flycal/config.yml",
+    "credentials_path": "~/.flycal/credentials.json",
+    "keys": {
+      "calendar_default": {
+        "type": "string",
+        "description": "Default Google Calendar ID used by search and as slots fallback"
+      },
+      "locale": {
+        "type": "string",
+        "enum": ["en", "it"],
+        "description": "Default CLI locale"
+      },
+      "slots.hours": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Slot search hour ranges, e.g. [\"9:30-13:00\", \"14:00-18:30\"]"
+      },
+      "slots.defaults.from": {
+        "type": "string",
+        "description": "Default --from for slots (e.g. now or a date string)"
+      },
+      "slots.defaults.default_duration": {
+        "type": "string",
+        "description": "Default slot duration when --duration is omitted (e.g. 45min)"
+      },
+      "slots.free_before": {
+        "type": "string",
+        "description": "Buffer before each slot; events block this window before slot start"
+      },
+      "slots.free_after": {
+        "type": "string",
+        "description": "Buffer after each slot; gaps must fit duration + free_after"
+      },
+      "slots.weekdays_only": {
+        "type": "boolean",
+        "description": "When true, slots are searched Mon–Fri only"
+      },
+      "slots.exclude_calendars": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Calendar IDs whose events block free slots. If empty, calendar_default is used."
+      }
+    }
+  },
+  "notes": [
+    "flycal is read-only against Google Calendar (no create/update/delete of events).",
+    "Auth uses OAuth desktop flow; tokens live under ~/.flycal/.",
+    "Prefer quoting duration values that contain spaces (e.g. --in \"3 days\").",
+    "Duration formats without spaces also work (e.g. 30days, 48hours, 1h, 30min)."
+  ],
+  "tools": [
+    {
+      "name": "flycal_version",
+      "title": "Show flycal version",
+      "description": "Print the installed flycal-cli version.",
+      "interactive": false,
+      "requires_auth": false,
+      "command": {
+        "argv": ["flycal", "version"],
+        "alternatives": [["flycal", "--version"], ["flycal", "-v"]]
+      },
+      "inputSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "locale": {
+            "type": "string",
+            "enum": ["en", "it"],
+            "description": "Optional locale override for this invocation"
+          }
+        }
+      }
+    },
+    {
+      "name": "flycal_update",
+      "title": "Update flycal gem",
+      "description": "Run gem update flycal-cli to install the latest published version.",
+      "interactive": false,
+      "requires_auth": false,
+      "side_effects": ["updates_local_gem"],
+      "command": {
+        "argv": ["flycal", "update"]
+      },
+      "inputSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "locale": {
+            "type": "string",
+            "enum": ["en", "it"]
+          }
+        }
+      }
+    },
+    {
+      "name": "flycal_login",
+      "title": "Connect Google account",
+      "description": "Start OAuth browser login for Google Calendar. Requires ~/.flycal/credentials.json and a browser. Interactive.",
+      "interactive": true,
+      "requires_auth": false,
+      "side_effects": ["writes_tokens"],
+      "command": {
+        "argv": ["flycal", "login"]
+      },
+      "inputSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "locale": {
+            "type": "string",
+            "enum": ["en", "it"]
+          }
+        }
+      }
+    },
+    {
+      "name": "flycal_logout",
+      "title": "Disconnect Google account",
+      "description": "Remove stored Google OAuth tokens and disconnect the account.",
+      "interactive": false,
+      "requires_auth": false,
+      "side_effects": ["deletes_tokens"],
+      "command": {
+        "argv": ["flycal", "logout"]
+      },
+      "inputSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "locale": {
+            "type": "string",
+            "enum": ["en", "it"]
+          }
+        }
+      }
+    },
+    {
+      "name": "flycal_calendars",
+      "title": "List calendars",
+      "description": "List available Google calendars as lines of \"name id\". Does not change configuration.",
+      "interactive": false,
+      "requires_auth": true,
+      "command": {
+        "argv": ["flycal", "calendars"]
+      },
+      "output": {
+        "format": "text/lines",
+        "example": "Work molinari@incode.it\nPersonal user@gmail.com"
+      },
+      "inputSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "locale": {
+            "type": "string",
+            "enum": ["en", "it"]
+          }
+        }
+      }
+    },
+    {
+      "name": "flycal_config",
+      "title": "Configure flycal (interactive)",
+      "description": "Interactive configuration menu. Options: calendar_default (single select), exclude_calendars (multi-select, min 1), edit config (opens ~/.flycal/config.yml in $EDITOR or vi). Ctrl+C prints \"config cancelled...\". Prefer editing config.yml or using dedicated non-interactive flows from MCP hosts.",
+      "interactive": true,
+      "requires_auth": true,
+      "side_effects": ["writes_config"],
+      "command": {
+        "argv": ["flycal", "config"]
+      },
+      "menu_options": [
+        "calendar_default",
+        "exclude_calendars",
+        "edit config"
+      ],
+      "inputSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "locale": {
+            "type": "string",
+            "enum": ["en", "it"]
+          }
+        }
+      }
+    },
+    {
+      "name": "flycal_search",
+      "title": "Search calendar events",
+      "description": "Search Google Calendar events. Prints one line per event (Calendar | Start | End | Title) plus a summary with total occupied time in hours/minutes and 8-hour working days. For ranges >7 days adds a weekly breakdown; for >30 days a monthly breakdown. Contains-filter on title/description when description is set. Read-only.",
+      "interactive": false,
+      "requires_auth": true,
+      "command": {
+        "argv_template": ["flycal", "search"],
+        "option_map": {
+          "calendar": ["--calendar", "{value}"],
+          "from": ["--from", "{value}"],
+          "to": ["--to", "{value}"],
+          "in": ["--in", "{value}"],
+          "description": ["--description", "{value}"],
+          "locale": ["--locale", "{value}"]
+        },
+        "examples": [
+          ["flycal", "search"],
+          ["flycal", "search", "--in", "30days", "--description", "placeholder"],
+          ["flycal", "search", "-f", "2025-03-01", "-t", "2025-03-31", "-c", "Work"],
+          ["flycal", "search", "--in", "2months", "-d", "placeholder", "--locale", "it"]
+        ]
+      },
+      "inputSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "calendar": {
+            "type": "string",
+            "description": "Calendar name or ID. Default: calendar_default from config."
+          },
+          "from": {
+            "type": "string",
+            "description": "Start datetime. Default: today midnight. Formats: YYYY-MM-DD or YYYY-MM-DDTHH:MM"
+          },
+          "to": {
+            "type": "string",
+            "description": "End datetime. Default: 23:59 of day 30 from today. Ignored when `in` is set."
+          },
+          "in": {
+            "type": "string",
+            "description": "Duration from `from` (or now/from default), overrides `to`. Prefer no spaces or quote values: 30days, 48hours, 2months, 1year, or \"30 days\"."
+          },
+          "description": {
+            "type": "string",
+            "description": "Case-insensitive contains filter on event summary or description."
+          },
+          "locale": {
+            "type": "string",
+            "enum": ["en", "it"]
+          }
+        }
+      }
+    },
+    {
+      "name": "flycal_slots",
+      "title": "Find free time slots",
+      "description": "Find free slots within configured hours, subtracting busy events from slots.exclude_calendars (or calendar_default if that list is empty). Starts from --from (default: config slots.defaults.from or now) for a window of --in (default: 1 week). Duration defaults to slots.defaults.default_duration (45min). Respects free_before and free_after buffers from config. Output begins with a multi-line header, calendar names, a Google Calendar day link, then continuous free ranges (each at least as long as duration). Read-only.",
+      "interactive": false,
+      "requires_auth": true,
+      "command": {
+        "argv_template": ["flycal", "slots"],
+        "required_options": [],
+        "option_map": {
+          "duration": ["--duration", "{value}"],
+          "from": ["--from", "{value}"],
+          "in": ["--in", "{value}"],
+          "calendar": ["--calendar", "{value}"],
+          "locale": ["--locale", "{value}"]
+        },
+        "examples": [
+          ["flycal", "slots"],
+          ["flycal", "slots", "--duration", "1h"],
+          ["flycal", "slots", "--from", "2026-08-01", "--in", "2 weeks", "--duration", "1h"]
+        ]
+      },
+      "output": {
+        "format": "text/plain",
+        "example": "found 3 slots\nfrom wed 29 July 2026 to wed 5 August 2026\nwith duration 45min\nfor calendars\nWork\nhttps://calendar.google.com/calendar/r/day/2026/7/29\n\nfriday 15/7\n10-12\n13-15.30"
+      },
+      "inputSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [],
+        "properties": {
+          "duration": {
+            "type": "string",
+            "description": "Slot length. Default from config slots.defaults.default_duration (45min)."
+          },
+          "from": {
+            "type": "string",
+            "description": "Start date/time. Default: now. YYYY-MM-DD always; with locale it also DD-MM-YYYY; with locale en also MM-DD-YYYY. Separators - or /. Optional time."
+          },
+          "in": {
+            "type": "string",
+            "description": "Search window from --from. Default: 1 week. Examples: 3 days, 1 week, 48 hours (quote if spaces)."
+          },
+          "calendar": {
+            "type": "string",
+            "description": "Fallback calendar name/ID when exclude_calendars is not configured."
+          },
+          "locale": {
+            "type": "string",
+            "enum": ["en", "it"]
+          }
+        }
+      }
+    }
+  ],
+  "mcp_implementation_hints": {
+    "execution": "Spawn the flycal binary with argv from command.argv or build argv from option_map. Capture stdout/stderr and exit code. Return stdout as MCP text content.",
+    "interactive_tools": "Do not auto-run tools with interactive=true unless the host provides a TTY. Instead tell the user to run the command in a terminal.",
+    "auth_errors": "If stdout/stderr indicates the user is not connected, suggest flycal login.",
+    "locale_arg": "If input.locale is set, append --locale <value> to argv for any tool.",
+    "tool_filter": "Expose at least flycal_search, flycal_slots, flycal_calendars, and flycal_version for agent use."
+  }
+}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flycal-cli
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - flycal-cli
@@ -139,6 +139,7 @@ files:
 - lib/flycal_cli/calendar_service.rb
 - lib/flycal_cli/cli.rb
 - lib/flycal_cli/config.rb
+- lib/flycal_cli/date_time_parser.rb
 - lib/flycal_cli/duration_parser.rb
 - lib/flycal_cli/locale.rb
 - lib/flycal_cli/slot_finder.rb
@@ -146,6 +147,8 @@ files:
 - lib/flycal_cli/version.rb
 - locales/en.json
 - locales/it.json
+- mcp/README.md
+- mcp/tools.json
 homepage: https://github.com/magnum/flycal-cli
 licenses:
 - MIT