flycal-cli 0.7.4 → 1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bfdf39ef3561cb1c12829bd2d28dfaf9c2062df7f4c4a163ee99e057af9d413
-  data.tar.gz: 8f0ee70cc004bfd8e29a1fd4c5d7b5d852c22a3958f2de596cc2c77f9ed044f8
+  metadata.gz: '0683f1fd5316c424662349a75956309890f9fe5d38fd0cd50a4e158f9a7085e1'
+  data.tar.gz: b7507dee7df050d2e4f11bfb80002f82c2d4cb2689daff89c1d4be62f244b5e1
 SHA512:
-  metadata.gz: 8069638ac5162722bc332a577833da48fb92161ee0b2ca39d6c7c31d1c4aeedecaebcc6bf696f0f9945306bbc4e99b8921718867356b5be87a9d1c22b10ff53e
-  data.tar.gz: 0bdca914927e92b873e91d42b7a061502a9558a858e392d1df1c93509c7ec85a281c5f47e309e011fd1ef734259c991a6d3fa761ecd520b5e6913a4d6f83590f
+  metadata.gz: ccabe113d4314bacfd16f3072986d9686919acf4c489a7d8cf9ec05e2bb6dddec59576a859cc210485f9ef56afe7ad9a8522432ba37f0976ae10e5385ffe6e93
+  data.tar.gz: 6fb81eb48cb1bc8ed7ea84b8764eb8c677f1a6b346c5a0841a9498aecd63a06b73f1c801e8dee0f915d3ebf20901e74195356d83a3323edf3ef2725c85fdb4d3

data/README.md

@@ -1,181 +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**
+- Core namespace: `Flycal`
+- CLI namespace: `Flycal::Cli`
+- Gem name: `flycal-cli`
 
 ```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
+ruby -Ilib -Iflycal_cli/lib flycal_cli/bin/flycal --help
 ```
 
-**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:
-
-```bash
-flycal config
-```
-
-- `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 on title/description |
-| `--calendar` / `-c` | `calendar_default` | Name or ID |
-| `--locale` | config / `en` | `en` or `it` |
-
-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/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/calendar_service.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "google/apis/calendar_v3"
+
+module Flycal
+  class CalendarService
+    def initialize(credentials)
+      @service = Google::Apis::CalendarV3::CalendarService.new
+      @service.authorization = credentials
+    end
+
+    def list_calendars
+      result = @service.list_calendar_lists
+      result.items || []
+    end
+
+    def get_calendar(calendar_id)
+      @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
+
+      loop do
+        result = @service.list_events(
+          calendar_id,
+          time_min: iso8601(time_min),
+          time_max: iso8601(time_max),
+          q: query,
+          single_events: true,
+          order_by: "startTime",
+          page_token: page_token
+        )
+
+        events.concat(result.items || [])
+
+        page_token = result.next_page_token
+        break if page_token.nil? || page_token.empty?
+      end
+
+      events
+    end
+
+    def list_all_events(calendar_ids, time_min:, time_max:, query: nil)
+      all_events = []
+
+      # When --description is used: fetch all events and filter client-side to guarantee
+      # contains/like behavior. We do not use the API's q param so we can ensure we
+      # return all events where the string appears in summary or description (case-insensitive).
+      calendar_ids.each do |cal_id|
+        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::Error => e
+          warn "Error in calendar #{cal_id}: #{e.message}"
+        end
+      end
+
+      # Filter: summary/description contains any OR term from query ("a|b"), case-insensitive.
+      if query && !query.to_s.strip.empty?
+        all_events.select! do |item|
+          event = item[:event]
+          DescriptionQuery.match?(event.summary, event.description, query)
+        end
+      end
+
+      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