@bobfrankston/gcal 0.1.45 → 0.1.47

package/README.md

@@ -1,92 +1,150 @@
-# @bobfrankston/gcal
-
-Google Calendar CLI tool with ICS import support.
-
-## Installation
-
-```bash
-npm install -g @bobfrankston/gcal
-```
-
-## Usage
-
-```bash
-gcal <file.ics>                    Import ICS file (file association)
-gcal <command> [options]           Run command
-```
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `list [n]` | List upcoming n events (default: 10) |
-| `list -since <date>` | List events from `<date>` forward (past dates allowed) |
-| `add <title> <when> [duration]` | Add event (explicit args) |
-| `add` | Add event (type description interactively) |
-| `add "free text description"` | Add event (AI parses single text arg) |
-| `add -clip` | Add event from clipboard text (AI-parsed) |
-| `del\|delete <id> [id2...]` | Delete event(s) by ID (prefix match) |
-| `remind <id> <dur> [dur2...]` | Add reminder(s) to existing event |
-| `resched <id> <when> [duration]` | Reschedule event (preserves duration by default) |
-| `snooze <id> [when]` | Snooze event; defaults to `+1d` |
-| `import <file.ics>` | Import events from ICS file |
-| `calendars` | List available calendars |
-| `assoc` | Set up .ics file association (Windows) |
-| `help` | Show help |
-
-## Options
-
-| Flag | Description |
-|------|-------------|
-| `-u`, `-user <email>` | Set default Google account |
-| `-c`, `-calendar <id>` | Calendar ID (default: primary) |
-| `-n <count>` | Number of events to list |
-| `-v`, `-verbose` | Show event IDs and links |
-| `-b`, `-birthdays` | Include birthday events (hidden by default) |
-| `-clip` | Read from clipboard (for add command) |
-| `-r`, `-reminder <dur>` | Add popup reminder (e.g., 30m, 1h); repeatable |
-| `-since <date>` | Start listing from `<date>` (e.g. `"10 days ago"`, `"April 1"`, `yesterday`) |
-| `-all` | Delete all instances of recurring event |
-
-## Examples
-
-```bash
-gcal meeting.ics                        # Import ICS file
-gcal list                               # List next 10 events
-gcal list -since "10 days ago"          # Include events from 10 days ago forward
-gcal list -since "april 1" -n 50        # 50 events since April 1
-gcal add "Dentist" "Friday 3pm" "1h"
-gcal add "Lunch" "1/14/2026 12:00" "1h"
-gcal add "Meeting" "tomorrow 10:00"
-gcal add "Appointment" "jan 15 2pm"
-gcal add "Dentist appointment Friday 3pm for 1 hour"
-gcal add -clip                          # Add from clipboard text
-gcal add "Dentist" "Friday 3pm" -r 30m  # Add with 30-min reminder
-gcal remind abc12345 30m                # Add 30-min reminder to event
-gcal resched abc12345 "next friday 3pm" # Reschedule to new date/time
-gcal resched abc12345 tomorrow          # Move to tomorrow (preserves time-of-day)
-gcal snooze abc12345                    # Snooze +1 day
-gcal snooze abc12345 +1w                # Snooze +1 week
-gcal add                                # Type event description
-gcal -u bob@gmail.com                   # Set default user
-```
-
-### Reschedule / snooze
-
-`resched` and `snooze` find events up to 30 days in the past by default, so stale
-reminder events remain findable. Use `-since <date>` to widen that window. For
-timed events, if `<when>` lacks a time-of-day (e.g. `tomorrow`, `next friday`) the
-original start time is preserved. All-day events stay all-day. Relative offsets
-`+1d` / `+1w` / `+1h` / `+1m` advance from the event's current start.
-
-## File Association (Windows)
-
-```bash
-gcal assoc    # Sets up .ics → gcal automatically
-```
-
-On first run, gcal will offer to set this up. Run `gcal assoc` anytime to (re)configure it.
-
-## License
-
-MIT
+# @bobfrankston/gcal
+
+Google Calendar **and** Google Tasks CLI tools. Two binaries (`gcal`, `gtask`) shipped together — they share OAuth credentials, scopes, and token files, so you authenticate once.
+
+## Installation
+
+```bash
+npm install -g @bobfrankston/gcal
+```
+
+Provides:
+- `gcal`  — Google Calendar
+- `gtask` — Google Tasks
+
+Both share OAuth client credentials with `gcards` (`%APPDATA%\gcards\credentials.json`).
+
+## gcal — Google Calendar
+
+```bash
+gcal <file.ics>            # Import ICS file (file association)
+gcal <command> [options]
+gcal help <command>        # Detailed help for one command
+```
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `list [n]` | List upcoming n events (default: 10) |
+| `add <title> <when> [duration]` | Add event (explicit) |
+| `add "<free text>"` | Add event (AI-parsed) |
+| `add -clip` | Add event from clipboard (AI-parsed) |
+| `add` | Add event interactively |
+| `del \| delete <id> [id2...]` | Delete event(s) by ID prefix |
+| `remind <id> <dur> [dur2...]` | Add reminder(s) |
+| `resched <id> <when> [duration]` | Reschedule (preserves duration) |
+| `snooze <id> [when]` | Snooze (default `+1d`) |
+| `import <file.ics>` | Import events from ICS |
+| `calendars` | List available calendars |
+| `assoc` | Set up `.ics` file association (Windows) |
+| `help [command]` | Show help |
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-u`, `-user <email>` | Set / use default Google account |
+| `-c`, `-calendar <id>` | Calendar ID (default: primary) |
+| `-n <count>` | Number of events to list |
+| `-v`, `-verbose` | Show event IDs and links |
+| `-b`, `-birthdays` | Include birthday events |
+| `-clip` | Read from clipboard (for `add`) |
+| `-r`, `-reminder <dur>` | Add popup reminder (e.g. `30m`, `1h`); repeatable |
+| `-since <date>` | Start listing from `<date>` |
+| `-till <date>` | End listing at `<date>` |
+| `-all` | Delete all instances of recurring event |
+
+### Examples
+
+```bash
+gcal meeting.ics
+gcal list
+gcal list -since "10 days ago"
+gcal list -since "april 1" -till "may 1"
+gcal add "Dentist" "Friday 3pm" "1h"
+gcal add "Lunch" "1/14/2026 12:00" "1h"
+gcal add "Dentist appointment Friday 3pm for 1 hour"
+gcal add -clip
+gcal add "Dentist" "Friday 3pm" -r 30m
+gcal remind abc12345 30m
+gcal resched abc12345 "next friday 3pm"
+gcal snooze abc12345 +1w
+gcal -u bob@gmail.com
+```
+
+### Reschedule / snooze notes
+
+`resched` and `snooze` find events up to 30 days in the past by default (so stale reminders remain findable). Widen with `-since <date>`. For timed events, if `<when>` lacks a time-of-day (e.g. `tomorrow`), the original time is preserved. All-day events stay all-day. Relative offsets `+1d` / `+1w` / `+1h` / `+1m` advance from the event's current start.
+
+### Windows file association
+
+```bash
+gcal assoc        # Sets up .ics → gcal
+```
+
+On first run, gcal offers to set this up. Run `gcal assoc` anytime to (re)configure.
+
+## gtask — Google Tasks
+
+```bash
+gtask <command> [options]
+gtask help <command>
+```
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `add <title> [when]` | Add a task (optional due date — date-only) |
+| `list` | List open tasks |
+| `lists` | List all tasklists |
+| `done <id>` | Mark task completed |
+| `undone <id>` | Reopen a completed task |
+| `del <id>` | Delete a task |
+| `edit <id> [-t title] [-when date] [-n notes]` | Update fields |
+| `clear` | Remove all completed tasks from list |
+| `move <id> -l <list>` | Move task to another tasklist |
+| `help [command]` | Show help |
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-u`, `-user <email>` | Google account |
+| `-l`, `-list <name\|id>` | Tasklist (default: primary) |
+| `-n`, `-notes <text>` | Notes for `add` / `edit` |
+| `-t`, `-title <text>` | New title for `edit` |
+| `-when <date>` | New due date for `edit` |
+| `-a`, `-all` | Include completed tasks in `list` |
+
+### Examples
+
+```bash
+gtask add "Write report"
+gtask add "Write report" friday
+gtask add "Pay bills" "april 30" -n "rent + utilities"
+gtask add "Call plumber" tomorrow -l Errands
+gtask list
+gtask list -l Errands
+gtask list -a
+gtask done abc12345
+gtask edit abc12345 -when "next monday"
+gtask move abc12345 -l Personal
+gtask clear -l Errands
+```
+
+### Notes on Google Tasks
+
+- **Due dates are date-only.** The Tasks API stores RFC3339 timestamps, but the Google UI ignores time-of-day. `gtask` writes midnight UTC.
+- **No reminders.** Tasks have no notification mechanism in the API. Reminders only appear if you create the task through the Calendar UI's task-with-time feature.
+- **No recurrence.** Recurring tasks aren't exposed via the API.
+- **Hierarchy is flat.** One level of subtasks via `move?parent=`. Not currently surfaced by `gtask`.
+
+## Shared OAuth
+
+Both tools request the combined scope set `calendar + tasks` (read or write depending on operation). The first time you run either tool after upgrading, Google prompts once for the new combined consent; afterward both share `token.json` / `token-write.json`.
+
+## License
+
+MIT

package/gcal.js

@@ -11,65 +11,12 @@ import fs from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
 import { createInterface } from 'readline/promises';
-import { authenticateOAuth } from '@bobfrankston/oauthsupport';
-import { CREDENTIALS_FILE, loadConfig, saveConfig, getUserPaths, ensureUserDir, formatDateTime, formatDuration, parseDuration, parseDateTime, hasTimeComponent, parseAllDay, formatYMD, ts, normalizeUser } from './glib/gutils.js';
+import { loadConfig, saveConfig, formatDateTime, formatDuration, parseDuration, parseDateTime, hasTimeComponent, parseAllDay, formatYMD, normalizeUser } from './glib/gutils.js';
+import { setupAbortHandler, getAccessToken, apiFetch } from './glib/goauth.js';
 import { extractEventsFromText, readClipboard } from './glib/aihelper.js';
 import pkg from './package.json' with { type: 'json' };
 const VERSION = pkg.version;
 const CALENDAR_API_BASE = 'https://www.googleapis.com/calendar/v3';
-const CALENDAR_SCOPE_READ = 'https://www.googleapis.com/auth/calendar.readonly';
-const CALENDAR_SCOPE_WRITE = 'https://www.googleapis.com/auth/calendar';
-let abortController = null;
-function setupAbortHandler() {
-    abortController = new AbortController();
-    let ctrlCCount = 0;
-    process.on('SIGINT', () => {
-        ctrlCCount++;
-        abortController?.abort();
-        if (ctrlCCount >= 2) {
-            console.log('\n\nForce exit.');
-            process.exit(1);
-        }
-        console.log('\n\nCtrl+C pressed - aborting... (press again to force exit)');
-    });
-}
-async function getAccessToken(user, writeAccess = false, forceRefresh = false) {
-    if (!fs.existsSync(CREDENTIALS_FILE)) {
-        console.error(`\nCredentials file not found: ${CREDENTIALS_FILE}\n`);
-        console.error(`gcal uses the same credentials as gcards.`);
-        console.error(`Make sure gcards is set up with OAuth credentials first.`);
-        console.error(`See: https://github.com/BobFrankston/oauthsupport/blob/master/SETUP-GOOGLE-OAUTH.md`);
-        process.exit(1);
-    }
-    const paths = getUserPaths(user);
-    ensureUserDir(user);
-    const scope = writeAccess ? CALENDAR_SCOPE_WRITE : CALENDAR_SCOPE_READ;
-    const tokenFileName = writeAccess ? 'token-write.json' : 'token.json';
-    const tokenFilePath = path.join(paths.userDir, tokenFileName);
-    if (forceRefresh && fs.existsSync(tokenFilePath)) {
-        fs.unlinkSync(tokenFilePath);
-        console.log(`${ts()} Token expired, refreshing...`);
-    }
-    const token = await authenticateOAuth(CREDENTIALS_FILE, {
-        scope,
-        tokenDirectory: paths.userDir,
-        tokenFileName,
-        credentialsKey: 'installed',
-        signal: abortController?.signal
-    });
-    if (!token) {
-        throw new Error('OAuth authentication failed');
-    }
-    return token.access_token;
-}
-async function apiFetch(url, accessToken, options = {}) {
-    const headers = {
-        'Authorization': `Bearer ${accessToken}`,
-        'Content-Type': 'application/json',
-        ...options.headers
-    };
-    return fetch(url, { ...options, headers });
-}
 async function listCalendars(accessToken) {
     const url = `${CALENDAR_API_BASE}/users/me/calendarList`;
     const res = await apiFetch(url, accessToken);
@@ -79,13 +26,15 @@ async function listCalendars(accessToken) {
     const data = await res.json();
     return data.items || [];
 }
-async function listEvents(accessToken, calendarId = 'primary', maxResults = 10, timeMin) {
+async function listEvents(accessToken, calendarId = 'primary', maxResults = 10, timeMin, timeMax) {
     const params = new URLSearchParams({
         maxResults: maxResults.toString(),
         singleEvents: 'true',
         orderBy: 'startTime',
         timeMin: timeMin || new Date().toISOString()
     });
+    if (timeMax)
+        params.set('timeMax', timeMax);
     const url = `${CALENDAR_API_BASE}/calendars/${encodeURIComponent(calendarId)}/events?${params}`;
     const res = await apiFetch(url, accessToken);
     if (!res.ok) {
@@ -195,64 +144,117 @@ async function importIcsFile(filePath, accessToken, calendarId = 'primary') {
     }
     return result;
 }
-function showUsage() {
-    console.log(`
-gcal v${VERSION} - Google Calendar CLI
+const USAGE_SUMMARY = `gcal v${VERSION} - Google Calendar CLI
 
-Usage:
-  gcal <file.ics>                    Import ICS file (file association)
-  gcal <command> [options]           Run command
+Usage: gcal <file.ics>                Import ICS file (file association)
+       gcal <command> [options]       Run command
+       gcal help <command>            Detailed help for a command
 
 Commands:
-  list [n]                           List upcoming n events (default: 10)
-  list -since <date>                 List events from <date> forward (past ok)
-  add <title> <when> [duration]      Add event (explicit args)
-  add                                Add event (type description interactively)
-  add "free text description"        Add event (AI parses single text arg)
-  add -clip                          Add event from clipboard text (AI-parsed)
-  del|delete <id> [id2...]           Delete event(s) by ID (prefix match)
-  remind <id> <dur> [dur2...]        Add reminder(s) to existing event
-  resched <id> <when> [duration]     Reschedule event (preserve duration by default)
-  snooze <id> [when]                 Snooze event (default: +1 day)
-  import <file.ics>                  Import events from ICS file
-  calendars                          List available calendars
-  assoc                              Set up .ics file association (Windows)
-  help                               Show this help
+  list                          List upcoming events
+  add                           Add event (explicit, AI, or interactive)
+  del | delete                  Delete event(s) by ID
+  remind                        Add reminder(s) to existing event
+  resched                       Reschedule event
+  snooze                        Snooze event (default: +1d)
+  import                        Import events from ICS file
+  calendars                     List available calendars
+  assoc                         Set up .ics file association (Windows)
+  help [command]                Show help
+
+Global options:
+  -u, -user <email>             Set / use default Google account
+  -c, -calendar <id>            Calendar ID (default: primary)
+
+Companion tool: gtask  (Google Tasks - shares OAuth with gcal)
+`;
+const USAGE = {
+    list: `gcal list [n] [-since <date>] [-till <date>] [-c <calendar>] [-b] [-v]
+  List upcoming events. Default n=10.
+  -since <date>   Start from date (past dates allowed)
+  -till <date>    End at date
+  -b              Include birthday events (hidden by default)
+  -v              Verbose (show full IDs and links)
+
+  Examples:
+    gcal list
+    gcal list 20
+    gcal list -since "10 days ago"
+    gcal list -since "april 1" -till "may 1"
+    gcal list -since "april 1" -n 50
+`,
+    add: `gcal add <title> <when> [duration]      Explicit
+       gcal add "<free text>"                  AI-parsed single arg
+       gcal add -clip                          AI-parsed from clipboard
+       gcal add                                Interactive (type description)
+  Add a calendar event. Default duration 1h. Use -r <dur> to add reminder(s).
+
+  Examples:
+    gcal add "Dentist" "Friday 3pm" "1h"
+    gcal add "Lunch" "1/14/2026 12:00" "1h"
+    gcal add "Meeting" "tomorrow 10:00"
+    gcal add "Appointment" "jan 15 2pm"
+    gcal add "Dentist appointment Friday 3pm for 1 hour"
+    gcal add -clip
+    gcal add "Dentist" "Friday 3pm" -r 30m
+`,
+    del: `gcal del <id> [id2...] [-all] [-b]
+       gcal delete <id> [id2...]
+  Delete event(s) by ID prefix.
+  -all            Delete entire recurring series (not just instance)
+  -b              Allow deletion of birthday events
+`,
+    delete: `gcal delete <id> [id2...] [-all]
+  Alias for "del".
+`,
+    remind: `gcal remind <id> <duration> [duration2...]
+  Add popup reminder(s) to an existing event.
 
-Options:
-  -u, -user <email>        Set default Google account
-  -c, -calendar <id>       Calendar ID (default: primary)
-  -n <count>               Number of events to list
-  -v, -verbose             Show event IDs and links
-  -b, -birthdays           Include birthday events (hidden by default)
-  -clip                    Read from clipboard (for add command)
-  -r, -reminder <dur>      Add popup reminder (e.g., 30m, 1h); repeatable
-  -since <date>            Start listing from <date> (e.g. "10 days ago", "April 1")
-  -all                     Delete all instances of recurring event
+  Examples:
+    gcal remind abc12345 30m
+    gcal remind abc12345 30m 1h
+`,
+    resched: `gcal resched <id> <when> [duration]
+  Reschedule an event. Preserves duration unless [duration] given.
+  If <when> lacks a time-of-day, the original time is preserved.
+  All-day events stay all-day. Searches up to 30 days back by default
+  (widen with -since).
 
-Examples:
-  gcal meeting.ics                        Import ICS file
-  gcal list                               List next 10 events
-  gcal list -since "10 days ago"          List events from 10 days ago forward
-  gcal list -since "april 1" -n 50        List 50 events since April 1
-  gcal add "Dentist" "Friday 3pm" "1h"
-  gcal add "Lunch" "1/14/2026 12:00" "1h"
-  gcal add "Meeting" "tomorrow 10:00"
-  gcal add "Appointment" "jan 15 2pm"
-  gcal add "Dentist appointment Friday 3pm for 1 hour"
-  gcal add -clip                          Add from clipboard text
-  gcal add "Dentist" "Friday 3pm" -r 30m  Add with 30-min reminder
-  gcal remind abc12345 30m                Add 30-min reminder to event
-  gcal resched abc12345 "next friday 3pm" Reschedule to new date/time
-  gcal resched abc12345 tomorrow          Move to tomorrow (preserve time-of-day)
-  gcal snooze abc12345                    Snooze event +1 day
-  gcal snooze abc12345 +1w                Snooze event +1 week
-  gcal add                                Type event description (one or multiple)
-  gcal -u bob@gmail.com                   Set default user
+  Examples:
+    gcal resched abc12345 "next friday 3pm"
+    gcal resched abc12345 tomorrow
+    gcal resched abc12345 +1w
+`,
+    snooze: `gcal snooze <id> [when]
+  Like resched, but defaults to +1d if no <when> given.
 
-File Association (Windows):
-  gcal assoc                              Set up automatically
-`);
+  Examples:
+    gcal snooze abc12345
+    gcal snooze abc12345 +1w
+`,
+    import: `gcal import <file.ics>
+       gcal <file.ics>                          (via file association)
+  Import events from an iCalendar file.
+`,
+    calendars: `gcal calendars
+  List available calendars (id, name, access role).
+`,
+    assoc: `gcal assoc
+  Set up Windows .ics file association so double-clicking imports to gcal.
+`,
+    help: `gcal help [command]
+  Show summary, or detailed help for a single command.
+`
+};
+function showUsage(cmd) {
+    if (cmd && USAGE[cmd]) {
+        console.log(USAGE[cmd]);
+        return;
+    }
+    if (cmd) {
+        console.error(`Unknown command: ${cmd}\n`);
+    }
+    console.log(USAGE_SUMMARY);
 }
 function parseArgs(argv) {
     const result = {
@@ -267,7 +269,8 @@ function parseArgs(argv) {
         birthdays: false,
         clip: false,
         all: false,
-        reminders: []
+        reminders: [],
+        helpCmd: ''
     };
     const unknown = [];
     let i = 0;
@@ -325,10 +328,21 @@ function parseArgs(argv) {
                 }
                 break;
             }
+            case '-till':
+            case '--till': {
+                const val = argv[++i] || '';
+                try {
+                    result.till = parseDateTime(val);
+                }
+                catch {
+                    console.error(`Invalid -till value: ${val}`);
+                    process.exit(1);
+                }
+                break;
+            }
             case '-h':
             case '-help':
             case '--help':
-            case 'help':
                 result.help = true;
                 break;
             case '-V':
@@ -360,6 +374,10 @@ function parseArgs(argv) {
         console.error(`Unknown options: ${unknown.join(', ')}`);
         process.exit(1);
     }
+    if (result.command === 'help') {
+        result.help = true;
+        result.helpCmd = result.args[0] || '';
+    }
     return result;
 }
 function buildReminders(minutes) {
@@ -426,8 +444,8 @@ async function main() {
         }
     }
     if (parsed.help) {
-        showUsage();
-        if (process.platform === 'win32' && !checkIcsAssoc()) {
+        showUsage(parsed.helpCmd);
+        if (!parsed.helpCmd && process.platform === 'win32' && !checkIcsAssoc()) {
             console.log('Note: .ics file association not set. Run "gcal assoc" to set it up.');
         }
         process.exit(0);
@@ -477,7 +495,6 @@ async function main() {
         console.error('No user configured. Use -u <email> to set default user.');
         process.exit(1);
     }
-    console.log(`${ts()} User: ${user}`);
     switch (parsed.command) {
         case 'import': {
             const filePath = parsed.icsFile || parsed.args[0];
@@ -501,10 +518,19 @@ async function main() {
             break;
         }
         case 'list': {
-            const count = parsed.args[0] ? parseInt(parsed.args[0]) : parsed.count;
+            let count = parsed.count;
+            if (parsed.args.length > 0) {
+                if (parsed.args.length > 1 || !/^\d+$/.test(parsed.args[0])) {
+                    console.error(`Invalid list arguments: ${parsed.args.join(' ')}`);
+                    console.error('Usage: gcal list [n] [-since <date>] [-till <date>]');
+                    process.exit(1);
+                }
+                count = parseInt(parsed.args[0], 10);
+            }
             const token = await getAccessToken(user, false);
             const timeMin = parsed.since ? parsed.since.toISOString() : undefined;
-            let events = await listEvents(token, parsed.calendar, count, timeMin);
+            const timeMax = parsed.till ? parsed.till.toISOString() : undefined;
+            let events = await listEvents(token, parsed.calendar, count, timeMin, timeMax);
             const birthdayCount = events.filter(e => e.eventType === 'birthday').length;
             if (!parsed.birthdays) {
                 events = events.filter(e => e.eventType !== 'birthday');
@@ -537,14 +563,12 @@ async function main() {
                     ? ['ID', 'When', 'Dur', 'Event', 'Location', 'Link']
                     : ['ID', 'When', 'Dur', 'Event', 'Location'];
                 const colWidths = headers.map((h, i) => Math.max(h.length, ...rows.map(r => (r[i] || '').length)));
-                // Print header
-                const headerLine = headers.map((h, i) => h.padEnd(colWidths[i])).join('  ');
-                console.log(headerLine);
+                const lastIdx = headers.length - 1;
+                const padCell = (s, i) => i === lastIdx ? s : s.padEnd(colWidths[i]);
+                console.log(headers.map(padCell).join('  '));
                 console.log(colWidths.map(w => '-'.repeat(w)).join('  '));
-                // Print rows
                 for (const row of rows) {
-                    const line = row.map((cell, i) => (cell || '').padEnd(colWidths[i])).join('  ');
-                    console.log(line);
+                    console.log(row.map((cell, i) => padCell(cell || '', i)).join('  '));
                 }
             }
             if (birthdayCount > 0 && !parsed.birthdays) {