Add Nextcloud integration tools

- CLI tools: nextcloud-client, nextcloud-contacts, nextcloud-calendar, nextcloud-mail - Build script with compile-time credentials - Skills for all four tools - Email tool supports IMAP/SMTP with attachment download
2026-02-20 17:24:13 +00:00
parent 8d932b1c15
commit 705f41a872
20 changed files with 5043 additions and 2 deletions
--- a/skills/nextcloud-calendar/SKILL.md
+++ b/skills/nextcloud-calendar/SKILL.md
@@ -0,0 +1,303 @@
+# Nextcloud Calendar Skill
+
+**Purpose:** Manage calendars and events on Nextcloud servers using the nextcloud-calendar CLI tool.
+
+## Overview
+
+This skill provides calendar operations for Nextcloud using the nextcloud-calendar Go binary. The CLI tool handles all CalDAV operations and iCalendar parsing.
+
+## Prerequisites
+
+- Go compiler (for building the CLI tool)
+- Nextcloud server URL
+- Nextcloud username
+- Nextcloud password (for app token retrieval)
+- Calendar app enabled on Nextcloud
+
+## Bootstrap Process
+
+**This skill will automatically build all three Nextcloud CLI tools with your app token and then immediately forget all credentials.**
+
+**Step 1: The skill will ask for:**
+- Nextcloud server URL (e.g., https://teamworkapps.com)
+- Nextcloud username (e.g., wltbagent@shortcutsolutions.net)
+- Nextcloud password (your normal login credentials, not app token)
+
+**Step 2: The skill will:**
+1. **Authenticate to Nextcloud** using your username and password
+2. **Retrieve or generate an app token** from Nextcloud settings
+3. **Build** all three CLI tools (files, contacts, calendar) with the app token
+4. **Verify** that all three binaries were created
+5. **Immediately forget** all credentials (never stored permanently)
+
+**Step 3: You're ready!**
+- Use any tool without passing credentials (app token is embedded at compile time)
+- Example: `nextcloud-list-calendars` (no --url, --user, --token needed)
+- Example: `nextcloud-create-event --summary "Meeting" --start "2026-02-12T10:00:00Z" --end "2026-02-12T11:00:00Z"`
+
+**Security Note:**
+- **All credentials** (username, password, and app token) are only used during the bootstrap process
+- **App token is retrieved automatically** - you don't need to find it manually
+- **Credentials are never stored permanently** - not in any file or environment variable
+- **The app token is embedded** in the compiled binaries, which stay on your local system only
+- **Do not distribute** built binaries outside your trusted environment
+
+**Flow:** Normal credentials → Authenticate → Get App Token → Build All CLI Tools → Forget All Credentials → Ready to Use
+
+## Configuration
+
+All credentials are embedded at compile time via Go ldflags. No runtime configuration needed.
+
+### Build-Time Configuration (Automatic)
+
+The skill handles this automatically during bootstrap:
+```bash
+cd projects/nextcloud-integration/tools/go/nextcloud-calendar
+
+go build -ldflags="-X 'main.BuildServerURL=https://teamworkapps.com' \
+                 -X 'main.BuildUsername=wltbagent@shortcutsolutions.net' \
+                 -X 'main.BuildToken=YOUR_APP_TOKEN'" \
+  -o ~/bin/nextcloud-calendar .
+```
+
+### Runtime Configuration (Fallback)
+
+If not set at build time, the tool will check these environment variables:
+
+```bash
+export NEXTCLOUD_URL="https://cloud.example.com"
+export NEXTCLOUD_USER="your-username"
+export NEXTCLOUD_TOKEN="your-app-token"
+```
+
+### Command-Line Flags (Override)
+
+Pass credentials directly to each command using:
+- `--url`
+- `--user`
+- `--token`
+
+**Priority:** Build-time ldflags > Environment variables > Command-line flags
+
+## Tool Reference
+
+All tools can be used without passing credentials (they're embedded at compile time).
+
+### `nextcloud-list-calendars` - List all calendars
+
+```bash
+# List all calendars
+nextcloud-list-calendars
+```
+
+**Output:**
+```
+Calendars:
+----------
+Name: Personal
+Path: personal
+ETag: 
+```
+
+### `nextcloud-list-events` - List events in a calendar
+
+```bash
+# List events in default calendar
+nextcloud-list-events
+
+# List events in specific calendar
+nextcloud-list-events --calendar "work"
+```
+
+**Output:**
+```
+Events in 'personal' calendar:
+-----------------
+UID: 1770849610657274975
+ETag: "18a633c6ae1ef474c2910a3bf9c12309"
+```
+
+### `nextcloud-get-event` - Retrieve a specific event
+
+```bash
+# Get event by UID
+nextcloud-get-event --uid "1770849610657274975"
+```
+
+**Output:**
+```
+Event: 1770849610657274975
+--------
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//WLTBAgent//NextCalendar//EN
+BEGIN:VEVENT
+UID:1770849610657274975
+DTSTAMP:20260211T221247Z
+DTSTART:20260212T090000Z
+DTEND:20260212T100000Z
+SUMMARY:Meeting with Team
+END:VEVENT
+END:VCALENDAR
+```
+
+### `nextcloud-create-event` - Create a new event
+
+```bash
+# Create event with summary and times (RFC3339 format)
+nextcloud-create-event \
+  --summary "Team Meeting" \
+  --start "2026-02-12T10:00:00Z" \
+  --end "2026-02-12T11:00:00Z"
+
+# Create event from iCalendar file
+nextcloud-create-event --ical /path/to/event.ics
+```
+
+**Time Format:** RFC3339 (UTC recommended)
+- `2026-02-12T10:00:00Z` - UTC with Z suffix
+- `2026-02-12T10:00:00-07:00` - With timezone offset
+
+**Output:**
+```
+Event created successfully
+```
+
+### `nextcloud-delete-event` - Delete an event
+
+```bash
+# Delete event by UID
+nextcloud-delete-event --uid "1770849610657274975"
+```
+
+**Output:**
+```
+Event deleted: 1770849610657274975
+```
+
+## Use Cases
+
+### 1. Event Management Workflow
+
+```bash
+# Create a new event
+nextcloud-create-event \
+  --summary "Project Review" \
+  --start "2026-02-12T14:00:00Z" \
+  --end "2026-02-12T15:00:00Z"
+
+# Verify event was created
+nextcloud-list-events | grep "Project"
+
+# Retrieve event details
+nextcloud-get-event --uid "$(nextcloud-list-events | grep 'Project' | awk '{print $2}')"
+```
+
+### 2. Meeting Scheduling
+
+```bash
+# Schedule meeting
+nextcloud-create-event \
+  --summary "Weekly Team Standup" \
+  --start "2026-02-12T09:00:00Z" \
+  --end "2026-02-12T09:30:00Z"
+
+# (Note: Recurring events require full iCalendar RRULE support - not yet implemented)
+```
+
+### 3. Event Search Workflow
+
+```bash
+# List all events
+nextcloud-list-events
+
+# Get detailed event info
+nextcloud-get-event --uid "event-uid"
+
+# Search by summary (parsing get-event output)
+nextcloud-get-event --uid "uid" | grep "SUMMARY"
+```
+
+### 4. Event Cleanup
+
+```bash
+# List all events
+nextcloud-list-events
+
+# Delete specific event
+nextcloud-delete-event --uid "old-event-uid"
+
+# Verify deletion
+nextcloud-list-events
+```
+
+### 5. Bulk Event Import
+
+```bash
+# Import events from iCalendar files
+for icsfile in events/*.ics; do
+  nextcloud-create-event --ical "$icsfile"
+done
+```
+
+## iCalendar Format
+
+The CLI tool generates iCalendar 2.0 format events:
+
+```ics
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//WLTBAgent//NextCalendar//EN
+BEGIN:VEVENT
+UID:<timestamp-nanoseconds>
+DTSTAMP:<creation-time>
+DTSTART:<start-time>
+DTEND:<end-time>
+SUMMARY:<event-summary>
+END:VEVENT
+END:VCALENDAR
+```
+
+**Time Formats:**
+- `DTSTAMP`: Creation time (UTC)
+- `DTSTART`: Event start time (UTC)
+- `DTEND`: Event end time (UTC)
+- Format: `YYYYMMDDTHHmmssZ` (RFC3339 compatible)
+
+## Error Handling
+
+The nextcloud-calendar binary provides clear error messages:
+
+| Error | Meaning | Action |
+|-------|---------|--------|
+| Error: credentials not set at build time | Need to re-bootstrap | Re-run bootstrap process |
+| Error: --uid is required for get-event operation | Missing UID | Provide event UID |
+| Error: event summary is required | Missing summary | Provide --summary flag |
+| Error parsing start time: xxx | Invalid time format | Use RFC3339 format (YYYY-MM-DDTHH:MM:SSZ) |
+| unexpected status: 404 | Event not found | Verify UID and calendar |
+| unexpected status: 401 | Unauthorized | Re-bootstrap (token expired) |
+| get event failed with status: xxx | Read error | Check event exists |
+
+## Best Practices
+
+1. **Use RFC3339 time format** for start/end times (UTC with Z suffix)
+2. **Store UIDs** when creating events for later retrieval
+3. **Verify operations** by listing after create/delete
+4. **Use UTC times** to avoid timezone confusion
+5. **Handle iCalendar format** when importing from files
+6. **No runtime configuration** - credentials are embedded at compile time
+
+## Dependencies
+
+- `~/bin/nextcloud-calendar` - Go binary for CalDAV operations
+- No external XML parsing needed (handled by Go)
+- iCalendar files use standard RFC 5545 format
+
+## Related Skills
+
+- **nextcloud-contacts** - For linking contacts to events
+- **nextcloud-files** - For storing event attachments
+
+---
+
+*OpenClaw skill wrapper for nextcloud-calendar Go binary with automatic app token retrieval*