@wangjs-jacky/ticktick-cli 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/.github/workflows/npm-publish.yml +26 -0
  2. package/CLAUDE.md +34 -0
  3. package/README.md +62 -0
  4. package/README_CN.md +62 -0
  5. package/bin/cli.ts +2 -0
  6. package/dist/index.d.ts +2 -0
  7. package/dist/index.js +1490 -0
  8. package/dist/index.js.map +1 -0
  9. package/docs/oauth-credential-pre-validation.md +253 -0
  10. package/docs/reference/cli-usage-guide.md +587 -0
  11. package/docs/reference/dida365-open-api-zh.md +999 -0
  12. package/docs/reference/dida365-open-api.md +999 -0
  13. package/docs/reference/project-guide.md +63 -0
  14. package/docs/superpowers/plans/2026-04-03-tt-cli-auth.md +1110 -0
  15. package/docs/superpowers/specs/2026-04-03-tt-cli-design.md +142 -0
  16. package/package.json +45 -0
  17. package/skills/tt-cli-guide/SKILL.md +152 -0
  18. package/skills/tt-cli-guide/references/intent-mapping.md +169 -0
  19. package/src/api/client.ts +61 -0
  20. package/src/api/oauth.ts +146 -0
  21. package/src/api/resources.ts +291 -0
  22. package/src/commands/auth.ts +218 -0
  23. package/src/commands/project.ts +303 -0
  24. package/src/commands/task.ts +806 -0
  25. package/src/commands/user.ts +43 -0
  26. package/src/index.ts +46 -0
  27. package/src/types.ts +211 -0
  28. package/src/utils/config.ts +88 -0
  29. package/src/utils/endpoints.ts +22 -0
  30. package/src/utils/format.ts +71 -0
  31. package/src/utils/server.ts +81 -0
  32. package/tests/config.test.ts +87 -0
  33. package/tests/format.test.ts +56 -0
  34. package/tests/oauth.test.ts +42 -0
  35. package/tests/parity-fields.test.ts +89 -0
  36. package/tests/parity-map.ts +184 -0
  37. package/tests/parity.test.ts +101 -0
  38. package/tsconfig.json +22 -0
  39. package/tsup.config.ts +12 -0
  40. package/vitest.config.ts +7 -0
package/docs/reference/project-guide.md ADDED
@@ -0,0 +1,63 @@
1
+ # tt-cli 项目开发指南
2
+
3
+ 滴答清单（TickTick）命令行工具，支持国内版（dida365.com）和国际版（ticktick.com）双区域。
4
+
5
+ ## 技术栈
6
+
7
+ | 类别 | 方案 |
8
+ |------|------|
9
+ | CLI 框架 | `cac` |
10
+ | 终端 UI | `@clack/prompts` + `picocolors` |
11
+ | 构建 | `tsup`（ESM only，target node18） |
12
+ | 测试 | `vitest`（globals 模式） |
13
+ | 运行时 | Node.js 18+，ESM 模块 |
14
+
15
+ ## 常用命令
16
+
17
+ ```bash
18
+ npm run build # 构建（tsup → dist/）
19
+ npm run dev # 监听模式构建
20
+ npm test # 运行测试
21
+ npm run test:watch # 监听模式测试
22
+ ```
23
+
24
+ ## 项目结构
25
+
26
+ ```
27
+ src/
28
+ index.ts # CLI 入口，cac 命令注册
29
+ types.ts # 类型定义（OAuthConfig, TokenData, Region, AppConfig）
30
+ commands/
31
+ auth.ts # 认证命令：login / logout / whoami / config
32
+ api/
33
+ client.ts # API 客户端，自动刷新 Token
34
+ oauth.ts # OAuth2 流程：授权 URL 构建、code 换 token、刷新
35
+ utils/
36
+ config.ts # 配置读写（~/.tt-cli/config.json）
37
+ endpoints.ts # 区域接口地址映射（cn / global）
38
+ server.ts # OAuth 回调本地 HTTP 服务器（端口 3000）
39
+ ```
40
+
41
+ ## 配置存储
42
+
43
+ - 配置目录：`~/.tt-cli/`（测试时通过 `TT_CLI_CONFIG_DIR` 环境变量覆盖）
44
+ - 配置文件：`~/.tt-cli/config.json`，包含 `oauth`（凭证）、`token`（访问令牌）、`region`（区域）
45
+
46
+ ## 区域系统
47
+
48
+ 通过 `tt config --region cn|global` 切换区域。切换区域会清除 Token，需要重新登录。凭证与区域绑定，登录时会检测不匹配并引导用户处理。
49
+
50
+ ## cac 子命令机制
51
+
52
+ > **关键约束**：`cac` v7 不支持空格分隔的子命令名（如 `'task list'`），解析时只匹配第一个词 `task`，找不到命令则静默退出。
53
+
54
+ - 命令注册使用连字符格式：`'task-list'`、`'project-create'` 等
55
+ - `index.ts` 中预处理 argv：`task list` → `task-list`，用户仍可输入 `tt task list`
56
+ - **新增子命令时必须同时更新两处**：`registerXxxCommands` 中的命令名 + `index.ts` 的 `SUBCOMMAND_GROUPS`
57
+
58
+ ## 参考文档
59
+
60
+ - [CLI 操作手册](cli-usage-guide.md)：所有已实现命令的完整用法、参数说明、输出示例与速查表
61
+ - [OAuth 2.0 认证架构设计](../oauth-credential-pre-validation.md)：授权码模式完整流程、双区域架构、Token 管理与安全设计
62
+ - [滴答清单 Open API 文档（中文）](dida365-open-api-zh.md)：官方 Open API 接口参考
63
+ - [TickTick Open API 文档（英文）](dida365-open-api.md)：官方 Open API 接口参考（英文版）