flycal-cli 0.7.7 → 1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db8d0ab49b0872b92c469825aff6a0a944f9012eed76c8bc0768bc82156de1f9
-  data.tar.gz: 16e758564b7adee8f7ea53b79c856865105afc26aa8489abe73313906f35ceb5
+  metadata.gz: fcbd8c2cfb6f90272cf8cc8cfa489bc99a7487efca11f68560b2d7f96ac92f34
+  data.tar.gz: 21e92239db0dc5b3f587abdd1e859b5e67e67293706f6ec1f50ca34ca4fe0e1d
 SHA512:
-  metadata.gz: 9485b33d254189f6f96d4c96f9e8867b047b35354fc60f63da86b8bd84612686afb559b6d5d937b98f41ac091777fd32a25ef1d0827a0cc6f4eb7f11be2287e5
-  data.tar.gz: c9b338282c8fa1ecc7a6b979d6c7c8632fcfe03ae598affdb27b98e603545dfb85e688d9d1180569bea2106094322fb9b664f48db89a731dade13d6c80ed2fe9
+  metadata.gz: 2524fb58d1faecdf6ac6643761315f2586f6fe10b4535f2f50b87418f871665f13c84110c3d627ad2131bb9b2ef95aa171c0e6e1e41b52f87d7b76fd7261493c
+  data.tar.gz: 906c85b9dd3711aa16874a6f41be9851be1accbd07d131b09fb9f6173ed26d0e081f6607b457d606f538ea8861ab98dcff89b6cdab4f482b79ffe0c8af41eb7b

data/README.md

@@ -1,188 +1,13 @@
 # flycal-cli
 
-[![Gem Version](https://badge.fury.io/rb/flycal-cli.svg)](https://badge.fury.io/rb/flycal-cli)
+CLI wrapper around **Flycal** core (`lib/flycal` in the monorepo).
 
-Read your Google Calendar from the terminal: search events, find free slots, copy them into an email. **Read-only** — nothing is modified on the calendar.
-
-## Quick start
-
-```bash
-gem install flycal-cli
-flycal login
-```
-
-During the test phase the project already provides the Google API credentials.  
-Open the browser, approve access, done.
-
-Optional but useful once:
-
-```bash
-flycal config          # set default calendar + calendars that block free slots
-flycal calendars       # list calendars (name + id)
-```
-
-## Common examples
-
-**Find free slots (most useful day-to-day)**
-
-```bash
-flycal slots
-flycal slots --in "5 days"
-flycal slots --from monday --in "5 days"
-flycal slots --from "next monday" --in "2 weeks" --duration 1h
-flycal slots --in "12 days" --template dinner
-flycal slots --locale it --from lunedi --in "5 days"
-```
-
-Output is a short header plus a clean list ready to paste (and copied to the clipboard when `pbcopy` / `clip` / `wl-copy` / `xclip` is available):
-
-```
-found 6 slots
-from sat 1 August 2026 to sat 8 August 2026
-with duration 45min, template dinner
-considering calendars
-- Work
-- Personal
-link: https://calendar.google.com/calendar/r/day/2026/8/1
-
-saturday 1/8
-19 - 23
-
-monday 3/8
-19 - 23
-```
-
-**Search events**
-
-```bash
-flycal search
-flycal search --in 30days
-flycal search --in 30days --description meeting
-flycal search --from 2026-08-01 --to 2026-08-31 -c Work
-flycal search --from monday --in "2 weeks" --locale it
-```
-
-**Other commands**
-
-```bash
-flycal version
-flycal update
-flycal logout
-```
-
-All commands accept `--locale en|it`.
-
----
-
-## Configuration (`~/.flycal/config.yml`)
-
-Defaults are created automatically on first run. Edit with `flycal config` → `edit config`, or by hand.
-
-```yaml
-calendar_default: ~
-locale: en
-slots:
-  templates:
-    work:
-      days: [1, 2, 3, 4, 5]          # 1=Mon … 7=Sun
-      hours:
-        - 9:30-13:00
-        - 14:00-18:30
-    dinner:
-      days: [1, 2, 3, 4, 5, 6, 7]
-      hours:
-        - 19-23
-  exclude_calendars: []              # calendars whose events block free slots
-  defaults:
-    from: now
-    default_duration: 45min
-  free_before: 0m
-  free_after: 15m
-```
-
-| Key | Meaning |
-|---|---|
-| `calendar_default` | Default calendar (`~` = unset) |
-| `locale` | `en` or `it` |
-| `slots.templates` | Named schedules; `flycal slots` uses the first one unless `--template` is set |
-| `slots.exclude_calendars` | Events here block free slots (fallback: `calendar_default`) |
-| `slots.defaults.*` | Defaults for `--from` / `--duration` |
-| `slots.free_before` / `free_after` | Buffers around busy events |
-
-Interactive helpers:
+- Core namespace: `Flycal`
+- CLI namespace: `Flycal::Cli`
+- Gem name: `flycal-cli`
 
 ```bash
-flycal config
+ruby -Ilib -Iflycal_cli/lib flycal_cli/bin/flycal --help
 ```
 
-- `calendar_default` — pick the default calendar  
-- `exclude_calendars` — multi-select calendars that block slots  
-- `edit config` — open the YAML in `$EDITOR`
-
----
-
-## Parameters (reference)
-
-### `flycal slots`
-
-| Option | Default | Notes |
-|---|---|---|
-| `--duration` | `45min` | Min free range length (`1h`, `90min`, …) |
-| `--from` / `-f` | `now` | Absolute date or relative: `monday`, `next monday`, `tomorrow`, `lunedi`, … |
-| `--in` / `-i` | `1 week` | Window from `--from` (`"5 days"`, `2weeks`, …) |
-| `--template` / `-T` | first template (`work`) | e.g. `dinner` |
-| `--calendar` / `-c` | — | Fallback if `exclude_calendars` is empty |
-| `--locale` | config / `en` | `en` or `it` |
-
-### `flycal search`
-
-| Option | Default | Notes |
-|---|---|---|
-| `--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; 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`.
-
----
-
-## Optional: your own Google Cloud credentials
-
-**Not needed** for the default test API — `flycal login` is enough.
-
-Use this only if you want flycal to talk to **your own** Google Cloud OAuth client instead of the project-provided test credentials.
-
-1. [Google Cloud Console → Credentials](https://console.cloud.google.com/apis/credentials)
-2. Enable **Google Calendar API**
-3. Create **Desktop app** OAuth credentials
-4. Authorized redirect URI: `http://127.0.0.1:9292/oauth2callback`
-5. Save the JSON as `~/.flycal/credentials.json`
-6. Run `flycal login`
-
-You can also ask a teammate who manages the Cloud project to share that JSON with you.
-
----
-
-## Files
-
-| Path | Purpose |
-|---|---|
-| `~/.flycal/config.yml` | Settings (calendars, templates, locale, …) |
-| `~/.flycal/credentials.json` | Own OAuth client (optional) |
-| `~/.flycal/tokens.yml` | Login tokens (managed automatically) |
-
-MCP catalog for agents: [`mcp/tools.json`](mcp/tools.json)
-
-## License
-
-MIT
+Release from the Rails app root: `bin/release-cli`

data/bin/flycal

@@ -4,8 +4,8 @@
 require "flycal_cli"
 
 if ARGV.include?("--version") || ARGV.include?("-v")
-  puts "flycal #{FlycalCli::VERSION}"
+  puts "flycal #{Flycal::VERSION}"
   exit 0
 end
 
-FlycalCli::Cli.start(ARGV)
+Flycal::Cli::App.start(ARGV)

data/config/defaults.yml

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

data/lib/flycal/cache_annotator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Flycal
+  # Injects cache HIT/MISS metadata into text / JSON payloads.
+  module CacheAnnotator
+    module_function
+
+    def line(status, _cache_key = nil)
+      "Cache: #{status}"
+    end
+
+    def annotate_text(text, status, cache_key = nil)
+      lines = text.to_s.sub(/\n\z/, "").split("\n")
+      insert_cache_line!(lines, status, cache_key, fallback: :append)
+      "#{lines.join("\n")}\n"
+    end
+
+    def annotate_payload!(payload, status, cache_key)
+      payload = stringify_keys(payload)
+      info = payload["info"] ||= {}
+      info["cache"] = status
+      info.delete("cache_key")
+
+      if payload["text"].is_a?(Array)
+        lines = payload["text"].map(&:to_s)
+        insert_cache_line!(lines, status, cache_key, fallback: :unshift)
+        payload["text"] = lines
+      end
+
+      payload
+    end
+
+    def strip_for_storage(payload)
+      copy = Marshal.load(Marshal.dump(stringify_keys(payload)))
+      if copy["info"].is_a?(Hash)
+        copy["info"] = copy["info"].dup
+        copy["info"].delete("cache")
+        copy["info"].delete("cache_key")
+      end
+      if copy["text"].is_a?(Array)
+        copy["text"] = copy["text"].reject { |l| l.to_s.start_with?("Cache:") }
+      end
+      copy
+    end
+
+    def stringify_keys(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(k, v), out| out[k.to_s] = stringify_keys(v) }
+      when Array
+        value.map { |v| stringify_keys(v) }
+      else
+        value
+      end
+    end
+
+    def insert_cache_line!(lines, status, cache_key = nil, fallback: :append)
+      lines.reject! { |l| l.to_s.start_with?("Cache:") }
+      marker = line(status, cache_key)
+
+      occupied_idx = lines.index { |l| l.to_s.start_with?("Total time occupied:") }
+      if occupied_idx
+        lines.insert(occupied_idx + 1, marker)
+        return lines
+      end
+
+      idx = lines.index("---")
+      if idx
+        lines.insert(idx + 1, marker)
+      else
+        blank_idx = lines.index { |l| l == "" }
+        if blank_idx
+          lines.insert(blank_idx, marker)
+        elsif fallback == :unshift
+          lines.unshift(marker)
+        else
+          lines << "---" << marker
+        end
+      end
+      lines
+    end
+  end
+end

data/lib/flycal/cache_key.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Flycal
+  # Builds stable cache keys for search/slots from fully resolved params
+  # (defaults applied, just before Google API calls).
+  class CacheKey
+    DEFAULT_TTL_MINUTES = 5
+
+    # Commands / CLI verbs / API paths that use response caching.
+    # Everything else (version, calendars, login, config, …) is uncached.
+    CACHED_COMMANDS = %w[search slots].freeze
+
+    SKIP_KEYS = %w[
+      nocache cache_status cache_key events totals groups calendar_names raw
+    ].freeze
+
+    class << self
+      def cached_commands
+        CACHED_COMMANDS
+      end
+
+      def cached?(command)
+        CACHED_COMMANDS.include?(command.to_s)
+      end
+
+      def generate(command, params)
+        digest = Digest::SHA256.hexdigest(canonical_json(params))
+        "flycal-#{command}-#{digest}"
+      end
+
+      def canonical_json(params)
+        JSON.generate(deep_sort(normalize(params)))
+      end
+
+      def normalize(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(k, v), out|
+            key = k.to_s
+            next if SKIP_KEYS.include?(key)
+
+            out[key] = normalize(v)
+          end
+        when Array
+          value.map { |v| normalize(v) }
+        when Time, DateTime
+          value.respond_to?(:iso8601) ? value.iso8601 : value.to_s
+        when Date
+          value.iso8601
+        when nil, TrueClass, FalseClass, Numeric, String
+          value
+        else
+          if value.respond_to?(:iso8601)
+            value.iso8601
+          elsif value.respond_to?(:to_h) && !value.is_a?(String)
+            normalize(value.to_h)
+          else
+            value.to_s
+          end
+        end
+      end
+
+      def deep_sort(value)
+        case value
+        when Hash
+          value.keys.map(&:to_s).sort.each_with_object({}) do |k, out|
+            # Hash may have symbol keys after normalize we use strings
+            raw_key = value.key?(k) ? k : value.keys.find { |x| x.to_s == k }
+            out[k] = deep_sort(value[raw_key])
+          end
+        when Array
+          value.map { |v| deep_sort(v) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/flycal/calendar_query.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Flycal
+  # Parses and resolves calendar selection options for CLI and HTTP API.
+  #
+  # Accepts:
+  #   - a single string: "Work"
+  #   - pipe/comma OR list: "Work|Personal" or "Work,Personal"
+  #   - an array (e.g. repeated --calendar flags): ["Work", "Personal"]
+  #   - mixed: ["Work|Gym", "Personal"]
+  module CalendarQuery
+    module_function
+
+    # Expand raw option value(s) into calendar reference strings.
+    def refs(value)
+      Array(value).flat_map { |entry| entry.to_s.split(/[|,]/) }
+                  .map(&:strip)
+                  .reject(&:empty?)
+                  .uniq
+    end
+
+    # Resolve refs to calendar IDs against a list of calendar objects
+    # (must respond to #id / #summary, or hash with those keys).
+    def resolve_ids(calendars, value)
+      refs(value).filter_map { |ref| resolve_ref(calendars, ref) }.uniq
+    end
+
+    def resolve_ref(calendars, ref)
+      ref = ref.to_s.strip
+      return nil if ref.empty?
+
+      exact = calendars.find { |cal| calendar_id(cal) == ref }
+      return calendar_id(exact) if exact
+
+      exact_name = calendars.find { |cal| calendar_summary(cal).to_s.casecmp?(ref) }
+      return calendar_id(exact_name) if exact_name
+
+      needle = ref.downcase
+      partial = calendars.find do |cal|
+        summary = calendar_summary(cal).to_s
+        !summary.empty? && summary.downcase.include?(needle)
+      end
+      calendar_id(partial)
+    end
+
+    def calendar_id(cal)
+      return nil if cal.nil?
+      return cal.id if cal.respond_to?(:id)
+
+      cal[:id] || cal["id"]
+    end
+
+    def calendar_summary(cal)
+      return nil if cal.nil?
+      return cal.summary if cal.respond_to?(:summary)
+
+      cal[:summary] || cal["summary"] || cal[:name] || cal["name"]
+    end
+  end
+end

data/lib/{flycal_cli → flycal}/calendar_service.rb

@@ -2,7 +2,7 @@
 
 require "google/apis/calendar_v3"
 
-module FlycalCli
+module Flycal
   class CalendarService
     def initialize(credentials)
       @service = Google::Apis::CalendarV3::CalendarService.new
@@ -18,6 +18,10 @@ module FlycalCli
       @service.get_calendar(calendar_id)
     end
 
+    def get_event(calendar_id, event_id)
+      @service.get_event(calendar_id, event_id)
+    end
+
     def list_events(calendar_id, time_min:, time_max:, query: nil)
       events = []
       page_token = nil
@@ -25,8 +29,8 @@ module FlycalCli
       loop do
         result = @service.list_events(
           calendar_id,
-          time_min: time_min.iso8601,
-          time_max: time_max.iso8601,
+          time_min: iso8601(time_min),
+          time_max: iso8601(time_max),
           q: query,
           single_events: true,
           order_by: "startTime",
@@ -52,7 +56,7 @@ module FlycalCli
         begin
           events = list_events(cal_id, time_min: time_min, time_max: time_max, query: nil)
           events.each { |e| all_events << { calendar_id: cal_id, event: e } }
-        rescue Google::Apis::Errors::Error => e
+        rescue Google::Apis::Error => e
           warn "Error in calendar #{cal_id}: #{e.message}"
         end
       end
@@ -67,5 +71,45 @@ module FlycalCli
 
       all_events
     end
+
+    def create_event(calendar_id: "primary", summary:, start_time:, end_time:, all_day: false)
+      event = Google::Apis::CalendarV3::Event.new(summary: summary)
+      apply_event_times!(event, start_time: start_time, end_time: end_time, all_day: all_day)
+      @service.insert_event(calendar_id, event)
+    end
+
+    def update_event(calendar_id: "primary", event_id:, summary:, start_time:, end_time:, all_day: false)
+      event = get_event(calendar_id, event_id)
+      event.summary = summary if summary && !summary.to_s.empty?
+      apply_event_times!(event, start_time: start_time, end_time: end_time, all_day: all_day)
+      @service.update_event(calendar_id, event_id, event)
+    end
+
+    private
+
+    def iso8601(value)
+      return value.iso8601 if value.respond_to?(:iso8601)
+      return value.to_time.iso8601 if value.respond_to?(:to_time)
+
+      value.to_s
+    end
+
+    def apply_event_times!(event, start_time:, end_time:, all_day:)
+      if all_day
+        event.start = Google::Apis::CalendarV3::EventDateTime.new(
+          date: Date.parse(start_time.to_s).to_s
+        )
+        event.end = Google::Apis::CalendarV3::EventDateTime.new(
+          date: Date.parse((end_time || start_time).to_s).to_s
+        )
+      else
+        event.start = Google::Apis::CalendarV3::EventDateTime.new(
+          date_time: DateTime.parse(start_time.to_s).rfc3339
+        )
+        event.end = Google::Apis::CalendarV3::EventDateTime.new(
+          date_time: DateTime.parse((end_time || start_time).to_s).rfc3339
+        )
+      end
+    end
   end
 end