@cayde-6/icalendar 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cayde-6
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,245 @@
+# icalendar
+
+[![CI](https://github.com/cayde-6/icalendar/actions/workflows/ci.yml/badge.svg)](https://github.com/cayde-6/icalendar/actions/workflows/ci.yml)
+[![Release](https://github.com/cayde-6/icalendar/actions/workflows/release.yml/badge.svg)](https://github.com/cayde-6/icalendar/actions/workflows/release.yml)
+[![Coverage](https://codecov.io/gh/cayde-6/icalendar/branch/main/graph/badge.svg)](https://codecov.io/gh/cayde-6/icalendar)
+
+![icalendar hero](./assets/hero.png)
+
+Production-ready TypeScript CLI for **CalDAV calendars**, **iCalendar events**, and **agent-friendly automation**.
+
+`icalendar` gives agents and scripts a thin, reliable interface for:
+- listing calendars
+- listing events
+- creating events
+- updating events
+- deleting events
+- sending attendee invites through CalDAV/iCalendar
+- setting a friendly organizer display name (for example `Bender`)
+
+It was validated live against **real iCloud CalDAV** with create → update → invite → delete flows.
+
+## Why this exists
+
+Most CalDAV tooling is either too low-level for agents or too UI-centric for automation. This repo wraps the ugly parts behind a small CLI and a layered codebase that is easy to embed, extend, and reason about.
+
+## Features
+
+- ESM TypeScript CLI with clean layering
+- CalDAV access via `tsdav`
+- invite-ready ICS generation
+- attendee support for create/update flows
+- configurable organizer common name via env
+- text and JSON output modes
+- runtime-safe handling of `--help` / `--version`
+- live-tested against iCloud CalDAV
+
+## Install
+
+### From npm
+
+```bash
+npm install -g @cayde-6/icalendar
+icalendar --help
+```
+
+### From source
+
+```bash
+git clone https://github.com/cayde-6/icalendar.git
+cd icalendar
+npm install
+npm run build
+```
+
+### Use as a local CLI
+
+```bash
+npm link
+icalendar --help
+```
+
+### Use without linking
+
+```bash
+node --import tsx src/cli.ts --help
+node dist/cli.js calendars list
+```
+
+## Configuration
+
+Copy the example file:
+
+```bash
+cp .env.example .env
+```
+
+Required configuration:
+
+```env
+CALDAV_SERVER_URL=https://caldav.icloud.com/
+CALDAV_USERNAME=primary.attendee@example.test
+CALDAV_PASSWORD=app-specific-password
+```
+
+Optional configuration:
+
+```env
+CALDAV_CALENDAR_NAME=OpenClaw Test
+CALDAV_ORGANIZER_NAME=Bender
+CALDAV_RANGE_START=2026-05-07T00:00:00+02:00
+CALDAV_RANGE_END=2026-05-08T00:00:00+02:00
+CALDAV_EXPAND_RECURRING=true
+```
+
+### iCloud setup: generate an app-specific password
+
+For iCloud CalDAV you need an **app-specific password**. Your normal Apple ID password will not work.
+
+How to generate it:
+
+1. Go to your Apple account settings: <https://account.apple.com/>
+2. Sign in with the Apple account that owns the iCloud calendar
+3. Open the **Sign-In and Security** section
+4. Find **App-Specific Passwords**
+5. Create a new password, for example named `icalendar`
+6. Copy the generated password and put it into:
+
+```env
+CALDAV_PASSWORD=your-app-specific-password
+```
+
+Recommended iCloud values:
+
+```env
+CALDAV_SERVER_URL=https://caldav.icloud.com/
+CALDAV_USERNAME=your-apple-id-email@example.com
+CALDAV_PASSWORD=your-app-specific-password
+```
+
+If authentication fails, the most common cause is using the normal Apple ID password instead of the generated app-specific one.
+
+## Quick examples
+
+### List calendars
+
+```bash
+icalendar calendars list
+icalendar calendars list --json
+```
+
+### List events
+
+```bash
+icalendar events list
+icalendar events list --json
+```
+
+### Create an event
+
+```bash
+icalendar events create \
+  --summary "Family sync" \
+  --start "2026-05-07T18:00:00+02:00" \
+  --end "2026-05-07T18:30:00+02:00" \
+  --description "Agenda review" \
+  --location "Belgrade" \
+  --attendees "primary.attendee@example.test,secondary.attendee@example.test"
+```
+
+### Update an event
+
+```bash
+icalendar events update \
+  --url "https://caldav.example.com/calendars/personal/event.ics" \
+  --summary "Family sync" \
+  --start "2026-05-07T18:00:00+02:00" \
+  --end "2026-05-07T18:45:00+02:00" \
+  --attendees "primary.attendee@example.test,secondary.attendee@example.test"
+```
+
+### Delete an event
+
+```bash
+icalendar events delete "https://caldav.example.com/calendars/personal/event.ics"
+```
+
+## Agent integration
+
+If another agent/session wants to adopt this CLI, start here:
+- [Agent integration guide](./docs/agent-integration.md)
+- [Architecture](./docs/architecture.md)
+
+Short version:
+1. install dependencies
+2. provide `.env`
+3. run `npm run build`
+4. use `icalendar ...` or `node dist/cli.js ...`
+5. prefer `--json` for machine consumers
+
+## Development
+
+```bash
+npm run check
+npm run build
+npm test
+npm run test:coverage
+npm run verify
+```
+
+## Test strategy
+
+Current coverage includes:
+- calendar selection rules
+- time range defaults
+- command parsing for create/update/delete
+- text/json runtime output
+- env config parsing
+- ICS generation and ICS parsing
+- runtime error rendering
+
+## Architecture
+
+`icalendar` follows the same layered structure as `threads-cli`:
+
+```text
+cli -> app(commands/use-cases) -> domain -> infra -> presentation -> shared
+```
+
+The CalDAV SDK stays in `infra/`, use-cases orchestrate, domain stays provider-agnostic, and renderers only format output.
+
+## Production-readiness notes
+
+- invite flows were smoke-tested live against iCloud CalDAV
+- `--help` and `--version` do not require env credentials
+- organizer display name is configurable with `CALDAV_ORGANIZER_NAME`
+- attendee invites work in both create and update flows
+- CLI defaults to the first calendar when `CALDAV_CALENDAR_NAME` is omitted
+
+## Repo docs
+
+- [Agent integration guide](./docs/agent-integration.md)
+- [Architecture](./docs/architecture.md)
+- [Release checklist](./docs/release-checklist.md)
+- [Versioning policy](./docs/versioning.md)
+- [Changelog](./CHANGELOG.md)
+- GitHub Actions: `.github/workflows/ci.yml`, `.github/workflows/release.yml`, `.github/workflows/smoke-icloud.yml`
+
+## License
+
+MIT
+
+## Live smoke workflow
+
+A dedicated GitHub Actions workflow is included for optional live CalDAV validation through repository secrets.
+
+Required secrets:
+- `CALDAV_SERVER_URL`
+- `CALDAV_USERNAME`
+- `CALDAV_PASSWORD`
+
+Optional secrets:
+- `CALDAV_CALENDAR_NAME`
+- `CALDAV_ORGANIZER_NAME`
+
+The workflow creates a temporary event, updates it, and deletes it in the end.

package/dist/chunk-MSLA47CB.js

@@ -0,0 +1,500 @@
+// src/cli.ts
+import { cac } from "cac";
+
+// src/infra/config/env-config.reader.ts
+import "dotenv/config";
+import { z } from "zod";
+var envSchema = z.object({
+  CALDAV_SERVER_URL: z.string().url(),
+  CALDAV_USERNAME: z.string().min(1),
+  CALDAV_PASSWORD: z.string().min(1),
+  CALDAV_CALENDAR_NAME: z.string().min(1).optional(),
+  CALDAV_RANGE_START: z.string().datetime({ offset: true }).optional(),
+  CALDAV_RANGE_END: z.string().datetime({ offset: true }).optional(),
+  CALDAV_EXPAND_RECURRING: z.enum(["true", "false"]).optional().transform((value) => value === "true"),
+  CALDAV_ORGANIZER_NAME: z.string().min(1).optional()
+});
+var EnvConfigReader = class {
+  readRuntimeConfig() {
+    const env = envSchema.parse(process.env);
+    return {
+      serverUrl: env.CALDAV_SERVER_URL,
+      username: env.CALDAV_USERNAME,
+      password: env.CALDAV_PASSWORD,
+      calendarName: env.CALDAV_CALENDAR_NAME,
+      rangeStart: env.CALDAV_RANGE_START,
+      rangeEnd: env.CALDAV_RANGE_END,
+      expandRecurring: env.CALDAV_EXPAND_RECURRING,
+      organizerName: env.CALDAV_ORGANIZER_NAME
+    };
+  }
+};
+
+// src/infra/parsing/ics-parser.ts
+var unfoldIcsLines = (ics) => {
+  return ics.replace(/\r\n[ \t]/g, "").split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+};
+var readIcsField = (ics, fieldName) => {
+  const lines = unfoldIcsLines(ics);
+  const line = lines.find((entry) => entry.startsWith(`${fieldName}:`) || entry.startsWith(`${fieldName};`));
+  if (!line) return void 0;
+  const separatorIndex = line.indexOf(":");
+  return separatorIndex === -1 ? void 0 : line.slice(separatorIndex + 1).trim();
+};
+var parseCalendarEvent = (raw, url) => {
+  const ics = typeof raw === "string" ? raw : "";
+  return {
+    summary: readIcsField(ics, "SUMMARY") ?? "Untitled event",
+    start: readIcsField(ics, "DTSTART"),
+    end: readIcsField(ics, "DTEND"),
+    description: readIcsField(ics, "DESCRIPTION"),
+    location: readIcsField(ics, "LOCATION"),
+    url
+  };
+};
+
+// src/infra/caldav/calendar-mapper.ts
+var toCalendar = (calendar) => ({
+  id: calendar.url,
+  displayName: String(calendar.displayName ?? "Untitled"),
+  url: calendar.url
+});
+var calendarDisplayName = (calendar) => calendar.displayName || "Untitled";
+
+// src/infra/caldav/client.ts
+import tsdav from "tsdav";
+var { createDAVClient } = tsdav;
+var createCaldavClient = async (config) => {
+  const client = await createDAVClient({
+    serverUrl: config.serverUrl,
+    credentials: {
+      username: config.username,
+      password: config.password
+    },
+    authMethod: "Basic",
+    defaultAccountType: "caldav"
+  });
+  return client;
+};
+
+// src/infra/caldav/event-object.service.ts
+import crypto2 from "crypto";
+
+// src/domain/events/ics.ts
+import crypto from "crypto";
+
+// src/shared/errors/cli-error.ts
+var CliError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+  }
+};
+
+// src/domain/events/ics.ts
+var escapeText = (value) => value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/,/g, "\\,").replace(/;/g, "\\;");
+var toUtcStamp = (value) => {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    throw new CliError("invalid_datetime", `Invalid datetime: ${value}`);
+  }
+  return date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+};
+var renderAttendee = (attendee) => {
+  const params = ["CUTYPE=INDIVIDUAL", "ROLE=REQ-PARTICIPANT", "PARTSTAT=NEEDS-ACTION", "RSVP=TRUE"];
+  if (attendee.commonName) params.unshift(`CN=${escapeText(attendee.commonName)}`);
+  return `ATTENDEE;${params.join(";")}:mailto:${attendee.email}`;
+};
+var renderOrganizer = (organizerEmail, organizerCommonName) => {
+  if (organizerCommonName) {
+    return `ORGANIZER;CN=${escapeText(organizerCommonName)}:mailto:${organizerEmail}`;
+  }
+  return `ORGANIZER:mailto:${organizerEmail}`;
+};
+var buildEventIcs = (draft, uid = crypto.randomUUID(), organizerEmail, organizerCommonName) => {
+  const now = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+  const lines = [
+    "BEGIN:VCALENDAR",
+    "VERSION:2.0",
+    "PRODID:-//cayde-6//icalendar//EN",
+    draft.attendees?.length ? "METHOD:REQUEST" : "METHOD:PUBLISH",
+    "BEGIN:VEVENT",
+    `UID:${uid}`,
+    `DTSTAMP:${now}`,
+    "SEQUENCE:0",
+    "STATUS:CONFIRMED",
+    `DTSTART:${toUtcStamp(draft.start)}`,
+    `DTEND:${toUtcStamp(draft.end)}`,
+    `SUMMARY:${escapeText(draft.summary)}`
+  ];
+  if (organizerEmail) lines.push(renderOrganizer(organizerEmail, organizerCommonName));
+  if (draft.description) lines.push(`DESCRIPTION:${escapeText(draft.description)}`);
+  if (draft.location) lines.push(`LOCATION:${escapeText(draft.location)}`);
+  for (const attendee of draft.attendees || []) lines.push(renderAttendee(attendee));
+  lines.push("END:VEVENT", "END:VCALENDAR");
+  return lines.join("\r\n") + "\r\n";
+};
+
+// src/infra/caldav/event-object.service.ts
+var EventObjectService = class {
+  constructor(client, options) {
+    this.client = client;
+    this.options = options;
+  }
+  client;
+  options;
+  async create(calendar, draft) {
+    const filename = `${crypto2.randomUUID()}.ics`;
+    const objectUrl = new URL(filename, calendar.url.endsWith("/") ? calendar.url : `${calendar.url}/`).toString();
+    const iCalString = buildEventIcs(draft, void 0, this.options.organizerEmail, this.options.organizerCommonName);
+    await this.client.createCalendarObject({
+      calendar: { url: calendar.url },
+      filename,
+      iCalString
+    });
+    return objectUrl;
+  }
+  async update(update) {
+    const iCalString = buildEventIcs(update, void 0, this.options.organizerEmail, this.options.organizerCommonName);
+    await this.client.updateCalendarObject({
+      calendarObject: { url: update.url, data: iCalString }
+    });
+  }
+  async delete(url) {
+    await this.client.deleteCalendarObject({ calendarObject: { url } });
+  }
+};
+
+// src/infra/caldav/tsdav-calendar.gateway.ts
+var TsdavCalendarGateway = class {
+  constructor(config) {
+    this.config = config;
+    this.clientPromise = createCaldavClient(config);
+  }
+  config;
+  clientPromise;
+  async listCalendars() {
+    const client = await this.clientPromise;
+    const calendars = await client.fetchCalendars();
+    return calendars.map(toCalendar);
+  }
+  async listEvents(input) {
+    const client = await this.clientPromise;
+    const calendars = await client.fetchCalendars();
+    const calendar = calendars.find((entry) => entry.url === input.calendar.url);
+    if (!calendar) return [];
+    const objects = await client.fetchCalendarObjects({
+      calendar,
+      timeRange: input.timeRange,
+      expand: input.expandRecurring
+    });
+    return objects.map((object) => parseCalendarEvent(object.data, object.url));
+  }
+  async createEvent(input) {
+    const client = await this.clientPromise;
+    const service = new EventObjectService(client, {
+      organizerEmail: this.config.username,
+      organizerCommonName: this.config.organizerName
+    });
+    const url = await service.create(input.calendar, input.draft);
+    return { ok: true, calendarName: calendarDisplayName(input.calendar), url };
+  }
+  async updateEvent(input) {
+    const client = await this.clientPromise;
+    const service = new EventObjectService(client, {
+      organizerEmail: this.config.username,
+      organizerCommonName: this.config.organizerName
+    });
+    await service.update(input.update);
+    return { ok: true, calendarName: calendarDisplayName(input.calendar), url: input.update.url };
+  }
+  async deleteEvent(input) {
+    const client = await this.clientPromise;
+    const service = new EventObjectService(client, {
+      organizerEmail: this.config.username,
+      organizerCommonName: this.config.organizerName
+    });
+    await service.delete(input.url);
+    return { ok: true, calendarName: calendarDisplayName(input.calendar), url: input.url };
+  }
+};
+
+// src/app/use-cases/calendars/list-calendars.ts
+var listCalendars = async (gateway) => {
+  const calendars = await gateway.listCalendars();
+  return { ok: true, calendars, count: calendars.length };
+};
+
+// src/app/commands/calendars/list.command.ts
+var runCalendarsListCommand = async (gateway) => {
+  return listCalendars(gateway);
+};
+
+// src/domain/shared/time-range.ts
+var toCalDavTime = (date) => {
+  return date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+};
+var addDays = (date, days) => {
+  const next = new Date(date);
+  next.setUTCDate(next.getUTCDate() + days);
+  return next;
+};
+var buildTimeRange = (start, end) => {
+  if (!start && !end) return void 0;
+  const startDate = start ? new Date(start) : /* @__PURE__ */ new Date();
+  const endDate = end ? new Date(end) : addDays(startDate, 30);
+  if (Number.isNaN(startDate.getTime()) || Number.isNaN(endDate.getTime())) {
+    throw new CliError("invalid_time_range", "Invalid CALDAV_RANGE_START/CALDAV_RANGE_END value");
+  }
+  if (startDate >= endDate) {
+    throw new CliError("invalid_time_range", "CALDAV_RANGE_START must be earlier than CALDAV_RANGE_END");
+  }
+  return {
+    start: toCalDavTime(startDate),
+    end: toCalDavTime(endDate)
+  };
+};
+
+// src/domain/calendars/calendar.ts
+var pickCalendar = (calendars, calendarName) => {
+  if (calendars.length === 0) return void 0;
+  if (!calendarName) return calendars[0];
+  const normalizedTarget = calendarName.trim().toLowerCase();
+  return calendars.find((calendar) => calendar.displayName.trim().toLowerCase() == normalizedTarget);
+};
+
+// src/app/use-cases/events/helpers.ts
+var resolveCalendar = async (calendars, calendarName) => {
+  const selectedCalendar = pickCalendar(calendars, calendarName);
+  if (!selectedCalendar) {
+    if (calendars.length === 0) {
+      throw new CliError("calendar_missing", "No calendars found");
+    }
+    throw new CliError("calendar_not_found", `Calendar not found: ${calendarName}`);
+  }
+  return selectedCalendar;
+};
+
+// src/app/use-cases/events/list-events.ts
+var listEvents = async (gateway, config) => {
+  const calendars = await gateway.listCalendars();
+  const selectedCalendar = await resolveCalendar(calendars, config.calendarName);
+  const timeRange = buildTimeRange(config.rangeStart, config.rangeEnd);
+  const events = await gateway.listEvents({
+    calendar: selectedCalendar,
+    timeRange,
+    expandRecurring: config.expandRecurring
+  });
+  return { ok: true, calendars, selectedCalendar, events, count: events.length, timeRange };
+};
+
+// src/app/commands/events/list.command.ts
+var runEventsListCommand = async (gateway, config) => {
+  return listEvents(gateway, config);
+};
+
+// src/app/use-cases/events/create-event.ts
+var createEvent = async (gateway, config, draft) => {
+  const calendars = await gateway.listCalendars();
+  const calendar = await resolveCalendar(calendars, config.calendarName);
+  return gateway.createEvent({ calendar, draft });
+};
+
+// src/app/commands/events/create.command.ts
+var getFlagValue = (args, name) => {
+  const index = args.indexOf(name);
+  if (index === -1) return void 0;
+  return args[index + 1]?.startsWith("--") ? void 0 : args[index + 1];
+};
+var parseAttendees = (value) => {
+  if (!value) return void 0;
+  const attendees = value.split(",").map((entry) => entry.trim()).filter(Boolean);
+  return attendees.length ? attendees.map((email) => ({ email })) : void 0;
+};
+var runEventsCreateCommand = async (gateway, config, args) => {
+  const summary = getFlagValue(args, "--summary");
+  const start = getFlagValue(args, "--start");
+  const end = getFlagValue(args, "--end");
+  const description = getFlagValue(args, "--description");
+  const location = getFlagValue(args, "--location");
+  const attendees = parseAttendees(getFlagValue(args, "--attendees"));
+  if (!summary || !start || !end) {
+    throw new CliError("missing_flags", "events create requires --summary, --start, and --end");
+  }
+  return createEvent(gateway, config, { summary, start, end, description, location, attendees });
+};
+
+// src/app/use-cases/events/update-event.ts
+var updateEvent = async (gateway, config, update) => {
+  const calendars = await gateway.listCalendars();
+  const calendar = await resolveCalendar(calendars, config.calendarName);
+  return gateway.updateEvent({ calendar, update });
+};
+
+// src/app/commands/events/update.command.ts
+var getFlagValue2 = (args, name) => {
+  const index = args.indexOf(name);
+  if (index === -1) return void 0;
+  return args[index + 1]?.startsWith("--") ? void 0 : args[index + 1];
+};
+var parseAttendees2 = (value) => {
+  if (!value) return void 0;
+  const attendees = value.split(",").map((entry) => entry.trim()).filter(Boolean);
+  return attendees.length ? attendees.map((email) => ({ email })) : void 0;
+};
+var runEventsUpdateCommand = async (gateway, config, args) => {
+  const url = getFlagValue2(args, "--url");
+  const summary = getFlagValue2(args, "--summary");
+  const start = getFlagValue2(args, "--start");
+  const end = getFlagValue2(args, "--end");
+  const description = getFlagValue2(args, "--description");
+  const location = getFlagValue2(args, "--location");
+  const attendees = parseAttendees2(getFlagValue2(args, "--attendees"));
+  if (!url || !summary || !start || !end) {
+    throw new CliError("missing_flags", "events update requires --url, --summary, --start, and --end");
+  }
+  return updateEvent(gateway, config, { url, summary, start, end, description, location, attendees });
+};
+
+// src/app/use-cases/events/delete-event.ts
+var deleteEvent = async (gateway, config, url) => {
+  const calendars = await gateway.listCalendars();
+  const calendar = await resolveCalendar(calendars, config.calendarName);
+  return gateway.deleteEvent({ calendar, url });
+};
+
+// src/app/commands/events/delete.command.ts
+var getFlagValue3 = (args, name) => {
+  const index = args.indexOf(name);
+  if (index === -1) return void 0;
+  return args[index + 1]?.startsWith("--") ? void 0 : args[index + 1];
+};
+var runEventsDeleteCommand = async (gateway, config, args) => {
+  const url = getFlagValue3(args, "--url") || args[2];
+  if (!url) {
+    throw new CliError("missing_flags", "events delete requires --url <event-url> or events delete <event-url>");
+  }
+  return deleteEvent(gateway, config, url);
+};
+
+// src/presentation/text/renderers.ts
+var renderCalendarsText = (result) => {
+  if (result.calendars.length === 0) return "calendars list: 0 item(s)";
+  return [
+    `calendars list: ${result.count} item(s)`,
+    ...result.calendars.map((calendar) => `- ${calendar.displayName} (${calendar.url})`)
+  ].join("\n");
+};
+var renderEventsText = (result) => {
+  const lines = [];
+  lines.push(`events list: ${result.count} item(s)`);
+  if (result.selectedCalendar) {
+    const rangeLabel = result.timeRange ? ` | range ${result.timeRange.start} \u2192 ${result.timeRange.end}` : "";
+    lines.push(`calendar: ${result.selectedCalendar.displayName}${rangeLabel}`);
+  }
+  if (result.events.length === 0) {
+    lines.push("- No events found.");
+    return lines.join("\n");
+  }
+  for (const event of result.events) {
+    lines.push(`- summary: ${event.summary}`);
+    lines.push(`  start: ${event.start ?? "-"}`);
+    lines.push(`  end: ${event.end ?? "-"}`);
+    lines.push(`  location: ${event.location ?? "-"}`);
+    lines.push(`  url: ${event.url}`);
+  }
+  return lines.join("\n");
+};
+var renderEventMutationText = (action, result) => {
+  return [
+    `events ${action}: done`,
+    `calendar: ${result.calendarName}`,
+    `url: ${result.url}`
+  ].join("\n");
+};
+
+// src/presentation/json/renderers.ts
+var renderJson = (value) => JSON.stringify(value, null, 2);
+
+// src/app/commands/runtime.ts
+var hasFlag = (args, name) => args.includes(name);
+var print = (args, value, renderText) => {
+  if (hasFlag(args, "--json")) {
+    console.log(renderJson(value));
+    return;
+  }
+  console.log(renderText(value));
+};
+var printError = (args, error) => {
+  if (hasFlag(args, "--json")) {
+    const normalized = error instanceof CliError ? { ok: false, error: { code: error.code, message: error.message } } : { ok: false, error: { message: error.message } };
+    console.error(renderJson(normalized));
+    return;
+  }
+  console.error(error.message);
+};
+var runCommand = async ({ gateway, config, args }) => {
+  if (args.length === 0) {
+    const result = await runEventsListCommand(gateway, config);
+    print(args, result, renderEventsText);
+    return true;
+  }
+  if (args[0] === "calendars" && args[1] === "list") {
+    const result = await runCalendarsListCommand(gateway);
+    print(args, result, renderCalendarsText);
+    return true;
+  }
+  if (args[0] === "events" && args[1] === "list") {
+    const result = await runEventsListCommand(gateway, config);
+    print(args, result, renderEventsText);
+    return true;
+  }
+  if (args[0] === "events" && args[1] === "create") {
+    const result = await runEventsCreateCommand(gateway, config, args);
+    print(args, result, (value) => renderEventMutationText("create", value));
+    return true;
+  }
+  if (args[0] === "events" && args[1] === "update") {
+    const result = await runEventsUpdateCommand(gateway, config, args);
+    print(args, result, (value) => renderEventMutationText("update", value));
+    return true;
+  }
+  if (args[0] === "events" && args[1] === "delete") {
+    const result = await runEventsDeleteCommand(gateway, config, args);
+    print(args, result, (value) => renderEventMutationText("delete", value));
+    return true;
+  }
+  return false;
+};
+
+// src/cli.ts
+var cli = cac("icalendar");
+cli.command("calendars list", "list available calendars");
+cli.command("events list", "list events for selected calendar/time range");
+cli.command("events create", "create calendar event");
+cli.command("events update", "update calendar event");
+cli.command("events delete [url]", "delete calendar event");
+cli.help();
+cli.version("0.1.0");
+var runCli = async (args = process.argv.slice(2)) => {
+  if (args.includes("--help") || args.includes("-h") || args.includes("--version") || args.includes("-v")) {
+    cli.parse();
+    return;
+  }
+  const configReader = new EnvConfigReader();
+  const config = configReader.readRuntimeConfig();
+  const gateway = new TsdavCalendarGateway(config);
+  if (!await runCommand({ gateway, config, args })) {
+    cli.parse();
+  }
+};
+runCli().catch((error) => {
+  printError(process.argv.slice(2), error);
+  process.exitCode = 1;
+});
+
+export {
+  runCli
+};

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+declare const runCli: (args?: string[]) => Promise<void>;
+
+export { runCli };

package/dist/cli.js

@@ -0,0 +1,6 @@
+import {
+  runCli
+} from "./chunk-MSLA47CB.js";
+export {
+  runCli
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { runCli } from './cli.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+import {
+  runCli
+} from "./chunk-MSLA47CB.js";
+export {
+  runCli
+};

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@cayde-6/icalendar",
+  "version": "0.1.0",
+  "description": "Production-ready TypeScript CLI for CalDAV calendars, iCalendar events, and agent automation",
+  "type": "module",
+  "private": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "icalendar": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "assets"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "bash -lc 'node --import tsx --test $(find test -name \"*.test.ts\" -print)'",
+    "test:coverage": "bash -lc 'c8 --reporter=text --reporter=lcov node --import tsx --test $(find test -name \"*.test.ts\" -print)'",
+    "build": "tsup src/cli.ts src/index.ts --format esm --dts --clean",
+    "dev": "tsx src/cli.ts",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "verify": "npm run check && npm run build && npm run test:coverage",
+    "start": "node dist/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cayde-6/icalendar.git"
+  },
+  "keywords": [
+    "caldav",
+    "icalendar",
+    "ics",
+    "cli",
+    "automation",
+    "agents",
+    "icloud"
+  ],
+  "author": "cayde-6",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/cayde-6/icalendar/issues"
+  },
+  "homepage": "https://github.com/cayde-6/icalendar#readme",
+  "dependencies": {
+    "cac": "^6.7.14",
+    "dotenv": "^17.4.2",
+    "tsdav": "^2.2.0",
+    "zod": "^4.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "c8": "^11.0.0",
+    "tsup": "^8.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}