@wangjs-jacky/ticktick-cli 0.1.0

package/src/commands/user.ts

@@ -0,0 +1,43 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { getUserPreference } from '../api/resources.js';
+
+async function userPrefCommand(): Promise<void> {
+  const s = p.spinner();
+  s.start('正在获取用户偏好...');
+
+  try {
+    const pref = await getUserPreference();
+    s.stop('获取成功');
+
+    console.log('');
+    if (pref.timeZone) console.log(`  时区: ${pref.timeZone}`);
+    if (pref.dateFormat !== undefined)
+      console.log(`  日期格式: ${pref.dateFormat}`);
+    if (pref.language) console.log(`  语言: ${pref.language}`);
+    if (pref.theme) console.log(`  主题: ${pref.theme}`);
+
+    // 如果所有字段都为空，显示原始数据
+    if (!pref.timeZone && pref.dateFormat === undefined && !pref.language && !pref.theme) {
+      console.log(pc.dim('  （未获取到偏好信息，API 可能不支持此端点）'));
+    }
+    console.log('');
+    p.outro('用户偏好如上');
+  } catch (err) {
+    s.stop('获取失败');
+    p.outro(pc.red(`获取用户偏好失败: ${(err as Error).message}`));
+  }
+}
+
+// ─── 注册命令 ────────────────────────────────────────
+
+export function registerUserCommands(cli: {
+  command: (name: string, desc: string) => {
+    option: (flag: string, desc: string) => {
+      action: (fn: (...args: unknown[]) => Promise<void>) => unknown;
+    };
+    action: (fn: (...args: unknown[]) => Promise<void>) => unknown;
+  };
+}): void {
+  cli.command('user-pref', '查看用户偏好设置').action(userPrefCommand);
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+import { cac } from 'cac';
+import type { Region } from './types.js';
+import { loginCommand, logoutCommand, whoamiCommand, configCommand } from './commands/auth.js';
+import { registerProjectCommands } from './commands/project.js';
+import { registerTaskCommands } from './commands/task.js';
+import { registerUserCommands } from './commands/user.js';
+
+// cac v7 不支持空格子命令（如 'task list'），需要将 argv 预处理为连字符格式
+const SUBCOMMAND_GROUPS = ['task', 'project', 'user'];
+const argv = process.argv.slice(2);
+if (
+  argv.length >= 2 &&
+  SUBCOMMAND_GROUPS.includes(argv[0]) &&
+  !argv[1].startsWith('-')
+) {
+  argv.splice(0, 2, `${argv[0]}-${argv[1]}`);
+}
+
+const cli = cac('tt');
+
+// 认证命令
+cli.command('login', '登录滴答清单').action(loginCommand);
+cli.command('logout', '登出').action(logoutCommand);
+cli.command('whoami', '查看登录状态').action(whoamiCommand);
+cli
+  .command('config', '查看/设置配置')
+  .option('--region <region>', '切换区域: cn (国内版) / global (国际版)')
+  .action(async (options: { region?: string }) => {
+    if (options.region && options.region !== 'cn' && options.region !== 'global') {
+      console.error(`无效的区域: ${options.region}，请使用 cn 或 global`);
+      process.exit(1);
+    }
+    await configCommand({ region: options.region as Region | undefined });
+  });
+
+// 项目命令
+registerProjectCommands(cli);
+
+// 任务命令
+registerTaskCommands(cli);
+
+// 用户命令
+registerUserCommands(cli);
+
+cli.help();
+cli.parse(['', '', ...argv]);

package/src/types.ts

@@ -0,0 +1,211 @@
+/** OAuth2 客户端凭证 */
+export interface OAuthConfig {
+  clientId: string;
+  clientSecret: string;
+  /** 凭证所属区域 */
+  region?: Region;
+}
+
+/** 持久化的 Token 数据 */
+export interface TokenData {
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+}
+
+/** API 区域 */
+export type Region = 'cn' | 'global';
+
+/** 区域对应的接口地址 */
+export interface RegionEndpoints {
+  authUrl: string;
+  tokenUrl: string;
+  apiBase: string;
+  developerUrl: string;
+}
+
+/** 配置文件结构 (~/.tt-cli/config.json) */
+export interface AppConfig {
+  oauth?: OAuthConfig;
+  token?: TokenData;
+  region?: Region;
+}
+
+/** TickTick OAuth2 token 响应 */
+export interface TokenResponse {
+  access_token: string;
+  token_type: string;
+  expires_in: number;
+  refresh_token: string;
+  scope: string;
+}
+
+// ─── API 数据类型 ────────────────────────────────────
+
+/** 项目 */
+export interface Project {
+  id: string;
+  name: string;
+  color: string;
+  sortOrder?: number;
+  closed?: boolean;
+  groupId?: string;
+  viewMode?: 'list' | 'kanban' | 'timeline';
+  permission?: 'read' | 'write' | 'comment';
+  kind?: 'TASK' | 'NOTE';
+}
+
+/** 看板列 */
+export interface Column {
+  id: string;
+  projectId: string;
+  name: string;
+  sortOrder: number;
+}
+
+/** 项目及数据 */
+export interface ProjectData {
+  project: Project;
+  tasks: Task[];
+  columns: Column[];
+}
+
+/** 清单子项 */
+export interface ChecklistItem {
+  id?: string;
+  title: string;
+  status?: number;
+  completedTime?: string;
+  isAllDay?: boolean;
+  sortOrder?: number;
+  startDate?: string;
+  timeZone?: string;
+}
+
+/** 任务 */
+export interface Task {
+  id: string;
+  projectId: string;
+  title: string;
+  isAllDay?: boolean;
+  completedTime?: string;
+  content?: string;
+  desc?: string;
+  dueDate?: string;
+  items?: ChecklistItem[];
+  priority?: number;
+  reminders?: string[];
+  repeatFlag?: string;
+  sortOrder?: number;
+  startDate?: string;
+  status?: number;
+  timeZone?: string;
+  kind?: 'TEXT' | 'NOTE' | 'CHECKLIST';
+  tags?: string[];
+  etag?: string;
+  /** 看板列 ID */
+  columnId?: string;
+  /** 父任务 ID */
+  parentId?: string;
+  /** 子任务 ID 列表 */
+  childIds?: string[];
+  /** 看板列名称 */
+  columnName?: string;
+  /** 任务指派人 */
+  assignor?: string;
+}
+
+// ─── API 请求参数类型 ────────────────────────────────
+
+/** 创建项目参数 */
+export interface CreateProjectParams {
+  name: string;
+  color?: string;
+  sortOrder?: number;
+  viewMode?: 'list' | 'kanban' | 'timeline';
+  kind?: 'TASK' | 'NOTE';
+}
+
+/** 更新项目参数 */
+export interface UpdateProjectParams {
+  name?: string;
+  color?: string;
+  sortOrder?: number;
+  viewMode?: 'list' | 'kanban' | 'timeline';
+  kind?: 'TASK' | 'NOTE';
+}
+
+/** 创建任务参数 */
+export interface CreateTaskParams {
+  title: string;
+  projectId: string;
+  content?: string;
+  desc?: string;
+  isAllDay?: boolean;
+  startDate?: string;
+  dueDate?: string;
+  timeZone?: string;
+  reminders?: string[];
+  repeatFlag?: string;
+  priority?: number;
+  sortOrder?: number;
+  items?: ChecklistItem[];
+}
+
+/** 更新任务参数 */
+export interface UpdateTaskParams {
+  id: string;
+  projectId: string;
+  title?: string;
+  content?: string;
+  desc?: string;
+  isAllDay?: boolean;
+  startDate?: string;
+  dueDate?: string;
+  timeZone?: string;
+  reminders?: string[];
+  repeatFlag?: string;
+  priority?: number;
+  sortOrder?: number;
+  items?: ChecklistItem[];
+}
+
+/** 移动任务参数 */
+export interface MoveTaskParams {
+  fromProjectId: string;
+  toProjectId: string;
+  taskId: string;
+}
+
+/** 已完成任务查询参数 */
+export interface CompletedTasksParams {
+  projectIds?: string[];
+  startDate?: string;
+  endDate?: string;
+}
+
+/** 筛选任务参数 */
+export interface FilterTasksParams {
+  projectIds?: string[];
+  startDate?: string;
+  endDate?: string;
+  priority?: number[];
+  tag?: string[];
+  status?: number[];
+}
+
+/** 批量任务操作参数 */
+export interface BatchTasksParams {
+  add?: CreateTaskParams[];
+  update?: UpdateTaskParams[];
+}
+
+/** 用户偏好 */
+export interface UserPreference {
+  timeZone?: string;
+  dateFormat?: string;
+  timeFormat?: string;
+  weekStartDay?: string;
+  language?: string;
+  [key: string]: unknown;
+}

package/src/utils/config.ts

@@ -0,0 +1,88 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import type { AppConfig, OAuthConfig, Region, TokenData } from '../types.js';
+
+/** 配置目录，可通过环境变量覆盖（测试用） */
+function getConfigDir(): string {
+  return process.env.TT_CLI_CONFIG_DIR ?? path.join(os.homedir(), '.tt-cli');
+}
+
+const CONFIG_FILE = 'config.json';
+
+function getConfigPath(): string {
+  return path.join(getConfigDir(), CONFIG_FILE);
+}
+
+function ensureConfigDir(): void {
+  const dir = getConfigDir();
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function readConfig(): AppConfig {
+  const configPath = getConfigPath();
+  if (!fs.existsSync(configPath)) return {};
+  return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+}
+
+function writeConfig(config: AppConfig): void {
+  ensureConfigDir();
+  fs.writeFileSync(getConfigPath(), JSON.stringify(config, null, 2));
+}
+
+/** 读取区域设置，默认国内版 */
+export function getRegion(): Region {
+  return readConfig().region ?? 'cn';
+}
+
+/** 保存区域设置 */
+export function setRegion(region: Region): void {
+  const config = readConfig();
+  config.region = region;
+  writeConfig(config);
+}
+
+/** 读取 OAuth 凭证 */
+export function getOAuth(): OAuthConfig | undefined {
+  return readConfig().oauth;
+}
+
+/** 保存 OAuth 凭证（同时记录当前区域） */
+export function setOAuth(oauth: OAuthConfig): void {
+  const config = readConfig();
+  config.oauth = { ...oauth, region: getRegion() };
+  writeConfig(config);
+}
+
+/** 获取凭证所属区域 */
+export function getOAuthRegion(): Region | undefined {
+  return readConfig().oauth?.region;
+}
+
+/** 读取 Token */
+export function getToken(): TokenData | undefined {
+  return readConfig().token;
+}
+
+/** 保存 Token */
+export function setToken(token: TokenData): void {
+  const config = readConfig();
+  config.token = token;
+  writeConfig(config);
+}
+
+/** 清除 Token（保留 OAuth 凭证） */
+export function clearToken(): void {
+  const config = readConfig();
+  delete config.token;
+  writeConfig(config);
+}
+
+/** Token 是否有效（未过期且剩余 > 5 分钟） */
+export function isTokenValid(): boolean {
+  const token = getToken();
+  if (!token) return false;
+  return Date.now() < token.expiresAt - 5 * 60 * 1000;
+}

package/src/utils/endpoints.ts

@@ -0,0 +1,22 @@
+import type { Region, RegionEndpoints } from '../types.js';
+
+/** 区域接口地址映射 */
+const ENDPOINTS: Record<Region, RegionEndpoints> = {
+  cn: {
+    authUrl: 'https://dida365.com/oauth/authorize',
+    tokenUrl: 'https://dida365.com/oauth/token',
+    apiBase: 'https://api.dida365.com/open/v1/',
+    developerUrl: 'https://developer.dida365.com/app',
+  },
+  global: {
+    authUrl: 'https://ticktick.com/oauth/authorize',
+    tokenUrl: 'https://ticktick.com/oauth/token',
+    apiBase: 'https://api.ticktick.com/open/v1/',
+    developerUrl: 'https://developer.ticktick.com/app',
+  },
+};
+
+/** 获取指定区域的接口地址 */
+export function getEndpoints(region: Region): RegionEndpoints {
+  return ENDPOINTS[region];
+}

package/src/utils/format.ts

@@ -0,0 +1,71 @@
+/**
+ * 任务时间格式化工具
+ */
+
+/**
+ * 规范化日期字符串为 TickTick API 要求的格式
+ * TickTick API 要求: "2026-04-04T19:00:00.000+0800"（有毫秒，时区无冒号）
+ *
+ * 支持输入格式:
+ * - "2026-04-04T19:00:00+08:00" → "2026-04-04T19:00:00.000+0800"
+ * - "2026-04-04T19:00:00Z"      → "2026-04-04T19:00:00.000+0000"
+ * - "2026-04-04T19:00:00.123+0800" → 保持不变
+ */
+export function normalizeTickTickDate(dateStr: string): string {
+  let result = dateStr;
+  // 补毫秒: "T19:00:00+" → "T19:00:00.000+"
+  if (!/T\d{2}:\d{2}:\d{2}\.\d{3}/.test(result)) {
+    result = result.replace(/(T\d{2}:\d{2}:\d{2})([+\-Z])/, '$1.000$2');
+  }
+  // 去时区冒号: "+08:00" → "+0800"
+  result = result.replace(/([+\-])(\d{2}):(\d{2})$/, '$1$2$3');
+  // "Z" → "+0000"
+  if (result.endsWith('Z')) {
+    result = result.slice(0, -1) + '+0000';
+  }
+  return result;
+}
+
+/** 从 TickTick ISO 8601 日期字符串提取本地时间的 HH:mm */
+function extractHM(dateStr: string): string | null {
+  // TickTick 返回格式如 "2026-04-04T14:15:00+0000" 或 "2026-04-04T14:15:00+08:00"
+  // API 返回 UTC 时间，需转换为本地时间显示
+  try {
+    const d = new Date(dateStr);
+    if (isNaN(d.getTime())) return null;
+    const hours = d.getHours().toString().padStart(2, '0');
+    const minutes = d.getMinutes().toString().padStart(2, '0');
+    return `${hours}:${minutes}`;
+  } catch {
+    // 回退：直接从字符串提取 HH:mm
+    const match = dateStr.match(/T(\d{2}):(\d{2})/);
+    if (!match) return null;
+    return `${match[1]}:${match[2]}`;
+  }
+}
+
+/**
+ * 格式化任务时间范围，用于表格显示
+ * - 全天任务显示 "全天"
+ * - 有起止时间显示 "HH:mm-HH:mm"
+ * - 仅有开始时间显示 "HH:mm"
+ * - 无时间显示空字符串
+ */
+export function formatTaskTime(task: {
+  startDate?: string;
+  dueDate?: string;
+  isAllDay?: boolean;
+}): string {
+  if (task.isAllDay && task.startDate) return '全天';
+  if (!task.startDate) return '';
+
+  const start = extractHM(task.startDate);
+  if (!start) return '';
+
+  if (task.dueDate) {
+    const end = extractHM(task.dueDate);
+    if (end && end !== start) return `${start}-${end}`;
+  }
+
+  return start;
+}

package/src/utils/server.ts

@@ -0,0 +1,81 @@
+import http from 'http';
+
+interface CallbackResult {
+  code: string;
+  close: () => void;
+}
+
+/**
+ * 创建临时本地 HTTP 服务器，等待 OAuth2 回调
+ * 返回 Promise，在收到合法回调时 resolve，超时 2 分钟后 reject
+ */
+export function createCallbackServer(
+  expectedState: string,
+  port: number
+): Promise<CallbackResult> {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url!, `http://localhost:${port}`);
+
+      if (url.pathname !== '/callback') {
+        res.writeHead(404);
+        res.end('Not found');
+        return;
+      }
+
+      const code = url.searchParams.get('code');
+      const state = url.searchParams.get('state');
+
+      if (state !== expectedState) {
+        res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end('<h1>授权失败：state 不匹配</h1>');
+        if (!settled) { settled = true; reject(new Error('CSRF state 不匹配')); }
+        server.close();
+        return;
+      }
+
+      if (!code) {
+        res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end('<h1>授权失败：缺少 code 参数</h1>');
+        if (!settled) { settled = true; reject(new Error('缺少授权码')); }
+        server.close();
+        return;
+      }
+
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end('<html><body style="display:flex;justify-content:center;align-items:center;height:100vh;font-family:sans-serif"><h1>✅ 授权成功！请返回终端。</h1></body></html>');
+
+      if (!settled) {
+        settled = true;
+        resolve({
+          code,
+          close: () => server.close(),
+        });
+      }
+    });
+
+    server.on('error', (err: NodeJS.ErrnoException) => {
+      if (!settled) {
+        settled = true;
+        if (err.code === 'EADDRINUSE') {
+          reject(new Error(`端口 ${port} 已被占用，请关闭占用该端口的程序或等待重试`));
+        } else {
+          reject(err);
+        }
+      }
+    });
+
+    server.listen(port);
+
+    // 2 分钟超时
+    setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        server.close();
+        reject(new Error('TIMEOUT'));
+      }
+    }, 120_000);
+  });
+}

package/tests/config.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, beforeEach, afterEach, expect } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+// 测试用临时目录，避免污染真实配置
+const TEST_DIR = path.join(os.tmpdir(), 'tt-cli-test-' + process.pid);
+
+let config: typeof import('../src/utils/config.js');
+
+beforeEach(async () => {
+  fs.mkdirSync(TEST_DIR, { recursive: true });
+  process.env.TT_CLI_CONFIG_DIR = TEST_DIR;
+  const mod = await import('../src/utils/config.js?' + Date.now());
+  config = mod;
+});
+
+afterEach(() => {
+  fs.rmSync(TEST_DIR, { recursive: true, force: true });
+  delete process.env.TT_CLI_CONFIG_DIR;
+});
+
+describe('config module', () => {
+  it('无配置时应返回 undefined', () => {
+    expect(config.getOAuth()).toBeUndefined();
+    expect(config.getToken()).toBeUndefined();
+  });
+
+  it('应正确保存和读取 OAuth 凭证', () => {
+    const oauth = { clientId: 'test-id', clientSecret: 'test-secret' };
+    config.setOAuth(oauth);
+    const result = config.getOAuth();
+    expect(result).toMatchObject(oauth);
+  });
+
+  it('应正确保存和读取 Token', () => {
+    const token = {
+      accessToken: 'access-123',
+      refreshToken: 'refresh-456',
+      expiresAt: Date.now() + 3600000,
+    };
+    config.setToken(token);
+    const result = config.getToken();
+    expect(result).toEqual(token);
+  });
+
+  it('未过期 token 应判定为有效', () => {
+    config.setToken({
+      accessToken: 'access',
+      refreshToken: 'refresh',
+      expiresAt: Date.now() + 600000,
+    });
+    expect(config.isTokenValid()).toBe(true);
+  });
+
+  it('即将过期（5 分钟内）应判定为无效', () => {
+    config.setToken({
+      accessToken: 'access',
+      refreshToken: 'refresh',
+      expiresAt: Date.now() + 240000,
+    });
+    expect(config.isTokenValid()).toBe(false);
+  });
+
+  it('无 token 应判定为无效', () => {
+    expect(config.isTokenValid()).toBe(false);
+  });
+
+  it('clearToken 应只删除 token 保留 oauth', () => {
+    config.setOAuth({ clientId: 'id', clientSecret: 'secret' });
+    config.setToken({
+      accessToken: 'a',
+      refreshToken: 'r',
+      expiresAt: Date.now() + 3600000,
+    });
+    config.clearToken();
+    expect(config.getToken()).toBeUndefined();
+    expect(config.getOAuth()).toMatchObject({ clientId: 'id', clientSecret: 'secret' });
+  });
+
+  it('配置应写入 JSON 文件', () => {
+    config.setOAuth({ clientId: 'id', clientSecret: 'secret' });
+    const configPath = path.join(TEST_DIR, 'config.json');
+    const content = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    expect(content.oauth).toMatchObject({ clientId: 'id', clientSecret: 'secret' });
+  });
+});