@walknpm/todo-cli 1.1.0

package/README.md

@@ -0,0 +1,203 @@
+# todo-cli
+
+> **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`.
+
+## Requirements
+
+- Node.js >= 18
+
+## Quick install
+
+```bash
+git clone https://gitcode.com/hw_aishell_projects/todo_cli.git
+cd todo_cli
+npm install -g .
+todo --version   # → todo v1.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.
+
+## 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
+
+```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"
+
+# List & filter
+todo list
+todo list --status pending --sort due
+todo list --category work --priority high
+
+# Search
+todo search tax
+
+# Bulk complete & archive
+todo done --all
+todo archive
+
+# Statistics
+todo stats
+
+# Auto-update
+todo update --check   # check for updates
+todo update           # install latest version
+
+# Export
+todo export csv > todos.csv
+todo export md
+```
+
+## Project structure
+
+```
+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
+```
+
+---
+
+## 🤖 AI 自动部署提示词
+
+> 以下提示词可直接粘贴给 AI 助手（如 Claude、ChatGPT、DeepSeek 等），AI 会自动完成部署。
+> 复制对应场景的代码块即可。
+
+### 场景一：从零安装并验证
+
+```
+请帮我安装部署 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 的输出。
+```
+
+### 场景二：安装 + 导入已有数据
+
+```
+请帮我部署 todo-cli 并导入已有待办数据：
+
+1. 克隆并安装：
+   git clone https://gitcode.com/hw_aishell_projects/todo_cli.git
+   cd todo_cli && npm install -g .
+
+2. 确认 todo --version 正常输出。
+
+3. 以下是我的待办事项，请逐条用 todo add 命令创建（根据内容自动判断优先级、分类和标签）：
+   - [在此粘贴你的待办列表，每行一条]
+
+4. 创建完成后运行 todo list 和 todo stats，把结果展示给我确认。
+```
+
+### 场景三：卸载
+
+```
+请帮我卸载 todo-cli 工具：
+
+1. 运行 npm uninstall -g todo-cli
+2. 删除数据文件：rm -rf ~/.todo-cli
+3. 运行 todo --version 确认已无法找到该命令
+4. 告诉我卸载是否成功。
+```
+
+### 场景四：更新到最新版本
+
+```
+请帮我更新 todo-cli 到最新版本：
+
+1. 运行 todo update --check 检查是否有新版本
+2. 如果有更新，运行 todo update 自动安装最新版
+3. 运行 todo --version 确认版本号已更新
+4. 运行 todo list 确认已有数据未丢失
+5. 告诉我更新结果。
+```
+
+### 场景五：完整部署（含数据备份与恢复）
+
+```
+请帮我完成 todo-cli 的完整部署流程：
+
+【安装】
+1. git clone https://gitcode.com/hw_aishell_projects/todo_cli.git
+2. cd todo_cli && npm install -g .
+3. 确认 todo --version 输出版本号
+
+【备份】（如果 ~/.todo-cli/todos.json 已存在）
+4. 如果存在 ~/.todo-cli/todos.json，先备份到 ~/todo-backup-$(date +%Y%m%d).json
+5. 确认备份文件内容有效
+
+【验证】
+6. 执行 todo add "验证任务" -p medium 并确认输出
+7. 执行 todo list 确认表格正常显示
+8. 执行 todo delete 1 清理验证数据
+
+【恢复】（如果有备份）
+9. 如果之前做了备份，将备份文件复制回 ~/.todo-cli/todos.json
+10. 执行 todo list 确认数据已恢复
+
+最后汇总报告：安装状态、版本号、备份/恢复状态。
+```
+
+---
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,202 @@
+# todo-cli
+
+> **简体中文** | [English](./README.md)
+
+一个零依赖的 Node.js 命令行待办事项管理器。支持完整的增删改查、完成状态切换、
+分类/标签、优先级排序、截止日期（含逾期高亮）、搜索、统计概览，以及导出
+（JSON / CSV / Markdown）。数据持久化到 `~/.todo-cli/todos.json`。
+
+## 环境要求
+
+- Node.js >= 18
+
+## 快速安装
+
+```bash
+git clone https://gitcode.com/hw_aishell_projects/todo_cli.git
+cd todo_cli
+npm install -g .
+todo --version   # → todo v1.0.0
+```
+
+## 命令一览
+
+| 命令                  | 说明                                               |
+| --------------------- | -------------------------------------------------- |
+| `add <标题>`          | 添加新待办                                         |
+| `list`                | 列出待办（默认命令）                               |
+| `done <id>`           | 标记完成（`done --all` = 全部完成）                |
+| `toggle <id>`         | 切换完成 / 待办状态                                |
+| `edit <id>`           | 编辑待办                                           |
+| `delete <id>`         | 删除待办                                           |
+| `search <关键词>`     | 搜索标题 / 标签 / 分类 / 备注                      |
+| `stats`               | 显示统计概览                                       |
+| `export [json\|csv\|md]` | 导出全部待办到标准输出                          |
+| `archive`             | 归档（删除所有已完成项）                           |
+| `update`              | 自动更新到最新版（`--check` = 仅检查不安装）       |
+| `clear`               | 清空所有待办                                       |
+| `help`                | 显示帮助                                           |
+
+`-h` / `--help` 可附加在**任意命令**后（或单独使用）显示帮助。
+`-v` / `--version` 显示版本号。
+
+## 参数标志
+
+| 标志                   | 适用命令         | 说明                                       |
+| ---------------------- | ---------------- | ------------------------------------------ |
+| `-p, --priority <v>`   | add, edit        | `high` \| `medium` \| `low`（默认: medium） |
+| `-t, --tags <v>`       | add, edit        | 逗号分隔的标签                             |
+| `-c, --category <v>`   | add, edit        | 分类名称                                   |
+| `-d, --due <v>`        | add, edit        | 截止日期 `YYYY-MM-DD`                      |
+| `--note <v>`           | add, edit        | 较长的备注 / 描述                          |
+| `--title <v>`          | edit             | 新标题                                     |
+| `--status <v>`         | list             | `all` \| `done` \| `pending`               |
+| `--tag <v>`            | list             | 按标签过滤                                 |
+| `--sort <v>`           | list             | `priority` \| `created` \| `due` \| `id`   |
+| `--all`                | done             | 完成所有待办项                             |
+| `--check`              | update           | 仅检查是否有更新，不安装                    |
+| `--format <v>`         | export           | `json` \| `csv` \| `md`（默认: json）      |
+
+## 使用示例
+
+```bash
+# 添加待办（含截止日期、优先级、标签、分类、备注）
+todo add "提交报税单" -p high -d 2025-01-31 -c finance -t urgent,monthly --note "附上收据"
+
+# 列出与过滤
+todo list
+todo list --status pending --sort due
+todo list --category work --priority high
+
+# 搜索
+todo search 报税
+
+# 批量完成与归档
+todo done --all
+todo archive
+
+# 统计概览
+todo stats
+
+# 自动更新
+todo update --check   # 检查是否有新版本
+todo update           # 安装最新版本
+
+# 导出
+todo export csv > todos.csv
+todo export md
+```
+
+## 项目结构
+
+```
+todo_cli/
+├── bin/
+│   └── todo.js        # 可执行入口（shebang）
+├── src/
+│   ├── store.js       # JSON 文件持久化层
+│   ├── todo.js        # 领域逻辑（增删改查、搜索、统计、导出等）
+│   └── cli.js         # 命令解析、ANSI 彩色、表格输出
+├── package.json
+├── README.md          # 英文文档
+└── README.zh-CN.md    # 中文文档
+```
+
+---
+
+## 🤖 AI 自动部署提示词
+
+> 以下提示词可直接粘贴给 AI 助手（如 Claude、ChatGPT、DeepSeek 等），AI 会自动完成部署。
+> 复制对应场景的代码块即可。
+
+### 场景一：从零安装并验证
+
+```
+请帮我安装部署 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 的输出。
+```
+
+### 场景二：安装 + 导入已有数据
+
+```
+请帮我部署 todo-cli 并导入已有待办数据：
+
+1. 克隆并安装：
+   git clone https://gitcode.com/hw_aishell_projects/todo_cli.git
+   cd todo_cli && npm install -g .
+
+2. 确认 todo --version 正常输出。
+
+3. 以下是我的待办事项，请逐条用 todo add 命令创建（根据内容自动判断优先级、分类和标签）：
+   - [在此粘贴你的待办列表，每行一条]
+
+4. 创建完成后运行 todo list 和 todo stats，把结果展示给我确认。
+```
+
+### 场景三：卸载
+
+```
+请帮我卸载 todo-cli 工具：
+
+1. 运行 npm uninstall -g todo-cli
+2. 删除数据文件：rm -rf ~/.todo-cli
+3. 运行 todo --version 确认已无法找到该命令
+4. 告诉我卸载是否成功。
+```
+
+### 场景四：更新到最新版本
+
+```
+请帮我更新 todo-cli 到最新版本：
+
+1. 运行 todo update --check 检查是否有新版本
+2. 如果有更新，运行 todo update 自动安装最新版
+3. 运行 todo --version 确认版本号已更新
+4. 运行 todo list 确认已有数据未丢失
+5. 告诉我更新结果。
+```
+
+### 场景五：完整部署（含数据备份与恢复）
+
+```
+请帮我完成 todo-cli 的完整部署流程：
+
+【安装】
+1. git clone https://gitcode.com/hw_aishell_projects/todo_cli.git
+2. cd todo_cli && npm install -g .
+3. 确认 todo --version 输出版本号
+
+【备份】（如果 ~/.todo-cli/todos.json 已存在）
+4. 如果存在 ~/.todo-cli/todos.json，先备份到 ~/todo-backup-$(date +%Y%m%d).json
+5. 确认备份文件内容有效
+
+【验证】
+6. 执行 todo add "验证任务" -p medium 并确认输出
+7. 执行 todo list 确认表格正常显示
+8. 执行 todo delete 1 清理验证数据
+
+【恢复】（如果有备份）
+9. 如果之前做了备份，将备份文件复制回 ~/.todo-cli/todos.json
+10. 执行 todo list 确认数据已恢复
+
+最后汇总报告：安装状态、版本号、备份/恢复状态。
+```
+
+---
+
+## 开源协议
+
+MIT

package/bin/todo.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// bin/todo.js — executable entry point for the todo CLI.
+import { run } from "../src/cli.js";
+
+run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@walknpm/todo-cli",
+  "version": "1.1.0",
+  "description": "A zero-dependency Node.js CLI todo list manager with CRUD, due dates, search, stats, export, and auto-update.",
+  "type": "module",
+  "main": "src/cli.js",
+  "bin": {
+    "todo": "bin/todo.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node bin/todo.js"
+  },
+  "keywords": [
+    "todo",
+    "cli",
+    "task",
+    "productivity",
+    "todo-list",
+    "command-line"
+  ],
+  "author": "walknpm",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://gitcode.com/hw_aishell_projects/todo_cli.git"
+  },
+  "homepage": "https://gitcode.com/hw_aishell_projects/todo_cli",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "README.zh-CN.md"
+  ]
+}

package/src/cli.js

@@ -0,0 +1,419 @@
+// cli.js — command-line interface for the todo list.
+// Parses argv into commands, executes them against the domain + store,
+// and prints results with ANSI colours and a table layout.
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { execSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { createStore } from "./store.js";
+import {
+  addTodo,
+  editTodo,
+  deleteTodo,
+  toggleTodo,
+  completeTodo,
+  completeAll,
+  listTodos,
+  clearTodos,
+  searchTodos,
+  getStats,
+  archiveCompleted,
+  exportTodos,
+  dueStatus,
+  PRIORITIES,
+} from "./todo.js";
+
+// --- version & repo (read from package.json so they stay in sync) -----------
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const __pkg = JSON.parse(
+  fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")
+);
+const VERSION = __pkg.version;
+const REPO_URL = "https://gitcode.com/hw_aishell_projects/todo_cli.git";
+
+// --- ANSI colours (disabled when not a TTY) -------------------------------
+const useColor = process.stdout.isTTY;
+function c(code, str) {
+  return useColor ? `\x1b[${code}m${str}\x1b[0m` : str;
+}
+const green = (s) => c("32", s);
+const red = (s) => c("31", s);
+const yellow = (s) => c("33", s);
+const cyan = (s) => c("36", s);
+const bold = (s) => c("1", s);
+const dim = (s) => c("2", s);
+
+const PRIORITY_COLOR = { high: red, medium: yellow, low: green };
+
+// --- argument parsing ------------------------------------------------------
+/**
+ * Split argv into a positional list and a flags object.
+ * Flags: -p/--priority, -t/--tags, -c/--category, -d/--due, --note,
+ *        --title, --status, --tag, --sort, --all, --format
+ */
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-p" || a === "--priority") flags.priority = argv[++i];
+    else if (a === "-t" || a === "--tags") flags.tags = argv[++i];
+    else if (a === "-c" || a === "--category") flags.category = argv[++i];
+    else if (a === "-d" || a === "--due") flags.due = argv[++i];
+    else if (a === "--note") flags.note = argv[++i];
+    else if (a === "--title") flags.title = argv[++i];
+    else if (a === "--status") flags.status = argv[++i];
+    else if (a === "--tag") flags.tag = argv[++i];
+    else if (a === "--sort") flags.sort = argv[++i];
+    else if (a === "--format") flags.format = argv[++i];
+    else if (a === "--all") flags.all = true;
+    else if (a === "--check") flags.check = true;
+    else if (a === "-h" || a === "--help") flags.help = true;
+    else if (a.startsWith("-")) {
+      // unknown flag — ignore but don't swallow a value
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, flags };
+}
+
+// --- table rendering -------------------------------------------------------
+function pad(str, width) {
+  str = String(str);
+  return str.length >= width ? str : str + " ".repeat(width - str.length);
+}
+
+function renderTable(todos) {
+  if (todos.length === 0) {
+    console.log(dim("  (no todos)"));
+    return;
+  }
+  const hasDue = todos.some((t) => t.due);
+  const cols = hasDue
+    ? ["ID", "Status", "Priority", "Due", "Category", "Tags", "Title"]
+    : ["ID", "Status", "Priority", "Category", "Tags", "Title"];
+
+  function dueCell(t) {
+    if (!t.due) return "-";
+    const ds = dueStatus(t.due);
+    if (t.done) return dim(t.due);
+    if (ds === "overdue") return red(t.due);
+    if (ds === "today") return yellow(t.due);
+    if (ds === "soon") return yellow(t.due);
+    return t.due;
+  }
+
+  const rows = todos.map((t) => {
+    const base = [
+      String(t.id),
+      t.done ? green("✓") : dim("○"),
+      PRIORITY_COLOR[t.priority](t.priority),
+    ];
+    if (hasDue) base.push(dueCell(t));
+    base.push(
+      t.category || "-",
+      t.tags.length ? cyan(t.tags.join(", ")) : "-",
+      t.done ? dim(t.title) : t.title
+    );
+    return base;
+  });
+
+  const widths = cols.map((_, ci) =>
+    Math.max(cols[ci].length, ...rows.map((r) => r[ci].length))
+  );
+
+  const header = "  " + cols.map((h, i) => bold(pad(h, widths[i]))).join("  ");
+  console.log(header);
+  console.log("  " + dim("-".repeat(widths.reduce((a, w) => a + w + 2, -2))));
+  for (const row of rows) {
+    console.log("  " + row.map((cell, i) => pad(cell, widths[i])).join("  "));
+  }
+  console.log(dim(`\n  ${todos.length} item(s)`));
+}
+
+// --- commands --------------------------------------------------------------
+function cmdAdd(todos, { positional, flags }) {
+  const title = positional.join(" ");
+  const todo = addTodo(todos, {
+    title,
+    priority: flags.priority,
+    tags: flags.tags,
+    category: flags.category,
+    due: flags.due,
+    note: flags.note,
+  });
+  let msg = green("✓ Added:") + ` #${todo.id} ${todo.title}`;
+  if (todo.due) msg += dim(`  (due ${todo.due})`);
+  console.log(msg);
+}
+
+function cmdList(todos, { flags }) {
+  const result = listTodos(todos, {
+    status: flags.status,
+    category: flags.category,
+    tag: flags.tag,
+    priority: flags.priority,
+    sort: flags.sort,
+  });
+  renderTable(result);
+}
+
+function cmdDone(todos, { positional, flags }) {
+  if (flags.all) {
+    const n = completeAll(todos);
+    console.log(green(`✓ Marked ${n} pending item(s) as done`));
+    return;
+  }
+  const id = positional[0];
+  if (!id) {
+    console.log(red("✗ Usage: todo done <id>  (or todo done --all)"));
+    return;
+  }
+  const todo = completeTodo(todos, id);
+  if (!todo) console.log(red(`✗ No todo with id ${id}`));
+  else console.log(green("✓ Done:") + ` #${todo.id} ${todo.title}`);
+}
+
+function cmdToggle(todos, { positional }) {
+  const id = positional[0];
+  const todo = toggleTodo(todos, id);
+  if (!todo) console.log(red(`✗ No todo with id ${id}`));
+  else
+    console.log(
+      (todo.done ? green("✓ Done:") : yellow("◌ Reopened:")) +
+        ` #${todo.id} ${todo.title}`
+    );
+}
+
+function cmdEdit(todos, { positional, flags }) {
+  const id = positional[0];
+  const todo = editTodo(todos, id, {
+    title: flags.title,
+    priority: flags.priority,
+    tags: flags.tags,
+    category: flags.category,
+    due: flags.due,
+    note: flags.note,
+  });
+  if (!todo) console.log(red(`✗ No todo with id ${id}`));
+  else console.log(green("✓ Edited:") + ` #${todo.id} ${todo.title}`);
+}
+
+function cmdDelete(todos, { positional }) {
+  const id = positional[0];
+  const ok = deleteTodo(todos, id);
+  if (!ok) console.log(red(`✗ No todo with id ${id}`));
+  else console.log(green("✓ Deleted:") + ` #${id}`);
+}
+
+function cmdClear(todos) {
+  const n = clearTodos(todos);
+  console.log(green(`✓ Cleared ${n} item(s)`));
+}
+
+function cmdSearch(todos, { positional }) {
+  const keyword = positional.join(" ");
+  const results = searchTodos(todos, keyword);
+  console.log(bold(`Search:`) + ` "${keyword}" — ${results.length} match(es)`);
+  renderTable(results);
+}
+
+function cmdStats(todos) {
+  const s = getStats(todos);
+  console.log(bold("Todo Statistics"));
+  console.log(dim("─────────────────"));
+  console.log(`  Total:    ${s.total}`);
+  console.log(`  ${green("Done:")}    ${s.done}`);
+  console.log(`  ${yellow("Pending:")} ${s.pending}`);
+  if (s.overdue > 0) console.log(`  ${red("Overdue:")} ${s.overdue}`);
+  console.log(dim("\n  By priority:"));
+  console.log(`    ${red("high")}: ${s.byPriority.high}  ${yellow("medium")}: ${s.byPriority.medium}  ${green("low")}: ${s.byPriority.low}`);
+  const cats = Object.keys(s.byCategory);
+  if (cats.length) {
+    console.log(dim("  By category:"));
+    for (const c of cats.sort()) console.log(`    ${c}: ${s.byCategory[c]}`);
+  }
+}
+
+function cmdExport(todos, { positional, flags }) {
+  const format = (positional[0] || flags.format || "json").toLowerCase();
+  const out = exportTodos(todos, format);
+  console.log(out);
+}
+
+function cmdArchive(todos) {
+  const n = archiveCompleted(todos);
+  console.log(green(`✓ Archived (removed) ${n} completed item(s)`));
+}
+
+function cmdUpdate(_todos, { flags }) {
+  const tmpDir = path.join(os.tmpdir(), "todo-cli-update");
+  const run = (cmd) => execSync(cmd, { stdio: ["pipe", "pipe", "pipe"] }).toString().trim();
+
+  console.log(bold("todo update") + dim(" — checking for updates...\n"));
+
+  let latestVersion;
+  try {
+    // Clone or pull the repo into a temp dir.
+    if (fs.existsSync(path.join(tmpDir, ".git"))) {
+      console.log(dim("  pulling latest..."));
+      run(`git -C ${tmpDir} pull origin main`);
+    } else {
+      console.log(dim("  cloning repository..."));
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+      run(`git clone --depth 1 ${REPO_URL} ${tmpDir}`);
+    }
+
+    latestVersion = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, "package.json"), "utf8")
+    ).version;
+  } catch (err) {
+    console.error(red(`✗ Failed to fetch latest version: ${err.message}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`  ${dim("current:")} v${VERSION}`);
+  console.log(`  ${dim("latest:")}  v${latestVersion}`);
+
+  if (latestVersion === VERSION) {
+    console.log(green("\n✓ Already up to date."));
+    return;
+  }
+
+  if (flags.check) {
+    console.log(yellow(`\n⬆ Update available: v${VERSION} → v${latestVersion}`));
+    console.log(dim("  Run `todo update` to install."));
+    return;
+  }
+
+  try {
+    console.log(dim("\n  installing..."));
+    execSync(`npm install -g ${tmpDir}`, { stdio: "inherit" });
+    console.log(green(`\n✓ Updated: v${VERSION} → v${latestVersion}`));
+  } catch (err) {
+    console.error(red(`\n✗ Install failed: ${err.message}`));
+    process.exitCode = 1;
+  }
+}
+
+function cmdHelp() {
+  console.log(
+    bold("todo") +
+      dim(" — a CLI todo list manager\n") +
+      `
+${bold("USAGE")}
+  todo <command> [args] [flags]
+
+${bold("COMMANDS")}
+  add <title>            Add a new todo
+  list                   List todos (default command)
+  done <id>              Mark a todo as done  (done --all = complete every pending)
+  toggle <id>            Toggle done / pending
+  edit <id>              Edit a todo (use --title, -p, -t, -c, -d, --note)
+  delete <id>            Delete a todo (alias: rm, remove)
+  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 the latest version (--check = check only)
+  clear                  Remove ALL todos
+  help                   Show this help
+
+${bold("GLOBAL FLAGS")}
+  -h, --help             Show help (works with any command)
+  -v, --version          Show version
+
+${bold("FLAGS")}
+  -p, --priority <v>     Priority: high | medium | low  (default: medium)
+  -t, --tags <v>         Comma-separated tags
+  -c, --category <v>     Category name
+  -d, --due <v>          Due date YYYY-MM-DD
+  --note <v>             Longer note / description
+  --title <v>            New title (for edit)
+  --status <v>           Filter: all | done | pending   (list only)
+  --tag <v>              Filter by tag                  (list only)
+  --sort <v>             Sort: priority | created | due | id  (default: priority)
+  --all                  Complete all pending           (done only)
+  --check                Check for update without installing (update only)
+  --format <v>           Export format json|csv|md      (export only)
+
+${bold("EXAMPLES")}
+  todo add "Buy groceries" -p high -t shopping,weekend -c personal -d 2025-01-15
+  todo add "Write report" --note "Focus on Q4 metrics" -p high -c work
+  todo list --status pending --sort due
+  todo search report
+  todo done 3
+  todo done --all
+  todo edit 2 --title "Updated" -p low -d 2025-02-01
+  todo stats
+  todo export csv
+  todo archive
+  todo update --check
+  todo update
+  todo delete 5
+`
+  );
+}
+
+// --- dispatch --------------------------------------------------------------
+const COMMANDS = {
+  add: cmdAdd,
+  list: cmdList,
+  ls: cmdList,
+  done: cmdDone,
+  toggle: cmdToggle,
+  edit: cmdEdit,
+  delete: cmdDelete,
+  rm: cmdDelete,
+  remove: cmdDelete,
+  search: cmdSearch,
+  stats: cmdStats,
+  export: cmdExport,
+  archive: cmdArchive,
+  update: cmdUpdate,
+  clear: cmdClear,
+  help: cmdHelp,
+};
+
+/** Main entry point. argv should be process.argv.slice(2). */
+export function run(argv) {
+  // -h / --help anywhere (including bare `todo --help`) shows help and exits.
+  if (argv.some((a) => a === "-h" || a === "--help")) {
+    cmdHelp();
+    return;
+  }
+
+  // -v / --version prints the version (read from package.json) and exits.
+  if (argv.some((a) => a === "-v" || a === "--version")) {
+    console.log(`todo v${VERSION}`);
+    return;
+  }
+
+  const store = createStore();
+  const todos = store.load();
+
+  const command = argv[0] && !argv[0].startsWith("-") ? argv[0] : "list";
+  const rest = command === "list" && argv[0] && !argv[0].startsWith("-")
+    ? argv.slice(1)
+    : (command === "list" ? argv : argv.slice(1));
+
+  const handler = COMMANDS[command] ?? cmdHelp;
+  const parsed = parseArgs(rest);
+
+  if (command === "help") {
+    cmdHelp();
+    return;
+  }
+
+  try {
+    handler(todos, parsed);
+    store.save(todos);
+  } catch (err) {
+    console.error(red(`✗ ${err.message}`));
+    process.exitCode = 1;
+  }
+}

package/src/store.js

@@ -0,0 +1,48 @@
+// store.js — JSON file persistence layer for todos.
+// Keeps all data in a single JSON file under the user's home directory.
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const DEFAULT_DATA_DIR = path.join(os.homedir(), ".todo-cli");
+const DEFAULT_DATA_FILE = "todos.json";
+
+/**
+ * Create a store backed by a JSON file.
+ * @param {object} [opts]
+ * @param {string} [opts.dataDir]  Directory for the data file.
+ * @param {string} [opts.dataFile] Filename inside the data dir.
+ */
+export function createStore(opts = {}) {
+  const dataDir = opts.dataDir ?? DEFAULT_DATA_DIR;
+  const dataFile = opts.dataFile ?? DEFAULT_DATA_FILE;
+  const filePath = path.join(dataDir, dataFile);
+
+  function ensureDir() {
+    if (!fs.existsSync(dataDir)) {
+      fs.mkdirSync(dataDir, { recursive: true });
+    }
+  }
+
+  /** Load all todos from disk. Returns [] when the file does not exist. */
+  function load() {
+    if (!fs.existsSync(filePath)) return [];
+    try {
+      const raw = fs.readFileSync(filePath, "utf8");
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch {
+      // Corrupt file — start fresh rather than crashing.
+      return [];
+    }
+  }
+
+  /** Persist the todos array to disk. */
+  function save(todos) {
+    ensureDir();
+    fs.writeFileSync(filePath, JSON.stringify(todos, null, 2), "utf8");
+  }
+
+  return { load, save, filePath };
+}

package/src/todo.js

@@ -0,0 +1,291 @@
+// todo.js — domain logic for the todo list.
+// Pure functions over a todos array; persistence is delegated to a store.
+
+export const PRIORITIES = ["high", "medium", "low"];
+const PRIORITY_RANK = { high: 0, medium: 1, low: 2 };
+
+/** Normalise and validate a priority string. Defaults to "medium". */
+export function normalizePriority(p) {
+  const v = String(p ?? "").toLowerCase().trim();
+  return PRIORITIES.includes(v) ? v : "medium";
+}
+
+/** Parse a comma-separated tag string into a deduplicated, lowercased array. */
+export function parseTags(tags) {
+  if (!tags) return [];
+  const list = Array.isArray(tags)
+    ? tags
+    : String(tags).split(",").map((t) => t.trim().toLowerCase());
+  return [...new Set(list.filter(Boolean))];
+}
+
+/**
+ * Parse & validate a due date (YYYY-MM-DD). Returns "" for empty input,
+ * or throws on an unparseable value.
+ */
+export function parseDueDate(due) {
+  if (!due) return "";
+  const s = String(due).trim();
+  const m = s.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (!m) throw new Error(`Invalid due date "${s}". Use YYYY-MM-DD.`);
+  const d = new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+  if (
+    d.getFullYear() !== Number(m[1]) ||
+    d.getMonth() !== Number(m[2]) - 1 ||
+    d.getDate() !== Number(m[3])
+  ) {
+    throw new Error(`Invalid due date "${s}".`);
+  }
+  return s;
+}
+
+/** Compare a due date (YYYY-MM-DD) to today. Returns null | "overdue" | "today" | "soon". */
+export function dueStatus(due) {
+  if (!due) return null;
+  const today = new Date();
+  const t = new Date(today.getFullYear(), today.getMonth(), today.getDate());
+  const d = new Date(due + "T00:00:00");
+  const diff = Math.round((d - t) / 86400000);
+  if (diff < 0) return "overdue";
+  if (diff === 0) return "today";
+  if (diff <= 3) return "soon";
+  return null;
+}
+
+function nextId(todos) {
+  return todos.reduce((max, t) => Math.max(max, t.id), 0) + 1;
+}
+
+/** Add a new todo. Returns the created todo object. */
+export function addTodo(todos, { title, priority, tags, category, due, note } = {}) {
+  if (!title || !title.trim()) {
+    throw new Error("Title is required.");
+  }
+  const todo = {
+    id: nextId(todos),
+    title: title.trim(),
+    done: false,
+    priority: normalizePriority(priority),
+    tags: parseTags(tags),
+    category: category ? String(category).trim() : "",
+    due: parseDueDate(due),
+    note: note ? String(note).trim() : "",
+    createdAt: new Date().toISOString(),
+  };
+  todos.push(todo);
+  return todo;
+}
+
+/** Find the index of a todo by id. Returns -1 if not found. */
+function indexOf(todos, id) {
+  return todos.findIndex((t) => t.id === Number(id));
+}
+
+/** Delete a todo by id. Returns true if something was removed. */
+export function deleteTodo(todos, id) {
+  const i = indexOf(todos, id);
+  if (i === -1) return false;
+  todos.splice(i, 1);
+  return true;
+}
+
+/** Edit an existing todo by id with partial fields. Returns the updated todo or null. */
+export function editTodo(todos, id, { title, priority, tags, category, due, note } = {}) {
+  const i = indexOf(todos, id);
+  if (i === -1) return null;
+  const todo = todos[i];
+  if (title != null) todo.title = title.trim();
+  if (priority != null) todo.priority = normalizePriority(priority);
+  if (tags != null) todo.tags = parseTags(tags);
+  if (category != null) todo.category = String(category).trim();
+  if (due !== undefined) todo.due = parseDueDate(due);
+  if (note !== undefined) todo.note = String(note).trim();
+  todo.updatedAt = new Date().toISOString();
+  return todo;
+}
+
+/** Toggle the done flag of a todo by id. Returns the updated todo or null. */
+export function toggleTodo(todos, id) {
+  const i = indexOf(todos, id);
+  if (i === -1) return null;
+  todos[i].done = !todos[i].done;
+  todos[i].updatedAt = new Date().toISOString();
+  return todos[i];
+}
+
+/** Mark a todo done by id. Returns the updated todo or null. */
+export function completeTodo(todos, id) {
+  const i = indexOf(todos, id);
+  if (i === -1) return null;
+  todos[i].done = true;
+  todos[i].updatedAt = new Date().toISOString();
+  return todos[i];
+}
+
+/**
+ * Filter and sort the todos.
+ * @param {Array}  todos
+ * @param {object} [filter]
+ * @param {string} [filter.status]   "all" | "done" | "pending"
+ * @param {string} [filter.category] Exact category match.
+ * @param {string} [filter.tag]      Exact tag match.
+ * @param {string} [filter.priority] "high" | "medium" | "low"
+ * @param {string} [filter.sort]     "priority" | "created" | "id"
+ */
+export function listTodos(todos, filter = {}) {
+  const status = filter.status ?? "all";
+  let result = todos.slice();
+
+  if (status === "done") result = result.filter((t) => t.done);
+  else if (status === "pending") result = result.filter((t) => !t.done);
+
+  if (filter.category) {
+    const c = String(filter.category).toLowerCase().trim();
+    result = result.filter((t) => t.category.toLowerCase() === c);
+  }
+  if (filter.tag) {
+    const tg = String(filter.tag).toLowerCase().trim();
+    result = result.filter((t) => t.tags.includes(tg));
+  }
+  if (filter.priority) {
+    const p = normalizePriority(filter.priority);
+    result = result.filter((t) => t.priority === p);
+  }
+
+  const sort = filter.sort ?? "priority";
+  switch (sort) {
+    case "created":
+      result.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+      break;
+    case "id":
+      result.sort((a, b) => a.id - b.id);
+      break;
+    case "due":
+      result.sort((a, b) => {
+        if (!a.due && !b.due) return a.id - b.id;
+        if (!a.due) return 1;
+        if (!b.due) return -1;
+        return a.due.localeCompare(b.due);
+      });
+      break;
+    case "priority":
+    default:
+      result.sort((a, b) => {
+        const d = PRIORITY_RANK[a.priority] - PRIORITY_RANK[b.priority];
+        return d !== 0 ? d : a.id - b.id;
+      });
+      break;
+  }
+  return result;
+}
+
+/** Remove all todos. Returns the count removed. */
+export function clearTodos(todos) {
+  const n = todos.length;
+  todos.length = 0;
+  return n;
+}
+
+/** Search todos by keyword across title, tags, category, and note. */
+export function searchTodos(todos, keyword) {
+  if (!keyword) return [];
+  const kw = String(keyword).toLowerCase().trim();
+  return todos.filter((t) => {
+    return (
+      t.title.toLowerCase().includes(kw) ||
+      t.category.toLowerCase().includes(kw) ||
+      t.note.toLowerCase().includes(kw) ||
+      t.tags.some((tag) => tag.includes(kw))
+    );
+  });
+}
+
+/** Compute summary statistics over all todos. */
+export function getStats(todos) {
+  const stats = {
+    total: todos.length,
+    done: 0,
+    pending: 0,
+    overdue: 0,
+    byPriority: { high: 0, medium: 0, low: 0 },
+    byCategory: {},
+  };
+  for (const t of todos) {
+    if (t.done) stats.done++;
+    else stats.pending++;
+    stats.byPriority[t.priority] = (stats.byPriority[t.priority] ?? 0) + 1;
+    if (t.category) {
+      stats.byCategory[t.category] = (stats.byCategory[t.category] ?? 0) + 1;
+    }
+    if (!t.done && dueStatus(t.due) === "overdue") stats.overdue++;
+  }
+  return stats;
+}
+
+/** Mark ALL pending todos as done. Returns the count completed. */
+export function completeAll(todos) {
+  let n = 0;
+  const now = new Date().toISOString();
+  for (const t of todos) {
+    if (!t.done) {
+      t.done = true;
+      t.updatedAt = now;
+      n++;
+    }
+  }
+  return n;
+}
+
+/** Remove all completed todos. Returns the count archived (removed). */
+export function archiveCompleted(todos) {
+  let n = 0;
+  for (let i = todos.length - 1; i >= 0; i--) {
+    if (todos[i].done) {
+      todos.splice(i, 1);
+      n++;
+    }
+  }
+  return n;
+}
+
+/** Export todos to a string in the given format: "json" | "csv" | "md". */
+export function exportTodos(todos, format = "json") {
+  switch (format) {
+    case "csv":
+      return exportCSV(todos);
+    case "md":
+      return exportMarkdown(todos);
+    case "json":
+    default:
+      return JSON.stringify(todos, null, 2);
+  }
+}
+
+function exportCSV(todos) {
+  const cols = ["id", "title", "done", "priority", "category", "tags", "due", "note"];
+  const esc = (v) => {
+    const s = String(v ?? "");
+    return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+  };
+  const lines = [cols.join(",")];
+  for (const t of todos) {
+    lines.push(
+      [t.id, t.title, t.done, t.priority, t.category, t.tags.join(";"), t.due, t.note]
+        .map(esc)
+        .join(",")
+    );
+  }
+  return lines.join("\n");
+}
+
+function exportMarkdown(todos) {
+  if (todos.length === 0) return "_(no todos)_";
+  const lines = ["| ID | Status | Priority | Category | Tags | Due | Title |", 
+    "|----|--------|----------|----------|------|-----|-------|"];
+  for (const t of todos) {
+    lines.push(
+      `| ${t.id} | ${t.done ? "✓" : "○"} | ${t.priority} | ${t.category || "-"} | ${t.tags.join(", ") || "-"} | ${t.due || "-"} | ${t.title} |`
+    );
+  }
+  return lines.join("\n");
+}