@walknpm/todo-cli 1.1.0 → 2.0.0

package/README.md

@@ -2,10 +2,11 @@
 
 > **English** | [简体中文](./README.zh-CN.md)
 
-A zero-dependency Node.js CLI todo list manager. Full CRUD, completion toggle,
-categories/tags, priority sorting, due dates with overdue highlighting, search,
-statistics, and export (JSON / CSV / Markdown). Data persists to
-`~/.todo-cli/todos.json`.
+A zero-dependency Node.js todo list manager with **CLI + Web UI**. Full CRUD,
+subtasks, recurring tasks, dependencies, time tracking, pinning, bulk operations,
+categories/tags, priority sorting, due dates, search, statistics, kanban board,
+calendar view, timeline, export (JSON / CSV / Markdown), and auto-update.
+Data persists to `~/.todo-cli/todos.json`.
 
 ## Requirements
 
@@ -13,190 +14,256 @@ statistics, and export (JSON / CSV / Markdown). Data persists to
 
 ## Quick install
 
+**Via npm:**
+
+```bash
+npm install -g @walknpm/todo-cli
+todo --version   # → todo v2.0.0
+```
+
+**Via git:**
+
 ```bash
 git clone https://gitcode.com/hw_aishell_projects/todo_cli.git
 cd todo_cli
 npm install -g .
-todo --version   # → todo v1.0.0
+todo --version   # → todo v2.0.0
 ```
 
-## Commands
-
-| Command               | Description                                        |
-| --------------------- | -------------------------------------------------- |
-| `add <title>`         | Add a new todo                                     |
-| `list`                | List todos (default command)                       |
-| `done <id>`           | Mark a todo as done (`done --all` = complete all)  |
-| `toggle <id>`         | Toggle done / pending                              |
-| `edit <id>`           | Edit a todo                                        |
-| `delete <id>`         | Delete a todo                                      |
-| `search <keyword>`    | Search title / tags / category / note              |
-| `stats`               | Show summary statistics                            |
-| `export [json\|csv\|md]` | Export all todos to stdout                       |
-| `archive`             | Remove all completed todos                         |
-| `update`              | Update todo-cli to latest (`--check` = check only) |
-| `clear`               | Remove ALL todos                                   |
-| `help`                | Show help                                          |
-
-`-h` / `--help` can be appended to **any** command (or used alone) to show help.
-`-v` / `--version` prints the version.
+## 🚀 Web UI
 
-## Flags
-
-| Flag                    | Applies to       | Description                                |
-| ----------------------- | ---------------- | ------------------------------------------ |
-| `-p, --priority <v>`    | add, edit        | `high` \| `medium` \| `low` (default: medium) |
-| `-t, --tags <v>`        | add, edit        | Comma-separated tags                       |
-| `-c, --category <v>`    | add, edit        | Category name                              |
-| `-d, --due <v>`         | add, edit        | Due date `YYYY-MM-DD`                      |
-| `--note <v>`            | add, edit        | Longer note / description                  |
-| `--title <v>`           | edit             | New title                                  |
-| `--status <v>`          | list             | `all` \| `done` \| `pending`               |
-| `--tag <v>`             | list             | Filter by tag                              |
-| `--sort <v>`            | list             | `priority` \| `created` \| `due` \| `id`   |
-| `--all`                 | done             | Complete all pending                       |
-| `--check`               | update           | Check for update without installing        |
-| `--format <v>`          | export           | `json` \| `csv` \| `md` (default: json)    |
-
-## Examples
+Start the web server with:
 
 ```bash
-# Add with due date, priority, tags, category, and note
-todo add "Submit tax return" -p high -d 2025-01-31 -c finance -t urgent,monthly --note "Include receipts"
+todo web              # default port 3456
+todo web 8080         # custom port
+npm run web           # via npm script
+```
 
-# List & filter
-todo list
-todo list --status pending --sort due
-todo list --category work --priority high
+Then open **http://localhost:3456** in your browser.
 
-# Search
-todo search tax
+### Web UI Features
 
-# Bulk complete & archive
-todo done --all
-todo archive
+| Feature | Description |
+| ------- | ----------- |
+| **Dashboard** | Stats cards, completion rate, recent todos, upcoming deadlines |
+| **List View** | Full todo list with inline actions, filtering, sorting, search |
+| **Kanban Board** | Drag-and-drop between Pending and Done columns |
+| **Calendar** | Monthly calendar with todos mapped to due dates |
+| **Timeline** | Chronological activity feed of all todos |
+| **Add/Edit Modal** | Full form with all fields including recurrence and pinning |
+| **Detail View** | Subtask management, dependencies, timestamps, quick actions |
+| **Time Tracking** | Start/stop timers with floating timer widget |
+| **Dark/Light Theme** | Toggle with persistence via localStorage |
+| **Responsive** | Works on desktop, tablet, and mobile |
+| **Keyboard Shortcuts** | `n` = new todo, `/` = search, `Esc` = close modal |
 
-# Statistics
-todo stats
+## Commands
 
-# Auto-update
-todo update --check   # check for updates
-todo update           # install latest version
+### Core Commands
+
+| Command | Description |
+| ------- | ----------- |
+| `add <title>` | Add a new todo |
+| `list` | List todos (default command) |
+| `show <id>` | Show detailed info for a todo |
+| `done <id>` | Mark a todo as done (`done --all` = complete all) |
+| `toggle <id>` | Toggle done / pending |
+| `edit <id>` | Edit a todo |
+| `delete <id>` | Delete a todo (alias: `rm`, `remove`) |
+| `duplicate <id>` | Clone a todo (alias: `dup`) |
+| `pin <id>` | Toggle pin status |
+| `search <keyword>` | Search title / tags / category / note / assignee |
+| `stats` | Show summary statistics |
+| `export [json\|csv\|md]` | Export all todos to stdout |
+| `archive` | Remove all completed todos |
+| `clear` | Remove ALL todos |
+| `web [port]` | Start the web UI server (default: 3456) |
+| `update` | Update todo-cli to latest (`--check` = check only) |
+| `help` | Show help |
+
+### Subtasks
 
-# Export
-todo export csv > todos.csv
-todo export md
+```bash
+todo subtask add <id> <title>        # Add a subtask
+todo subtask done <id> <sid>         # Toggle subtask done
+todo subtask edit <id> <sid> <title> # Edit subtask title
+todo subtask delete <id> <sid>       # Delete a subtask
 ```
 
-## Project structure
+### Recurring Tasks
 
-```
-todo_cli/
-├── bin/
-│   └── todo.js        # executable entry point (shebang)
-├── src/
-│   ├── store.js       # JSON file persistence layer
-│   ├── todo.js        # domain logic (CRUD, search, stats, export, ...)
-│   └── cli.js         # command parsing, ANSI colours, table output
-├── package.json
-├── README.md          # English documentation
-└── README.zh-CN.md    # Chinese documentation
+```bash
+todo recur <id> daily   [interval]   # Repeat every N days
+todo recur <id> weekly  [interval]   # Repeat every N weeks
+todo recur <id> monthly [interval]   # Repeat every N months
+todo recur <id> yearly  [interval]   # Repeat every N years
+todo recur <id> off                  # Remove recurrence
 ```
 
----
+When a recurring todo is completed, a new pending instance is automatically
+created with the due date advanced by the recurrence interval.
 
-## 🤖 AI 自动部署提示词
+### Dependencies
 
-> 以下提示词可直接粘贴给 AI 助手（如 Claude、ChatGPT、DeepSeek 等），AI 会自动完成部署。
-> 复制对应场景的代码块即可。
+```bash
+todo dep add <id> <depId>     # Add dependency (blocks completion)
+todo dep remove <id> <depId>  # Remove dependency
+```
 
-### 场景一：从零安装并验证
+### Time Tracking
 
-```
-请帮我安装部署 todo-cli 命令行待办工具，步骤如下：
-
-1. 克隆仓库：git clone https://gitcode.com/hw_aishell_projects/todo_cli.git
-2. 进入目录：cd todo_cli
-3. 全局安装：npm install -g .
-4. 验证安装：运行 todo --version，确认输出 "todo v1.0.0"
-5. 功能验证：依次执行以下命令并确认每步输出正常：
-   - todo add "部署测试任务" -p high -t test -c verify
-   - todo list
-   - todo done 1
-   - todo stats
-   - todo clear
-6. 如果任何步骤报错，请展示完整错误信息并尝试修复。
-
-完成后告诉我安装路径和 todo --version 的输出。
+```bash
+todo timer start <id>         # Start timer (stops any other running timer)
+todo timer stop <id>          # Stop timer and log elapsed time
+todo timer log <id> <minutes> # Manually log time
+todo timer                    # Show active timer
 ```
 
-### 场景二：安装 + 导入已有数据
+### Bulk Operations
 
+```bash
+todo bulk done <ids...>              # Complete multiple todos
+todo bulk delete <ids...>            # Delete multiple todos
+todo bulk priority <ids...> -p <val> # Set priority on multiple todos
+todo bulk category <ids...> -c <val> # Set category on multiple todos
+todo bulk assign <ids...> --assignee <val>  # Set assignee on multiple todos
 ```
-请帮我部署 todo-cli 并导入已有待办数据：
 
-1. 克隆并安装：
-   git clone https://gitcode.com/hw_aishell_projects/todo_cli.git
-   cd todo_cli && npm install -g .
+## Flags
 
-2. 确认 todo --version 正常输出。
+| Flag | Applies to | Description |
+| ---- | ---------- | ----------- |
+| `-p, --priority <v>` | add, edit | `high` \| `medium` \| `low` (default: medium) |
+| `-t, --tags <v>` | add, edit | Comma-separated tags |
+| `-c, --category <v>` | add, edit | Category name |
+| `-d, --due <v>` | add, edit | Due date `YYYY-MM-DD` |
+| `--note <v>` | add, edit | Longer note / description |
+| `--title <v>` | edit | New title |
+| `--assignee <v>` | add, edit | Assign to a person |
+| `--estimate <v>` | add, edit | Estimated minutes to complete |
+| `--color <v>` | add, edit | Custom color label |
+| `--status <v>` | list | `all` \| `done` \| `pending` |
+| `--tag <v>` | list | Filter by tag |
+| `--sort <v>` | list | `priority` \| `created` \| `due` \| `id` \| `title` \| `updated` \| `order` |
+| `--pinned` | add | Pin the new todo |
+| `--overdue` | list | Show only overdue items |
+| `--due-today` | list | Show only items due today |
+| `--all` | done | Complete all pending |
+| `--check` | update | Check for update without installing |
+| `--format <v>` | export | `json` \| `csv` \| `md` (default: json) |
 
-3. 以下是我的待办事项，请逐条用 todo add 命令创建（根据内容自动判断优先级、分类和标签）：
-   - [在此粘贴你的待办列表，每行一条]
+## Examples
 
-4. 创建完成后运行 todo list 和 todo stats，把结果展示给我确认。
-```
+```bash
+# Add with all fields
+todo add "Submit tax return" -p high -d 2025-01-31 -c finance -t urgent,monthly --note "Include receipts" --estimate 120 --assignee bob
 
-### 场景三：卸载
+# List & filter
+todo list --status pending --sort due
+todo list --overdue
+todo list --category work --priority high
 
-```
-请帮我卸载 todo-cli 工具：
+# Subtasks
+todo subtask add 1 "Research options"
+todo subtask add 1 "Write draft"
+todo subtask done 1 1
 
-1. 运行 npm uninstall -g todo-cli
-2. 删除数据文件：rm -rf ~/.todo-cli
-3. 运行 todo --version 确认已无法找到该命令
-4. 告诉我卸载是否成功。
-```
+# Recurring
+todo recur 3 weekly 1
+todo done 3   # creates a new instance for next week
 
-### 场景四：更新到最新版本
+# Dependencies
+todo dep add 5 3   # todo #5 is blocked until #3 is done
 
-```
-请帮我更新 todo-cli 到最新版本：
+# Time tracking
+todo timer start 2
+todo timer stop 2
+todo timer log 2 30
 
-1. 运行 todo update --check 检查是否有新版本
-2. 如果有更新，运行 todo update 自动安装最新版
-3. 运行 todo --version 确认版本号已更新
-4. 运行 todo list 确认已有数据未丢失
-5. 告诉我更新结果。
-```
+# Pin & duplicate
+todo pin 1
+todo duplicate 3
 
-### 场景五：完整部署（含数据备份与恢复）
+# Bulk operations
+todo bulk done 1 2 3
+todo bulk priority 1 2 3 -p high
 
-```
-请帮我完成 todo-cli 的完整部署流程：
+# Web UI
+todo web 8080
 
-【安装】
-1. git clone https://gitcode.com/hw_aishell_projects/todo_cli.git
-2. cd todo_cli && npm install -g .
-3. 确认 todo --version 输出版本号
+# Statistics
+todo stats
 
-【备份】（如果 ~/.todo-cli/todos.json 已存在）
-4. 如果存在 ~/.todo-cli/todos.json，先备份到 ~/todo-backup-$(date +%Y%m%d).json
-5. 确认备份文件内容有效
+# Export
+todo export csv > todos.csv
+todo export md
 
-【验证】
-6. 执行 todo add "验证任务" -p medium 并确认输出
-7. 执行 todo list 确认表格正常显示
-8. 执行 todo delete 1 清理验证数据
+# Auto-update
+todo update --check
+todo update
+```
 
-【恢复】（如果有备份）
-9. 如果之前做了备份，将备份文件复制回 ~/.todo-cli/todos.json
-10. 执行 todo list 确认数据已恢复
+## Project structure
 
-最后汇总报告：安装状态、版本号、备份/恢复状态。
+```
+todo_cli/
+├── bin/
+│   └── todo.js            # executable entry point (shebang)
+├── src/
+│   ├── store.js           # JSON file persistence layer
+│   ├── todo.js            # domain logic (CRUD, subtasks, recurring, deps, timer, bulk, ...)
+│   ├── cli.js             # command parsing, ANSI colours, table output
+│   └── server.js          # zero-dependency HTTP server (REST API + static files)
+├── web/
+│   ├── index.html         # SPA shell
+│   ├── css/
+│   │   └── style.css      # modern responsive design (dark/light themes)
+│   └── js/
+│       └── app.js         # SPA application logic (dashboard, list, kanban, calendar, timeline)
+├── skill/
+│   ├── SKILL.md           # DSH skill instructions
+│   ├── README.md          # skill documentation
+│   └── CHANGELOG.md       # skill changelog
+├── package.json
+├── README.md              # English documentation
+└── README.zh-CN.md        # Chinese documentation
 ```
 
----
+## REST API
+
+The web server exposes a REST API at `/api/`:
+
+| Method | Endpoint | Description |
+| ------ | -------- | ----------- |
+| GET | `/api/todos` | List all todos (supports query filters) |
+| POST | `/api/todos` | Create a new todo |
+| GET | `/api/todos/:id` | Get a single todo |
+| PATCH | `/api/todos/:id` | Edit a todo |
+| DELETE | `/api/todos/:id` | Delete a todo |
+| POST | `/api/todos/:id/toggle` | Toggle done status |
+| POST | `/api/todos/:id/complete` | Mark as done |
+| POST | `/api/todos/:id/pin` | Toggle pin |
+| POST | `/api/todos/:id/duplicate` | Duplicate a todo |
+| POST | `/api/todos/:id/reorder` | Reorder a todo |
+| POST | `/api/todos/:id/subtasks` | Add a subtask |
+| POST | `/api/todos/:id/subtasks/:sid/toggle` | Toggle subtask |
+| PATCH | `/api/todos/:id/subtasks/:sid` | Edit subtask |
+| DELETE | `/api/todos/:id/subtasks/:sid` | Delete subtask |
+| POST | `/api/todos/:id/recurring` | Set/remove recurrence |
+| POST | `/api/todos/:id/dependencies` | Add dependency |
+| DELETE | `/api/todos/:id/dependencies/:depId` | Remove dependency |
+| POST | `/api/todos/:id/timer/start` | Start timer |
+| POST | `/api/todos/:id/timer/stop` | Stop timer |
+| POST | `/api/todos/:id/timer/log` | Log time manually |
+| GET | `/api/stats` | Get statistics |
+| GET | `/api/search?q=<keyword>` | Search todos |
+| GET | `/api/timer` | Get active timer |
+| POST | `/api/bulk` | Bulk operations |
+| POST | `/api/complete-all` | Complete all pending |
+| POST | `/api/archive` | Archive completed |
+| POST | `/api/clear` | Clear all |
+| GET | `/api/export?format=<fmt>` | Export todos |
 
 ## License