flycal-cli 0.7.3 → 0.7.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9b15a5f08efcc922a2088d9a4c47fb852794932b4261406312f262905664c09
-  data.tar.gz: 114f71e6f2ca779315908015cf0b772f374b0e9de04e5775b220f8c3278aa5e5
+  metadata.gz: db8d0ab49b0872b92c469825aff6a0a944f9012eed76c8bc0768bc82156de1f9
+  data.tar.gz: 16e758564b7adee8f7ea53b79c856865105afc26aa8489abe73313906f35ceb5
 SHA512:
-  metadata.gz: 1545a6259e5a710d4db52267909e7bbbff350aba2e75d617c9e6e2cbb722bb77f9663b5ca8e08483a5606f8030642952c7b1f5c170c4550de706503d15db3fd8
-  data.tar.gz: 6a63614ed3c9cd16ad5d1cf01b358e49edd5fc46ef285b986e181973ef0c660e9353f40e38ae130265bc470073730314d31fce48639ba3942338989a371042c5
+  metadata.gz: 9485b33d254189f6f96d4c96f9e8867b047b35354fc60f63da86b8bd84612686afb559b6d5d937b98f41ac091777fd32a25ef1d0827a0cc6f4eb7f11be2287e5
+  data.tar.gz: c9b338282c8fa1ecc7a6b979d6c7c8632fcfe03ae598affdb27b98e603545dfb85e688d9d1180569bea2106094322fb9b664f48db89a731dade13d6c80ed2fe9

data/README.md

@@ -1,188 +1,48 @@
 # flycal-cli
 
-[![Gem Version](https://badge.fury.io/rb/flycal-cli.svg)](https://badge.fury.io/rb/flycal-cli) 
+[![Gem Version](https://badge.fury.io/rb/flycal-cli.svg)](https://badge.fury.io/rb/flycal-cli)
 
-A command-line tool to access and search Google Calendar events. Connect your Google account, choose a default calendar, and search events with flexible date ranges and text filters.
+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.
 
-## Requirements
-
-- Ruby 3.1 or later
-- A Google Cloud project with Calendar API enabled
-
-## Installation
+## Quick start
 
 ```bash
 gem install flycal-cli
-```
-
-Or add to your Gemfile:
-
-```ruby
-gem "flycal-cli"
-```
-
-Then run `bundle install`.
-
-## Setup
-
-Before using flycal, you need OAuth credentials from Google Cloud Console:
-
-1. Go to [Google Cloud Console - Credentials](https://console.cloud.google.com/apis/credentials)
-2. Create a project or select an existing one
-3. Enable the **Google Calendar API** (APIs & Services → Library → search for "Google Calendar API")
-4. Create **Desktop app** credentials (OAuth 2.0 Client IDs)
-5. Add this URI as an authorized redirect:
-   ```
-   http://127.0.0.1:9292/oauth2callback
-   ```
-6. Download the JSON file and save it as `~/.flycal/credentials.json`
-
-## Commands
-
-All commands support a per-invocation locale override:
-
-```bash
-flycal search --locale it --in 7days
-flycal slots --locale en --in "3 days" --duration 1h
-```
-
-### login
-
-Connect to your Google account. Opens a browser for OAuth authentication when not yet connected.
-
-```bash
 flycal login
 ```
 
-If already connected, the command reports the current status and suggests running `flycal config` to set the default calendar.
-
-### logout
-
-Disconnect from your Google account and remove stored tokens.
-
-```bash
-flycal logout
-```
-
-### update
-
-Update `flycal-cli` to the latest published gem version.
-
-```bash
-flycal update
-```
-
-### version
-
-Show the current installed `flycal-cli` version.
-
-```bash
-flycal version
-flycal --version
-flycal -v
-```
-
-### calendars
-
-List available calendars with name and ID.
-
-```bash
-flycal calendars
-```
-
-Example output:
-
-```
-Work user@example.com
-Personal user@gmail.com
-```
-
-### config
-
-Interactive configuration menu.
-
-```bash
-flycal config
-```
-
-Options:
-
-- `calendar_default` — choose the default calendar and save it to `~/.flycal/config.yml`
-- `exclude_calendars` — multi-select one or more calendars whose events block free slots (default selection includes the current default calendar)
-- `edit config` — open `~/.flycal/config.yml` with `$EDITOR` (or `vi`)
+During the test phase the project already provides the Google API credentials.  
+Open the browser, approve access, done.
 
-Press Ctrl+C during configuration to cancel without error (`config cancelled...`).
-
-The default calendar is used by the search command when no calendar is specified.
-
-### search
-
-Search for events in your calendar(s). Supports flexible date ranges and text filtering.
+Optional but useful once:
 
 ```bash
-flycal search
-flycal search --in 30days --description placeholder
-flycal search -f 2025-03-01 -t 2025-03-31 -c "Work"
-flycal search -i 2months -d placeholder
+flycal config          # set default calendar + calendars that block free slots
+flycal calendars       # list calendars (name + id)
 ```
 
-**Options:**
-
-- `--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)
-
-**Time range behavior:**
+## Common examples
 
-- If neither `--from` nor `--to` is given: searches from today at midnight to 23:59 of the 30th day from today
-- If `--in` is given: `--to` is ignored; the end time is computed from `--from` plus the duration
-- Examples: `--in 30days`, `--in 48hours`, `--in 1months`, `--in 1year`
-
-**Output:**
-
-Each event is printed as: `Calendar | Start | End | Title`
-
-The summary shows:
-- From and To dates used
-- Number of events found
-- Total time occupied (hours, minutes, and working days based on 8-hour days)
-
-For time frames longer than 7 days, a weekly breakdown is added (week number, start/end dates, hours, working days per week). For time frames longer than 30 days, a monthly breakdown is shown instead (month number, month name, hours, working days per month).
-
-### slots
-
-Find free time slots in your calendar. Output is a simple list for copy/paste into email or other tools.
+**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 "5 days" --locale it
-flycal slots --from lunedi --in "5 days" --locale it
+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"
 ```
 
-**Options:**
-
-- `--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`). Accepts:
-  - absolute: `YYYY-MM-DD`, locale dates (`DD-MM-YYYY` / `MM-DD-YYYY`), optional time
-  - relative: `now`, `today`/`oggi`, `tomorrow`/`domani`, `monday`/`lunedi`, `next monday`/`prossimo lunedi`, `last friday`/`scorso venerdi`
-- `--in` / `-i` — Search window from `--from`. Default: `1 week`.
-- `--template` / `-T` — Template from `slots.templates` in config. Default: first template (`work`)
-- `--calendar` / `-c` — Calendar name or ID used as fallback when `exclude_calendars` is not configured
-
-**Output:**
+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
-- incode - antonio
-- Polimi 10110009
-- antoniomolinari1977@gmail.com
+- Work
+- Personal
 link: https://calendar.google.com/calendar/r/day/2026/8/1
 
 saturday 1/8
@@ -192,9 +52,31 @@ monday 3/8
 19 - 23
 ```
 
-If a clipboard tool is available (`pbcopy` on macOS, `wl-copy`/`xclip` on Linux, `clip` on Windows), the slot list without the header is also copied to the clipboard.
+**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`.
+
+---
 
-Slot search windows are configured in `~/.flycal/config.yml`:
+## Configuration (`~/.flycal/config.yml`)
+
+Defaults are created automatically on first run. Edit with `flycal config` → `edit config`, or by hand.
 
 ```yaml
 calendar_default: ~
@@ -202,27 +84,15 @@ locale: en
 slots:
   templates:
     work:
-      days:
-        - 1
-        - 2
-        - 3
-        - 4
-        - 5
+      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
+      days: [1, 2, 3, 4, 5, 6, 7]
       hours:
         - 19-23
-  exclude_calendars: []
+  exclude_calendars: []              # calendars whose events block free slots
   defaults:
     from: now
     default_duration: 45min
@@ -230,80 +100,88 @@ slots:
   free_after: 15m
 ```
 
-Missing keys are filled from `config/defaults.yml` in the gem and saved to your `config.yml` on first read.
-
-- `calendar_default: ~` means no default calendar is set (`~` is YAML null)
-- `templates` — named schedules; default used is the first one (`work`)
-- `templates.*.days` — weekdays as numbers: `1` Monday … `7` Sunday
-- `templates.*.hours` — one or more ranges (`H-H`, `HH:MM-HH:MM`, mixed)
-- `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
-- `free_after` — buffer after each slot; gaps must fit `duration + free_after`, output shows continuous free ranges
-- `exclude_calendars` — calendars whose events block free slots; if empty, `calendar_default` is used
-- `locale` supports `en` and `it` (default is `en`)
+| 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 |
 
-**Output example:**
+Interactive helpers:
 
+```bash
+flycal config
 ```
-friday 15/7
-10 - 12
-13 - 15.30
 
-monday 21/7
-12 - 13
-14 - 15
-```
+- `calendar_default` — pick the default calendar  
+- `exclude_calendars` — multi-select calendars that block slots  
+- `edit config` — open the YAML in `$EDITOR`
 
-## Configuration
+---
 
-Data is stored in `~/.flycal/`:
+## Parameters (reference)
 
-| File | Purpose |
-|:-----|---------|
-| `config.yml` | Default calendar ID and other settings |
-| `credentials.json` | OAuth credentials (created manually from Google Cloud Console) |
-| `tokens.yml` | Access tokens (managed automatically) |
+### `flycal slots`
 
-## Publishing to RubyGems
+| 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` |
 
-### First release
+### `flycal search`
 
-1. Create an account at [rubygems.org](https://rubygems.org) if needed
-2. Update `flycal-cli.gemspec` with your author, email, and homepage
-3. Build and push:
+| 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) |
 
-```bash
-gem build flycal-cli.gemspec
-gem push flycal-cli-0.1.0.gem
-```
+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.
 
-### Subsequent releases
+Relative dates work in English and Italian: `today`/`oggi`, `tomorrow`/`domani`, `monday`/`lunedi`, `next monday`/`prossimo lunedi`, `last friday`/`scorso venerdi`.
 
-1. Update the version in `lib/flycal_cli/version.rb`
-2. Build and push:
+---
 
-```bash
-gem build flycal-cli.gemspec
-gem push flycal-cli-X.Y.Z.gem
-```
+## Optional: your own Google Cloud credentials
 
-3. Optionally tag and push:
+**Not needed** for the default test API — `flycal login` is enough.
 
-```bash
-git tag vX.Y.Z
-git push origin vX.Y.Z
-```
+Use this only if you want flycal to talk to **your own** Google Cloud OAuth client instead of the project-provided test credentials.
 
-### Using rake release
+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`
 
-With `bundler/gem_tasks` in your Rakefile:
+You can also ask a teammate who manages the Cloud project to share that JSON with you.
 
-```bash
-bundle exec rake release
-```
+---
+
+## Files
+
+| Path | Purpose |
+|---|---|
+| `~/.flycal/config.yml` | Settings (calendars, templates, locale, …) |
+| `~/.flycal/credentials.json` | Own OAuth client (optional) |
+| `~/.flycal/tokens.yml` | Login tokens (managed automatically) |
 
-This builds the gem, pushes to RubyGems, and can handle git tagging and pushing.
+MCP catalog for agents: [`mcp/tools.json`](mcp/tools.json)
 
 ## License
 

data/lib/flycal_cli/calendar_service.rb

@@ -57,14 +57,11 @@ module FlycalCli
         end
       end
 
-      # Filter: only events where summary or description contains the search string (case-insensitive)
+      # Filter: summary/description contains any OR term from query ("a|b"), case-insensitive.
       if query && !query.to_s.strip.empty?
-        q = query.strip.downcase
         all_events.select! do |item|
           event = item[:event]
-          summary = (event.summary || "").downcase
-          description = (event.description || "").downcase
-          summary.include?(q) || description.include?(q)
+          DescriptionQuery.match?(event.summary, event.description, query)
         end
       end