@wangjs-jacky/ticktick-cli 0.1.0

package/tests/format.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from 'vitest';
+import { formatTaskTime } from '../src/utils/format.js';
+
+describe('formatTaskTime', () => {
+  it('全天任务应返回 "全天"', () => {
+    expect(
+      formatTaskTime({ startDate: '2026-04-04T00:00:00+0000', isAllDay: true })
+    ).toBe('全天');
+  });
+
+  it('有起止时间应返回 "HH:mm-HH:mm"', () => {
+    expect(
+      formatTaskTime({
+        startDate: '2026-04-04T14:15:00+0000',
+        dueDate: '2026-04-04T14:45:00+0000',
+        isAllDay: false,
+      })
+    ).toBe('14:15-14:45');
+  });
+
+  it('仅有开始时间应返回 "HH:mm"', () => {
+    expect(formatTaskTime({ startDate: '2026-04-04T09:00:00+0000' })).toBe(
+      '09:00'
+    );
+  });
+
+  it('无时间字段应返回空字符串', () => {
+    expect(formatTaskTime({})).toBe('');
+  });
+
+  it('仅有截止日期无开始时间应返回空字符串', () => {
+    expect(formatTaskTime({ dueDate: '2026-04-04T14:45:00+0000' })).toBe('');
+  });
+
+  it('全天任务无 startDate 应返回空字符串', () => {
+    expect(formatTaskTime({ isAllDay: true })).toBe('');
+  });
+
+  it('起止时间相同时只显示一个', () => {
+    expect(
+      formatTaskTime({
+        startDate: '2026-04-04T10:00:00+0000',
+        dueDate: '2026-04-04T10:00:00+0000',
+      })
+    ).toBe('10:00');
+  });
+
+  it('应处理 +08:00 时区格式', () => {
+    expect(
+      formatTaskTime({
+        startDate: '2026-04-04T14:15:00+08:00',
+        dueDate: '2026-04-04T14:45:00+08:00',
+      })
+    ).toBe('14:15-14:45');
+  });
+});

package/tests/oauth.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import { generateState, buildAuthUrl } from '../src/api/oauth.js';
+import type { OAuthConfig } from '../src/types.js';
+
+describe('OAuth utilities', () => {
+  it('generateState 应返回 32 位十六进制字符串', () => {
+    const state = generateState();
+    expect(state).toMatch(/^[0-9a-f]{32}$/);
+  });
+
+  it('generateState 每次应返回不同的值', () => {
+    const a = generateState();
+    const b = generateState();
+    expect(a).not.toBe(b);
+  });
+
+  it('buildAuthUrl 国内版应使用 dida365 域名', () => {
+    const config: OAuthConfig = { clientId: 'my-client-id', clientSecret: 'my-secret' };
+    const url = buildAuthUrl(config, 'test-state', 3000, 'cn');
+
+    expect(url).toContain('https://dida365.com/oauth/authorize');
+    expect(url).toContain('client_id=my-client-id');
+    expect(url).toContain('state=test-state');
+  });
+
+  it('buildAuthUrl 国际版应使用 ticktick 域名', () => {
+    const config: OAuthConfig = { clientId: 'my-client-id', clientSecret: 'my-secret' };
+    const url = buildAuthUrl(config, 'test-state', 3000, 'global');
+
+    expect(url).toContain('https://ticktick.com/oauth/authorize');
+    expect(url).toContain('client_id=my-client-id');
+  });
+
+  it('buildAuthUrl 不同端口应生成不同的 redirect_uri', () => {
+    const config: OAuthConfig = { clientId: 'id', clientSecret: 'secret' };
+    const url3000 = buildAuthUrl(config, 's', 3000, 'cn');
+    const url8080 = buildAuthUrl(config, 's', 8080, 'cn');
+
+    expect(url3000).toContain('localhost%3A3000');
+    expect(url8080).toContain('localhost%3A8080');
+  });
+});

package/tests/parity-fields.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest';
+import type { Task } from '../src/types.js';
+
+/**
+ * MCP OpenTask schema 定义的所有字段
+ * 来源：dida365 MCP server 的 OpenTask 类型定义
+ */
+const MCP_OPEN_TASK_FIELDS = [
+  'id',
+  'projectId',
+  'sortOrder',
+  'title',
+  'content',
+  'desc',
+  'startDate',
+  'dueDate',
+  'timeZone',
+  'isAllDay',
+  'priority',
+  'reminders',
+  'repeatFlag',
+  'completedTime',
+  'status',
+  'items',
+  'tags',
+  'columnId',
+  'parentId',
+  'childIds',
+  'columnName',
+  'assignor',
+  'etag',
+  'kind',
+] as const;
+
+/**
+ * CLI Task 接口的所有字段
+ */
+const CLI_TASK_FIELDS: (keyof Task)[] = [
+  'id',
+  'projectId',
+  'title',
+  'isAllDay',
+  'completedTime',
+  'content',
+  'desc',
+  'dueDate',
+  'items',
+  'priority',
+  'reminders',
+  'repeatFlag',
+  'sortOrder',
+  'startDate',
+  'status',
+  'timeZone',
+  'kind',
+  'tags',
+  'etag',
+  'columnId',
+  'parentId',
+  'childIds',
+  'columnName',
+  'assignor',
+];
+
+describe('MCP-CLI 等价校验：Task 字段覆盖', () => {
+  it('CLI Task 类型应覆盖 MCP OpenTask 的所有核心字段', () => {
+    const cliSet = new Set<string>(CLI_TASK_FIELDS);
+    const missing = MCP_OPEN_TASK_FIELDS.filter((f) => !cliSet.has(f));
+
+    expect(missing, `CLI Task 缺少 MCP 字段: ${missing.join(', ')}`).toEqual([]);
+  });
+
+  it('CLI Task 字段数应 >= MCP OpenTask 字段数', () => {
+    const cliSet = new Set<string>(CLI_TASK_FIELDS);
+    const mcpSet = new Set<string>(MCP_OPEN_TASK_FIELDS);
+
+    expect(cliSet.size).toBeGreaterThanOrEqual(mcpSet.size);
+  });
+
+  it('CLI 可有 MCP 无的扩展字段（仅做信息性输出）', () => {
+    const mcpSet = new Set<string>(MCP_OPEN_TASK_FIELDS);
+    const cliExtra = CLI_TASK_FIELDS.filter((f) => !mcpSet.has(f));
+
+    // CLI 扩展字段是允许的，仅做日志输出
+    if (cliExtra.length > 0) {
+      console.log(`  CLI 扩展字段（MCP 无对应）: ${cliExtra.join(', ')}`);
+    }
+  });
+});

package/tests/parity-map.ts

@@ -0,0 +1,184 @@
+/**
+ * MCP 工具与 CLI API 函数的等价映射表
+ *
+ * 用于自动化校验 MCP 工具 ↔ CLI API 函数的输入输出一致性。
+ * 每次新增 MCP 工具或 CLI API 函数时，需同步更新此表。
+ */
+
+export interface ParityEntry {
+  /** MCP 工具名称 */
+  mcpTool: string;
+  /** CLI API 函数名称 (在 src/api/resources.ts 中) */
+  cliApiFn: string;
+  /** CLI 命令名称 (tt <command>) */
+  cliCommand: string;
+  /** API HTTP 方法 */
+  httpMethod: string;
+  /** API 路径模板 */
+  apiPath: string;
+  /** 备注 */
+  notes?: string;
+}
+
+/**
+ * 完整的 MCP 工具 → CLI 映射表
+ */
+export const PARITY_MAP: ParityEntry[] = [
+  // ─── 项目 (Project) ────────────────────────────────
+  {
+    mcpTool: 'list_projects',
+    cliApiFn: 'getProjects',
+    cliCommand: 'project-list',
+    httpMethod: 'GET',
+    apiPath: 'project',
+  },
+  {
+    mcpTool: 'get_project_by_id',
+    cliApiFn: 'getProject',
+    cliCommand: 'project-get <id>',
+    httpMethod: 'GET',
+    apiPath: 'project/{projectId}',
+  },
+  {
+    mcpTool: 'get_project_with_undone_tasks',
+    cliApiFn: 'getProjectData',
+    cliCommand: 'project-tasks <id>',
+    httpMethod: 'GET',
+    apiPath: 'project/{projectId}/data',
+  },
+  {
+    mcpTool: 'create_project',
+    cliApiFn: 'createProject',
+    cliCommand: 'project-create [name]',
+    httpMethod: 'POST',
+    apiPath: 'project',
+  },
+  {
+    mcpTool: 'update_project',
+    cliApiFn: 'updateProject',
+    cliCommand: 'project-update <id>',
+    httpMethod: 'POST',
+    apiPath: 'project/{projectId}',
+  },
+
+  // ─── 任务 (Task) ──────────────────────────────────────
+  {
+    mcpTool: 'create_task',
+    cliApiFn: 'createTask',
+    cliCommand: 'task-add [title]',
+    httpMethod: 'POST',
+    apiPath: 'task',
+  },
+  {
+    mcpTool: 'get_task_in_project',
+    cliApiFn: 'getTask',
+    cliCommand: 'task-get <projectId> <taskId>',
+    httpMethod: 'GET',
+    apiPath: 'project/{projectId}/task/{taskId}',
+  },
+  {
+    mcpTool: 'get_task_by_id',
+    cliApiFn: 'getTaskById',
+    cliCommand: 'task-find <taskId>',
+    httpMethod: 'POST',
+    apiPath: 'task/filter (客户端过滤)',
+    notes: 'CLI 通过 filterTasks + 客户端匹配实现',
+  },
+  {
+    mcpTool: 'update_task',
+    cliApiFn: 'updateTask',
+    cliCommand: 'task-update <taskId>',
+    httpMethod: 'POST',
+    apiPath: 'task/{taskId}',
+  },
+  {
+    mcpTool: 'complete_task',
+    cliApiFn: 'completeTask',
+    cliCommand: 'task-done <projectId> <taskId>',
+    httpMethod: 'POST',
+    apiPath: 'project/{projectId}/task/{taskId}/complete',
+  },
+  {
+    mcpTool: 'batch_add_tasks',
+    cliApiFn: 'batchAddTasks',
+    cliCommand: 'task-batch-add [jsonFile]',
+    httpMethod: 'POST',
+    apiPath: 'task/batch',
+  },
+  {
+    mcpTool: 'batch_update_tasks',
+    cliApiFn: 'batchUpdateTasks',
+    cliCommand: 'task-batch-update [jsonFile]',
+    httpMethod: 'POST',
+    apiPath: 'task/batch',
+  },
+  {
+    mcpTool: 'complete_tasks_in_project',
+    cliApiFn: 'completeTasksInProject',
+    cliCommand: 'task-batch-done <projectId>',
+    httpMethod: 'POST',
+    apiPath: 'project/{projectId}/task/{taskId}/complete (循环调用)',
+    notes: 'CLI 循环调用 completeTask 实现',
+  },
+  {
+    mcpTool: 'filter_tasks',
+    cliApiFn: 'filterTasks',
+    cliCommand: 'task-list',
+    httpMethod: 'POST',
+    apiPath: 'task/filter',
+  },
+  {
+    mcpTool: 'list_completed_tasks_by_date',
+    cliApiFn: 'getCompletedTasks',
+    cliCommand: 'task-completed',
+    httpMethod: 'POST',
+    apiPath: 'task/completed',
+  },
+  {
+    mcpTool: 'list_undone_tasks_by_date',
+    cliApiFn: 'listUndoneTasksByDate',
+    cliCommand: 'task-undone --start --end',
+    httpMethod: 'POST',
+    apiPath: 'task/filter (status:[0])',
+    notes: 'CLI 封装 filterTasks 并添加 status:[0]',
+  },
+  {
+    mcpTool: 'list_undone_tasks_by_time_query',
+    cliApiFn: 'listUndoneTasksByTimeQuery',
+    cliCommand: 'task-undone --query <preset>',
+    httpMethod: 'POST',
+    apiPath: 'task/filter (计算日期范围 + status:[0])',
+    notes: 'CLI 计算本地日期范围后调用 listUndoneTasksByDate',
+  },
+  {
+    mcpTool: 'search_task',
+    cliApiFn: 'searchTask',
+    cliCommand: 'task-search <keyword>',
+    httpMethod: 'POST',
+    apiPath: 'task/filter (客户端关键词匹配)',
+  },
+  {
+    mcpTool: 'search',
+    cliApiFn: 'searchTask',
+    cliCommand: 'task-search <keyword>',
+    httpMethod: 'POST',
+    apiPath: 'task/filter (客户端关键词匹配)',
+    notes: '别名，对应同一个 CLI 函数',
+  },
+  {
+    mcpTool: 'move_task',
+    cliApiFn: 'moveTasks',
+    cliCommand: 'task-move <taskId>',
+    httpMethod: 'POST',
+    apiPath: 'task/move',
+  },
+
+  // ─── 用户 (User) ───────────────────────────────────────
+  {
+    mcpTool: 'get_user_preference',
+    cliApiFn: 'getUserPreference',
+    cliCommand: 'user-pref',
+    httpMethod: 'GET',
+    apiPath: 'user/info',
+  },
+];

package/tests/parity.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest';
+import { PARITY_MAP } from './parity-map.js';
+
+/**
+ * resources.ts 中实际导出的全部 API 函数名
+ * （每次新增 API 函数时需同步更新）
+ */
+const RESOURCES_EXPORTED_FNS = [
+  // Project API
+  'getProjects',
+  'getProject',
+  'getProjectData',
+  'createProject',
+  'updateProject',
+  'deleteProject',
+  // Task API
+  'getTask',
+  'createTask',
+  'updateTask',
+  'completeTask',
+  'deleteTask',
+  'moveTasks',
+  'getCompletedTasks',
+  'filterTasks',
+  // Batch
+  'batchAddTasks',
+  'batchUpdateTasks',
+  'completeTasksInProject',
+  // Query
+  'getTaskById',
+  'getUserPreference',
+  'listUndoneTasksByDate',
+  'listUndoneTasksByTimeQuery',
+  'searchTask',
+] as const;
+
+describe('MCP-CLI 等价校验：API 函数覆盖', () => {
+  it('映射表中每个 CLI API 函数名应存在于 resources.ts 导出列表中', () => {
+    const exportedSet = new Set(RESOURCES_EXPORTED_FNS);
+    const missing: string[] = [];
+
+    for (const entry of PARITY_MAP) {
+      if (!exportedSet.has(entry.cliApiFn)) {
+        missing.push(`${entry.mcpTool} -> resources.${entry.cliApiFn}`);
+      }
+    }
+
+    expect(missing, `以下 CLI API 函数在 resources.ts 中不存在:\n${missing.join('\n')}`).toEqual([]);
+  });
+
+  it('映射表应覆盖所有已知的 MCP 工具', () => {
+    const knownTools = [
+      'list_projects',
+      'get_project_by_id',
+      'get_project_with_undone_tasks',
+      'create_project',
+      'update_project',
+      'create_task',
+      'get_task_in_project',
+      'get_task_by_id',
+      'update_task',
+      'complete_task',
+      'batch_add_tasks',
+      'batch_update_tasks',
+      'complete_tasks_in_project',
+      'filter_tasks',
+      'list_completed_tasks_by_date',
+      'list_undone_tasks_by_date',
+      'list_undone_tasks_by_time_query',
+      'search_task',
+      'search',
+      'move_task',
+      'get_user_preference',
+    ];
+
+    const mappedTools = new Set(PARITY_MAP.map((e) => e.mcpTool));
+    const unmapped = knownTools.filter((t) => !mappedTools.has(t));
+
+    expect(unmapped, `以下 MCP 工具未在映射表中:\n${unmapped.join('\n')}`).toEqual([]);
+  });
+
+  it('非别名条目不应有重复的 CLI API 函数', () => {
+    const nonAliasEntries = PARITY_MAP.filter(
+      (e) => !e.notes?.includes('别名')
+    );
+    const fns = nonAliasEntries.map((e) => e.cliApiFn);
+    const uniqueFns = new Set(fns);
+
+    expect(uniqueFns.size, `存在重复的 CLI API 函数映射`).toBe(fns.length);
+  });
+
+  it('每个映射条目都包含必要字段', () => {
+    for (const entry of PARITY_MAP) {
+      expect(entry.mcpTool, 'mcpTool 不能为空').toBeTruthy();
+      expect(entry.cliApiFn, 'cliApiFn 不能为空').toBeTruthy();
+      expect(entry.cliCommand, 'cliCommand 不能为空').toBeTruthy();
+      expect(entry.httpMethod, 'httpMethod 不能为空').toBeTruthy();
+      expect(entry.apiPath, 'apiPath 不能为空').toBeTruthy();
+    }
+  });
+});

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "ignoreDeprecations": "6.0",
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "outDir": "dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*", "bin/**/*", "tests/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  target: 'node18',
+  clean: true,
+  splitting: false,
+  sourcemap: true,
+  dts: true,
+  banner: { js: '#!/usr/bin/env node' },
+});

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+  },
+});