dsh-calendar 0.3.2 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stardustlc
+
+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.en.md

@@ -1,7 +1,13 @@
 # dsh-calendar
 
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
+
 DSH community plugin: read/write calendar events via CalDAV. Provides 5 model-facing tools (calendar_list / calendar_create / calendar_update / calendar_delete / calendar_search), supporting Google / iCloud / Nextcloud and any CalDAV server. This round is a node half-body with no settings-page UI; all configuration goes through the profile's cordis.patch.yml.
 
+## Compatibility
+
+Verified against `@deepseek-ai/dsh@0.1.1-rc.2` on 2026-08-26. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+
 ## Installation
 
 ```bash
@@ -10,6 +16,15 @@ dsh plugin --profile web add dsh-calendar
 
 After installing, restart dsh. The plugin inserts a `calendar` config line into the profile (see this package's cordis.patch.yml). The default provider is custom with no credentials filled in; the plugin still loads, but tools throw a Chinese guidance error when called, prompting you to complete the configuration.
 
+## Uninstall
+
+```bash
+dsh plugin --profile web remove dsh-calendar
+```
+
+Then restart the web service. To clean up fully, also remove the plugin entry from your profile `cordis.patch.yml` if you overrode it.
+
+
 ## Configuration
 
 All configuration lives in your profile's cordis.patch.yml; override the `calendar` line by id (overriding replaces that line's config wholesale). Common fields:
@@ -92,11 +107,11 @@ If your CalDAV server is not directly reachable from your network (some regional
 
 ## Tool reference
 
-- `calendar_list`: list events in a time range (start/end, ISO 8601; defaults to the next 7 days). Recurring events are expanded by default (`expand` defaults to true, `maxOccurrences` defaults to 30, clamped to 1-200): each occurrence is a separate row with `isOccurrence: true` and `seriesStart`; non-recurring events keep `isOccurrence: false`. With `expand=false`, recurring events are returned as a single original entry with `rrule`
-- `calendar_create`: create an event (summary/start/end required; description/location/allDay optional)
-- `calendar_update`: edit an event by uid (summary/start/end/description/location/allDay optional; omitted fields keep their original values)
+- `calendar_list`: list events in a time range (start/end, ISO 8601; defaults to the next 7 days). Recurring events are expanded by default (`expand` defaults to true, `maxOccurrences` defaults to 30, clamped to 1-200): each occurrence is a separate row with `isOccurrence: true` and `seriesStart`; non-recurring events keep `isOccurrence: false`. With `expand=false`, recurring events are returned as a single original entry with `rrule`. Results are stably sorted by start time.
+- `calendar_create`: create an event (summary/start/end required; description/location/allDay/rrule optional). Validates real calendar dates and `end >= start`.
+- `calendar_update`: edit an event by uid (summary/start/end/description/location/allDay/rrule optional; omitted fields keep their original values, including the recurrence rule).
 - `calendar_delete`: delete an event by uid
-- `calendar_search`: search events by keyword (client-side filter over title/description/location/UID, case-insensitive)
+- `calendar_search`: search events by keyword (client-side filter over title/description/location/UID, case-insensitive; `limit` defaults to 50, clamped to 1-200, and results are sorted by start time).
 
 The stable event identifier `uid` is the CalDAV href (full object URL); `calendar_update` / `calendar_delete` use it.
 
@@ -104,6 +119,14 @@ The stable event identifier `uid` is the CalDAV href (full object URL); `calenda
 
 Input and output are uniformly ISO 8601. Timed events are output in UTC (e.g. `2025-01-15T01:00:00Z`); all-day events output `YYYY-MM-DD`. Input may carry a timezone offset (e.g. `2025-01-15T09:00:00+08:00`); the plugin converts to UTC internally for storage.
 
+
+## v0.3.2 improvements
+
+- Fix `calendar_update` dropping `rrule` while updating other fields.
+- Validate `end >= start` and reject impossible dates such as `2025-02-30`.
+- Sort `calendar_list` / `calendar_search` output by start time and clamp search `limit` to 1-200.
+- Reset the cached CalDAV client after creation failure so the next tool call can retry.
+
 ## Known limitations
 
 - Recurring event expansion: calendar_list expands RRULE by default via ICAL.RecurExpansion (`expand=true`), capped by `maxOccurrences`; calendar_search still returns the original series (not expanded).
@@ -121,4 +144,4 @@ pnpm install
 pnpm test   # 构建 + node --test
 ```
 
-Build output in `lib/`; tests in `test/*.test.mjs` (no real account needed).
+Build output in `lib/`; tests in `test/*.test.mjs` (no real account needed).

package/README.md

@@ -6,9 +6,15 @@
 
 ![npm version](https://img.shields.io/npm/v/dsh-calendar?label=npm&color=blue) ![npm downloads](https://img.shields.io/npm/dm/dsh-calendar) ![license](https://img.shields.io/npm/l/dsh-calendar) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-calendar?style=social)
 
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
+
 
 DSH 社区插件：通过 CalDAV 读写日历事件。提供 5 个面向模型的工具（calendar_list / calendar_create / calendar_update / calendar_delete / calendar_search），支持 Google / iCloud / Nextcloud 及任意 CalDAV 服务器。本轮为 node 半身，不含设置页 UI，配置全部走 profile 的 cordis.patch.yml。
 
+## 兼容性
+
+在 `@deepseek-ai/dsh@0.1.1-rc.2` 上验证（2026-08-26）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+
 ## 安装
 
 ```bash
@@ -29,6 +35,15 @@ dsh plugin --profile web add dsh-calendar
 - `calendarId`：google 专用，日历 ID（通常是你的邮箱）
 - `host` / `user` / `calendar`：nextcloud 专用
 
+
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-calendar
+```
+
+卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中的对应插件行。
+
 ## 中国用户：特殊代理配置（Google / iCloud）
 
 Google 与 iCloud 的 CalDAV 端点在中国大陆**不可直连**，需要配合你常用的梯子/特殊代理使用。插件内置 `proxyUrl` 配置：把 CalDAV 请求路由到**你本机代理客户端的端口**，不影响其他插件，也无需改任何系统设置。
@@ -119,11 +134,11 @@ iCloud：登录 appleid.apple.com → 登录与安全 → App 专用密码，生
 
 ## 工具清单
 
-- `calendar_list`：列出某时间段事件（start/end，ISO 8601，缺省未来 7 天）。默认展开重复事件（`expand` 默认 true，`maxOccurrences` 默认 30、clamp 1-200）：每个实例独立成行，带 `isOccurrence: true` 与 `seriesStart`；非重复事件保持 `isOccurrence: false`。`expand=false` 时重复事件按原始单条返回并带 `rrule`
-- `calendar_create`：新建事件（summary/start/end 必填，description/location/allDay 可选）
-- `calendar_update`：按 uid 改事件（summary/start/end/description/location/allDay 可选，未提供保留原值）
+- `calendar_list`：列出某时间段事件（start/end，ISO 8601，缺省未来 7 天）。默认展开重复事件（`expand` 默认 true，`maxOccurrences` 默认 30、clamp 1-200）：每个实例独立成行，带 `isOccurrence: true` 与 `seriesStart`；非重复事件保持 `isOccurrence: false`。`expand=false` 时重复事件按原始单条返回并带 `rrule`。结果按开始时间稳定排序
+- `calendar_create`：新建事件（summary/start/end 必填，description/location/allDay/rrule 可选）。严格校验真实日历日期与 `end >= start`
+- `calendar_update`：按 uid 改事件（summary/start/end/description/location/allDay/rrule 可选，未提供保留原值，重复规则不再丢失）
 - `calendar_delete`：按 uid 删事件
-- `calendar_search`：按关键词搜事件（客户端过滤标题/描述/地点/UID，不区分大小写）
+- `calendar_search`：按关键词搜事件（客户端过滤标题/描述/地点/UID，不区分大小写；`limit` 默认 50、clamp 1-200，结果按开始时间排序）
 
 事件稳定标识 `uid` 为 CalDAV href（完整对象 URL），`calendar_update` / `calendar_delete` 使用它。
 
@@ -131,6 +146,14 @@ iCloud：登录 appleid.apple.com → 登录与安全 → App 专用密码，生
 
 输入输出统一 ISO 8601。定时事件输出为 UTC（如 `2025-01-15T01:00:00Z`），全天事件输出 `YYYY-MM-DD`。输入可带时区偏移（如 `2025-01-15T09:00:00+08:00`），插件内部转 UTC 存储。
 
+## v0.3.2 优化
+
+- 修复 `calendar_update` 更新其他字段时丢失 `rrule` 的问题。
+- 更新与新建都会校验 `end >= start`，并拒绝 `2025-02-30` 这类不存在的日期。
+- `calendar_list` / `calendar_search` 输出按开始时间稳定排序；搜索 `limit` clamp 到 1-200。
+- CalDAV 客户端创建失败后清空缓存，下一次调用可自动重试，不再永久复用 rejected promise。
+
+
 ## 已知限制
 
 - **国内网络**：Google 与 iCloud 的 CalDAV 端点在中国大陆不可直连；可用 `proxyUrl` 走本机梯子/特殊代理，或改用国内可直连的 CalDAV 端点（自建 Nextcloud/Radicale）。
@@ -157,5 +180,4 @@ pnpm test   # 构建 + node --test
 
 - [dsh-calendar](https://github.com/STARDUSTLC666/dsh-calendar) — CalDAV 日历五件套
 - [dsh-slack](https://github.com/STARDUSTLC666/dsh-slack) — Slack 通知/收件箱
-- [dsh-dingtalk](https://github.com/STARDUSTLC666/dsh-dingtalk) — 钉钉群通知（零依赖）
-
+- [dsh-dingtalk](https://github.com/STARDUSTLC666/dsh-dingtalk) — 钉钉群通知（零依赖）

package/lib/ical.js

@@ -179,7 +179,12 @@ export function expandEventFromICal(data, href, etag, rangeStart, rangeEnd, maxO
     const rangeEndMs = isoToEpochMs(rangeEnd);
     const occurrences = [];
     try {
+        const totalIterationCap = Math.max(100000, maxOccurrences * 1000);
+        let iterations = 0;
         while (occurrences.length < maxOccurrences) {
+            iterations += 1;
+            if (iterations > totalIterationCap)
+                break;
             const next = expansion.next();
             if (next === null || next === undefined)
                 break;

package/lib/index.d.ts

@@ -10,6 +10,7 @@
 import { type CalendarConfig } from './config.js';
 import { type CalendarToolDefinition } from './tools.js';
 /** cordis 服务注入：apply 里要用 ctx.tools，必须显式声明注入，否则宿主会抛 cannot get property without inject。 */
+export declare const name = "calendar";
 export declare const inject: string[];
 /** 插件所需的最小 ctx 面（社区插件不依赖宿主内部类型）。 */
 export interface CalendarPluginContext {

package/lib/index.js

@@ -10,6 +10,7 @@
 import { resolveConfig } from './config.js';
 import { buildCalendarTools } from './tools.js';
 /** cordis 服务注入：apply 里要用 ctx.tools，必须显式声明注入，否则宿主会抛 cannot get property without inject。 */
+export const name = 'calendar';
 export const inject = ['tools'];
 /**
  * 插件入口：惰性解析配置并注册五个日历工具。

package/lib/tools.d.ts

@@ -26,5 +26,5 @@ export interface CalendarToolDefinition {
     execute(args: unknown, exec: unknown): Promise<unknown>;
     timeoutMs?: number;
 }
-/** 构建五个工具定义；每个 execute 惰性解析配置，缺失时抛出中文指引。 */
+/** 构建六个工具定义；每个 execute 惰性解析配置，缺失时抛出中文指引。 */
 export declare function buildCalendarTools(config: CalendarConfig | undefined): CalendarToolDefinition[];

package/lib/tools.js

@@ -96,7 +96,7 @@ function buildSearchFilter(query) {
         return haystack.includes(needle);
     };
 }
-/** 构建五个工具定义；每个 execute 惰性解析配置，缺失时抛出中文指引。 */
+/** 构建六个工具定义；每个 execute 惰性解析配置，缺失时抛出中文指引。 */
 export function buildCalendarTools(config) {
     const service = () => new CalendarService(resolveConfig(config));
     const list = {
@@ -319,5 +319,48 @@ export function buildCalendarTools(config) {
         },
         timeoutMs: TIMEOUT_MS,
     };
-    return [list, create, update, remove, search];
+    const health = {
+        name: 'calendar_health',
+        description: 'dsh-calendar 自检：检查 CalDAV 配置完整性（服务商/日历地址/账号/密码），不发起网络连接。遇到问题时先运行本工具定位。',
+        parameters: compileParameters({}),
+        output: {
+            schema: { type: 'object', additionalProperties: true },
+            render: (_args, value) => {
+                const rec = (value ?? {});
+                const rawChecks = Array.isArray(rec.checks) ? rec.checks : [];
+                const lines = ['dsh-calendar 自检' + (rec.ok === true ? '：正常。' : '：发现问题。')];
+                for (const item of rawChecks) {
+                    const c = (item ?? {});
+                    lines.push('- ' + String(c.name) + '：' + (c.ok === true ? '✅ ' + String(c.detail ?? '') : '❌ ' + String(c.detail ?? '')));
+                }
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute() {
+            const checks = [];
+            let ok = true;
+            const provider = (config?.provider ?? 'custom');
+            checks.push({ name: '服务商', ok: true, detail: provider });
+            const hasUrl = typeof config?.caldavUrl === 'string' && config.caldavUrl.trim() !== '';
+            const derivable = provider === 'google' || provider === 'nextcloud' || provider === 'icloud';
+            if (hasUrl || derivable) {
+                checks.push({ name: '日历地址', ok: true, detail: hasUrl ? '已配置 caldavUrl' : provider + ' 预设可推导' });
+            }
+            else {
+                ok = false;
+                checks.push({ name: '日历地址', ok: false, detail: '未配置：请在 profile 的 cordis.patch.yml 里给 calendar 行填 caldavUrl' });
+            }
+            const hasUser = typeof config?.username === 'string' && config.username.trim() !== '';
+            checks.push({ name: '账号', ok: hasUser, detail: hasUser ? '已配置' : '未配置：请填 username（Google/iCloud 为账号邮箱）' });
+            if (!hasUser)
+                ok = false;
+            const hasPass = typeof config?.password === 'string' && config.password.trim() !== '';
+            checks.push({ name: '密码', ok: hasPass, detail: hasPass ? '已配置' : '未配置：请填 password 或环境变量 DSH_CALENDAR_PASSWORD（Google/iCloud 用应用专用密码）' });
+            if (!hasPass)
+                ok = false;
+            return { ok, plugin: 'dsh-calendar', checks };
+        },
+        timeoutMs: TIMEOUT_MS,
+    };
+    return [list, create, update, remove, search, health];
 }

package/package.json

@@ -1,61 +1,63 @@
-{
-  "name": "dsh-calendar",
-  "version": "0.3.2",
-  "description": "DSH 日历工具插件：通过 CalDAV 读写日历事件（Google / iCloud / Nextcloud / 自定义）",
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./cordis.patch.yml": "./cordis.patch.yml",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib",
-    "cordis.patch.yml",
-    "README.md"
-  ],
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  },
-  "keywords": [
-    "dsh",
-    "deepseek-harness",
-    "plugin",
-    "calendar",
-    "caldav",
-    "ical"
-  ],
-  "license": "MIT",
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "ical.js": "^2.1.0",
-    "tsdav": "^2.3.1",
-    "undici": "^8.10.0"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "typescript": "^5.6.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/STARDUSTLC666/dsh-calendar"
-  },
-  "bugs": {
-    "url": "https://github.com/STARDUSTLC666/dsh-calendar/issues"
-  },
-  "homepage": "https://github.com/STARDUSTLC666/dsh-calendar#readme",
-  "author": "stardustlc",
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "pnpm run build && node --test \"test/*.test.mjs\""
-  }
-}
+{
+  "name": "dsh-calendar",
+  "version": "0.4.0",
+  "description": "DSH 日历工具插件：通过 CalDAV 读写日历事件（Google / iCloud / Nextcloud / 自定义）",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && node --test \"test/*.test.mjs\"",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "calendar",
+    "caldav",
+    "ical"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "ical.js": "^2.1.0",
+    "tsdav": "^2.3.1",
+    "undici": "^8.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/STARDUSTLC666/dsh-calendar.git"
+  },
+  "bugs": {
+    "url": "https://github.com/STARDUSTLC666/dsh-calendar/issues"
+  },
+  "homepage": "https://github.com/STARDUSTLC666/dsh-calendar#readme",
+  "author": "stardustlc",
+  "packageManager": "pnpm@11.7.0"
+}