dsh-calendar

A calendar / scheduling integration bundle for DeepSeek Harness (dsh), built as a self-contained npm package that follows the dsh bundle convention ("dsh": { "bundle": { "patch": "./cordis.patch.yml" } }).

It connects to any CalDAV server (Google Calendar, iCloud, Nextcloud, custom), stores and computes iCalendar/RRULE data itself, understands Chinese calendar context (lunar calendar, holidays, Asia/Shanghai by default), and detects time conflicts — all without a single runtime dependency.

---

Features

1. CalDAV integration — list / create / update / delete / search events over standard REPORT/PROPFIND/GET/PUT/DELETE, with automatic discovery (well-known → current-user-principal → calendar-home-set → calendars). Two authentication channels:

   • Basic auth (Nextcloud, iCloud, generic servers)
   • Google OAuth2 via the device flow (headless-friendly), with a refresh-token flow and secure token storage
   • Credentials come from environment variables or the dsh credential service (ctx.credentials) or a local chmod-0600 store. Secrets are never written to logs — a redact() helper masks them in output.

2. RRULE expansion + single-instance editing — a from-scratch RFC 5545 recurrence engine covering FREQ (SECONDLY…YEARLY), INTERVAL, COUNT, UNTIL (UTC & local), BYDAY (with ordinals), BYMONTH, BYMONTHDAY, BYYEARDAY, BYWEEKNO, BYSETPOS, WKST, BYHOUR/BYMINUTE/BYSECOND, plus EXDATE and RDATE. Editing or deleting one occurrence writes a RECURRENCE-ID override (STATUS:CANCELLED for deletion) and never touches the series master.

3. Chinese bias — lunar calendar conversion (astronomically computed, full 2000–2100 coverage), Chinese holidays (春节 / 清明 / 端午 / 中秋 / 元宵 / 七夕 / 重阳 / 除夕 / 元旦 / 劳动节 / 国庆节), 干支/生肖 anchored at 立春, Asia/Shanghai default timezone, and a cal_remind tool whose output plugs straight into dsh's session-local schedule_create.

4. Conflict detection — overlapping events (timed, all-day, and across recurring instances) are flagged with the overlapping span; updates can exclude the event itself.

5. Timezone handling — an embedded, dependency-free timezone engine (present-day rules, 2000–2100) with correct DST transitions; wall-time ↔ UTC conversion with documented ambiguity/gap resolution; TZID-preserving ICS round-trips.

6. Toolchain — dsh tools under ctx.tools (cal_list, cal_get, cal_create, cal_update, cal_delete, cal_search, cal_conflicts, cal_holidays, plus cal_calendars, cal_remind) and a standalone CLI (dsh-calendar).

---

Bundle layout

| file | purpose | |---|---| | package.json | npm manifest with dsh.bundle.patch + peer deps | | cordis.patch.yml | config layer mounting the bundle entry | | src/index.ts | dsh plugin entry: name / inject / Config / apply | | src/service.ts | high-level operations shared by tools & CLI | | src/tools.ts | cal_* tool definitions | | src/credentials.ts | secret resolution + redaction | | src/dav/* | CalDAV client, OAuth2 (Google device flow), XML, store | | src/core/* | timezone, iCalendar, RRULE, recurrence, conflicts, lunar |

No runtime dependencies — peerDependencies (@deepseek-ai/cordis, @deepseek-ai/dsh-tools, @deepseek-ai/schemastery) are only used by the entry module and are provided by the dsh runtime.

---

Install & connect to dsh

Prerequisite: a working dsh profile. Then:

# 1. build the bundle (produces lib/)
npm install
npm run build

# 2. install it into your dsh profile
dsh plugin --profile <name> add ./calendar

This pnpm-links the checkout, appends the bundle to the profile, and dsh then mounts the entry module via cordis.patch.yml (id: calendar, name: dsh-calendar), registering the cal_* tools.

To iterate without installing, layer the patch directly:

dsh --profile <name> --patch ./cordis.patch.yml

(When installed by git/pack instead of a local checkout, run npm run build first — the manifest ships built lib/, not sources.)

Configuration

Configuration goes through the bundle's Config schema (set in the patch / profile overlay):

- insert:
    - id: calendar
      name: dsh-calendar
      config:
        defaultTimezone: Asia/Shanghai
        serverUrl: https://nextcloud.example.com/remote.php/dav/
        # or calendarUrl: https://nextcloud.example.com/remote.php/dav/calendars/me/personal/
        authMode: basic   # basic | google

or via environment variables / the dsh credential service (see below).

Credentials (never logged)

| secret | meaning | |---|---| | CALDAV_URL | full calendar collection URL (Basic) | | CALDAV_USERNAME / CALDAV_PASSWORD | Basic credentials | | GOOGLE_CLIENT_ID | Google OAuth client id | | GOOGLE_CALDAV_REFRESH_TOKEN | long-lived refresh token (see below) |

Set them in the environment, or store them in the dsh credential service (credentialRef names match the table above, e.g. credentialRef('CALDAV_PASSWORD')), or, for the CLI, in the local .calendar-credentials.json (mode 0600). The resolver checks environment → dsh credential service → local store.

Google OAuth (device flow)

dsh-calendar auth google --device --client-id <CLIENT_ID>

opens a URL to authorize; the refresh token is saved to the secure store. The server-side client refreshes the access token automatically when near expiry.

---

Tools (ctx.tools)

| tool | description | |---|---| | cal_list | events in a window (with wall/UTC times) | | cal_get | one series + its concrete occurrences | | cal_create | create (RRULE/EXDATE/RDATE/all-day) + conflict check | | cal_update | update whole series, or one occurrence via recurrenceId | | cal_delete | delete series, or one occurrence (→ CANCELLED override) | | cal_search | text search over titles/descriptions/locations | | cal_conflicts | check a proposed time (incl. recurring) for overlaps | | cal_holidays | upcoming Chinese holidays + today's 干支/生肖 | | cal_calendars | list accessible calendars | | cal_remind | reminder plan, formatted for dsh schedule_create |

Reminder linkage: dsh's schedule surface is deliberately model-facing (schedule_create / schedule_list / schedule_delete). cal_remind expands the event and returns { at: { date, time, time_zone }, prompt } per occurrence — pass those directly to schedule_create to register session-local reminders in the calendar's timezone.

---

CLI

dsh-calendar list  [--start "2026-01-01" --end "2026-01-31" --tz Asia/Shanghai]
dsh-calendar get      <uid>
dsh-calendar create   --summary "Team sync" --start "2026-03-02 10:00" --end "2026-03-02 11:00" \
                      --rrule "FREQ=WEEKLY;COUNT=4"
dsh-calendar update   <uid> --summary "Renamed" --recurrence-id "2026-03-09 10:00" --start "2026-03-09 15:00"
dsh-calendar delete   <uid> [--recurrence-id "2026-03-09 10:00"]
dsh-calendar search   "meeting"
dsh-calendar conflicts --start "2026-06-01 14:00" --end "2026-06-01 15:00"
dsh-calendar holidays --days 60
dsh-calendar calendars
dsh-calendar remind   <uid> --before 30m
dsh-calendar auth google --device
dsh-calendar auth status

A .env file in the working directory is loaded (if present) before credentials are resolved.

---

Timezone model

The engine embeds present-day IANA-style rules for common zones (Shanghai, Tokyo, Seoul, London, Paris, Berlin, New York, Chicago, Los Angeles, Sydney, Auckland, …). Conversions are:

• wall (TZID) ↔ UTC with deterministic DST handling:
  • a fold (autumn, wall time occurs twice) picks the first occurrence (the larger offset);
  • a gap (spring, wall time does not exist) is shifted forward across the gap.
• All-day dates are stored as dates and interpreted at midnight in the event / default timezone.
• RRULE instances are expanded on the DTSTART's wall-clock representation, so a weekly 09:00 meeting stays at 09:00 on both sides of a DST transition.

Lunar calendar

Computed from astronomical principles (Meeus truncated new-moon & solar-longitude series) rather than a hard-coded table, so the whole 2000–2100 range is covered by construction, including leap months (闰月) and the famously unusual 2033 闰十一月. The test suite pins 春节 dates across 2000–2100, known leap months (2001–2033), and holiday dates (端午/中秋/清明).

---

Development

npm install
npm test             # vitest: 185 tests (rrule vectors, DST, lunar, conflicts, CalDAV mock)
npm run typecheck
npm run build        # compile to lib/

Tests run against an in-process mock CalDAV server (test/helpers/mockCaldav.ts) and RFC 5545 example vectors — no network access needed.

---

License

MIT — see LICENSE.