@cacinie/cace-timer 1.0.0 → 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CacinieP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,333 +1,192 @@
-# CACE TIMER
-
-一个极简的时间记录 CLI 工具，配有可爱的短发小女孩动画吉祥物。
-
-## 安装
-
-```bash
-cd timekeeper
-npm link
-```
-
-安装后全局命令 `tk` 即可使用。
-
-## 快速开始
-
-```bash
-# 开始一个任务
-tk start "写周报" --tag work --estimate 30
-
-# 记录进度节点
-tk mark "完成数据分析"
-
-# 查看当前状态
-tk status
-
-# 结束任务（显示效率评分）
-tk stop
-```
-
-## 命令一览
-
-### tk start
-
-开始新任务。
-
-```bash
-tk start <任务名> [选项]
-
-选项:
-  --tag <标签>       添加标签
-  --estimate <分钟>  预估时长（用于计算效率分）
-```
-
-示例：
-```bash
-tk start "开发登录功能" --tag coding --estimate 60
-```
-
-### tk mark
-
-记录时间节点。
-
-```bash
-tk mark <备注>
-```
-
-示例：
-```bash
-tk mark "完成API接口"
-tk mark "开始写测试"
-```
-
-### tk stop
-
-结束当前任务，显示总结和效率评分。
-
-```bash
-tk stop
-```
-
-效率评分规则：
-- 实际时长 ≤ 预估时长 → 100%（🏆 优秀）
-- 实际时长稍超预估 → 80-99%（💪 良好）
-- 实际时长远超预估 → <50%（💀 需改进）
-
-### tk status
-
-查看当前进行中的任务状态。
-
-```bash
-tk status
-```
-
-### tk list
-
-查看历史记录。
-
-```bash
-tk list [选项]
-
-选项:
-  --today         仅显示今天
-  --tag <标签>    按标签筛选
-  --limit <数量>  限制显示数量（默认10）
-```
-
-示例：
-```bash
-tk list --today
-tk list --tag coding --limit 20
-```
-
-### tk search
-
-搜索历史记录。
-
-```bash
-tk search <关键词>
-```
-
-会搜索任务名、标签、标记备注。
-
-```bash
-tk search "登录"
-tk search "coding"
-```
-
-### tk sync
-
-设置同步文件路径，实现跨设备同步。
-
-```bash
-tk sync <文件路径>
-```
-
-建议将同步文件放在云盘目录：
-```bash
-tk sync ~/Dropbox/cace-timer.json
-tk sync ~/OneDrive/cace-timer.json
-```
-
-## 数据同步指南
-
-### 工作原理
-
-CACE TIMER 采用**单文件同步**策略：
-
-```
-┌─────────────┐         ┌─────────────┐
-│   设备 A    │         │   设备 B    │
-│  ~/(本地)   │         │  ~/(本地)   │
-│ .cace-timer │         │ .cace-timer │
-│    .json    │         │    .json    │
-└──────┬──────┘         └──────┬──────┘
-       │                       │
-       ▼                       ▼
-┌─────────────────────────────────────┐
-│         云盘同步目录                  │
-│   Dropbox / iCloud / OneDrive       │
-│        cace-timer.json              │
-└─────────────────────────────────────┘
-```
-
-每次执行 `tk` 命令时：
-1. 写入本地 `~/.cace-timer.json`
-2. 同时写入配置的 `syncPath`（如果设置了）
-
-### 设置步骤
-
-#### Dropbox
-
-```bash
-# macOS / Linux
-tk sync ~/Dropbox/cace-timer.json
-
-# Windows
-tk sync "%USERPROFILE%\Dropbox\cace-timer.json"
-```
-
-#### iCloud
-
-```bash
-# macOS
-tk sync ~/Library/Mobile\ Documents/com~apple~CloudDocs/cace-timer.json
-```
-
-#### OneDrive
-
-```bash
-# macOS
-tk sync ~/OneDrive/cace-timer.json
-
-# Windows
-tk sync "%USERPROFILE%\OneDrive\cace-timer.json"
-```
-
-#### 自建同步 (Syncthing / Resilio)
-
-```bash
-tk sync ~/Sync/cace-timer.json
-```
-
-### 多设备使用
-
-**首次在设备 B 使用：**
-
-```bash
-# 1. 安装 CACE TIMER
-cd timekeeper && npm link
-
-# 2. 设置同步路径（指向云盘已同步的文件）
-tk sync ~/Dropbox/cace-timer.json
-
-# 3. 查看同步的数据
-tk list
-```
-
-**注意：** 新设备需要先设置 `tk sync`，然后才能读取云盘数据。
-
-### 同步冲突处理
-
-由于采用单文件策略，建议：
-
-| 场景 | 建议 |
-|------|------|
-| 多设备同时使用 | 避免同时在多个设备操作 |
-| 云盘同步延迟 | 操作后等待几秒再切换设备 |
-| 冲突文件 | 手动合并 JSON，保留需要的记录 |
-
-### 手动备份
-
-```bash
-# 导出备份
-cp ~/.cace-timer.json ~/backup/cace-timer-$(date +%Y%m%d).json
-
-# 恢复备份
-cp ~/backup/cace-timer-20240302.json ~/.cace-timer.json
-```
-
-### 数据格式
-
-同步文件为标准 JSON 格式：
-
-```json
-{
-  "syncPath": "/Users/you/Dropbox/cace-timer.json",
-  "current": null,
-  "history": [
-    {
-      "id": "lq3x9k2",
-      "task": "开发功能",
-      "start": "2024-03-02T10:00:00.000Z",
-      "end": "2024-03-02T11:30:00.000Z",
-      "tags": ["coding"],
-      "marks": [
-        { "time": "2024-03-02T10:30:00.000Z", "note": "完成API" }
-      ],
-      "estimatedMinutes": 60
-    }
-  ]
-}
-```
-
-### 取消同步
-
-编辑 `~/.cace-timer.json`，删除 `syncPath` 字段即可。
-
----
-
-### tk help
-
-显示帮助信息。
-
-```bash
-tk help
-```
-
-## CACE 吉祥物
-
-CACE 是一个可爱的短发小女孩头像：
-
-```
-   ▄▄▄▄▄▄▄▄▄▄▄
-  █░░░░░░░░░░░█   ← 刘海
-  █░▄▄▄▄▄▄▄▄▄░█
-  █░│ ●   ● │░█   ← 大眼睛
-  █░│   ▽   │░█   ← 小鼻子
-  █░│  ───  │░█   ← 嘴巴
-  ╰───────────╯
-```
-
-**动画表情：**
-
-| 状态 | 眼睛 | 嘴巴 | 触发场景 |
-|------|------|------|----------|
-| 正常 | ● ● | ─── | 默认状态 |
-| 开心 | ★ ★ | ◡◡◡ | 完成任务 |
-| 眨眼 | ─ ─ | ─── | 动画帧 |
-| 超开心 | ◉ ◉ | ▽△▽ | 动画帧 |
-| 困倦 | ─ ─ | ─── | 无任务时 |
-
-动画循环：正常 → 眨眼 → 开心 → 超开心（循环2次）
-
-## 数据存储
-
-数据保存在 `~/.cace-timer.json`：
-
-```json
-{
-  "syncPath": "~/Dropbox/cace-timer.json",
-  "current": null,
-  "history": [
-    {
-      "id": "xxx",
-      "task": "写周报",
-      "start": "2024-03-02T10:00:00Z",
-      "end": "2024-03-02T10:30:00Z",
-      "tags": ["work"],
-      "marks": [
-        { "time": "2024-03-02T10:15:00Z", "note": "完成数据分析" }
-      ],
-      "estimatedMinutes": 30
-    }
-  ]
-}
-```
-
-## 使用场景
-
-- **编程开发**：记录编码时间，评估效率
-- **学习复习**：跟踪学习时长和进度
-- **项目管理**：标记关键节点，回顾时间分配
-- **自由职业**：为客户项目计时
-
-## 卸载
-
-```bash
-npm unlink -g cace-timer
-```
-
-## License
-
-MIT
+# cace-timer
+
+[![npm version](https://img.shields.io/npm/v/@cacinie/cace-timer.svg)](https://www.npmjs.com/package/@cacinie/cace-timer)
+[![license](https://img.shields.io/npm/l/@cacinie/cace-timer.svg)](https://github.com/CacinieP/cace-timer/blob/main/LICENSE)
+
+A minimal time tracking CLI with cute anime girl mascot.
+
+```
+npm install -g @cacinie/cace-timer
+```
+
+```
+  ▄▄▄▄▄▄▄▄▄▄▄▄
+ █░░░░░░░░░░░░█
+ █░▄▄▄▄▄▄▄▄▄░█
+ █░│ ●   ● │░█
+ █░│   ▽   │░█
+ █░│  ───  │░█
+ ╰────────────╯
+   CACE TIMER
+```
+
+## Quick Start
+
+```bash
+# Start a task
+tk start "写周报" --tag work --estimate 30
+
+# Mark progress
+tk mark "完成数据分析"
+
+# Check status
+tk status
+
+# Stop and get efficiency score
+tk stop
+```
+
+## Commands
+
+### `tk start <task> [options]`
+
+Start a new task.
+
+| Option | Description |
+|--------|-------------|
+| `--tag <tag>` | Add a tag |
+| `--estimate <minutes>` | Estimated duration (for efficiency score) |
+
+```bash
+tk start "开发登录功能" --tag coding --estimate 60
+```
+
+### `tk mark <note>`
+
+Record a time checkpoint.
+
+```bash
+tk mark "完成API接口"
+tk mark "开始写测试"
+```
+
+### `tk stop`
+
+Stop current task, show summary and efficiency score.
+
+| Score | Emoji | Meaning |
+|-------|-------|---------|
+| 100% | 🏆 | Actual ≤ Estimate |
+| 80-99% | ⭐ | Slightly over or on target |
+| 50-79% | 💪 | Moderately over estimate |
+| <50% | 💀 | Far over estimate |
+
+Efficiency score is only shown when `--estimate` was set at task start.
+
+### `tk status`
+
+Show current running task.
+
+### `tk list [options]`
+
+View history.
+
+| Option | Description |
+|--------|-------------|
+| `--today` | Today only |
+| `--tag <tag>` | Filter by tag |
+| `--limit <n>` | Limit count (default 10) |
+
+```bash
+tk list --today
+tk list --tag coding --limit 20
+```
+
+### `tk search <keyword>`
+
+Search across task names, tags, and mark notes.
+
+```bash
+tk search "登录"
+```
+
+### `tk sync <path>`
+
+Set sync file path for cross-device sync (Dropbox / iCloud / OneDrive).
+
+```bash
+# macOS / Linux
+tk sync ~/Dropbox/cace-timer.json
+tk sync ~/OneDrive/cace-timer.json
+
+# Windows
+tk sync "%USERPROFILE%\Dropbox\cace-timer.json"
+tk sync "%USERPROFILE%\OneDrive\cace-timer.json"
+```
+
+### `tk help`
+
+Show help.
+
+## CACE Mascot
+
+CACE reacts to what you do:
+
+| State | Eyes | Mouth | When |
+|-------|------|-------|------|
+| Normal | ● ● | ─── | Default |
+| Happy | ★ ★ | ◡◡◡ | Task completed |
+| Super Happy | ◉ ◉ | ▽△▽ | Animation frame |
+| Sleepy | ─ ─ | ─── | No active task |
+| Blink | ─ ─ | ─── | Animation frame |
+
+## Data
+
+All data is stored in `~/.cace-timer.json`. Single JSON file, easy to backup and sync.
+
+```json
+{
+  "syncPath": "~/Dropbox/cace-timer.json",
+  "current": null,
+  "history": [
+    {
+      "id": "lq3x9k2",
+      "task": "写周报",
+      "start": "2024-03-02T10:00:00.000Z",
+      "end": "2024-03-02T10:30:00.000Z",
+      "tags": ["work"],
+      "marks": [{ "time": "...", "note": "完成数据分析" }],
+      "estimatedMinutes": 30
+    }
+  ]
+}
+```
+
+## Uninstall
+
+```bash
+npm uninstall -g @cacinie/cace-timer
+```
+
+## Changelog
+
+### v1.1.1
+
+- Added `prepare` script (fixes git-based installs)
+- Added `types` field for TypeScript consumers
+- Fixed efficiency score display when no estimate was set
+- Fixed efficiency score table mismatch in README
+- Fixed `--limit 0` falsy-zero bug
+- Fixed `--estimate` NaN handling
+- Added Super Happy mascot state and Windows sync paths to README
+- Added uninstall instructions and data format to README
+
+### v1.1.0
+
+- Restructured repo layout (flat structure, no nested `timekeeper/`)
+- Fixed `.gitignore` (dist/ was not properly ignored)
+- Fixed CI workflow (was running in wrong directory)
+- Added Node 18/20/22 matrix in CI
+- Added `engines` field in package.json
+
+### v1.0.0
+
+- Initial release
+- start / mark / stop / status / list / search / sync commands
+- CACE mascot animation
+- Efficiency scoring
+- Cloud sync support
+
+## License
+
+MIT

package/dist/index.js

@@ -264,8 +264,9 @@ async function cmdStop() {
     const duration = new Date(session.end).getTime() - new Date(session.start).getTime();
     const durationMinutes = duration / 60000;
     // Calculate efficiency score
-    let efficiency = 100;
-    if (session.estimatedMinutes && session.estimatedMinutes > 0) {
+    const hasEstimate = session.estimatedMinutes && session.estimatedMinutes > 0;
+    let efficiency = -1;
+    if (hasEstimate) {
         efficiency = Math.min(100, Math.round((session.estimatedMinutes / durationMinutes) * 100));
     }
     data.history.unshift(session);
@@ -287,20 +288,25 @@ async function cmdStop() {
         console.log(`  📍 标记: ${session.marks.length} 个`);
     }
     // Efficiency display
-    let effEmoji = '⭐';
-    let effColor = '\x1b[32m';
-    if (efficiency < 50) {
-        effEmoji = '💀';
-        effColor = '\x1b[31m';
-    }
-    else if (efficiency < 80) {
-        effEmoji = '💪';
-        effColor = '\x1b[33m';
+    if (hasEstimate) {
+        let effEmoji = '⭐';
+        let effColor = '\x1b[32m';
+        if (efficiency < 50) {
+            effEmoji = '💀';
+            effColor = '\x1b[31m';
+        }
+        else if (efficiency < 80) {
+            effEmoji = '💪';
+            effColor = '\x1b[33m';
+        }
+        else if (efficiency >= 100) {
+            effEmoji = '🏆';
+        }
+        console.log(`  ${effEmoji} 效率分: ${effColor}${efficiency}%\x1b[0m`);
     }
-    else if (efficiency >= 100) {
-        effEmoji = '🏆';
+    else {
+        console.log('  ⏱  未设置预估时长，无法计算效率分');
     }
-    console.log(`  ${effEmoji} 效率分: ${effColor}${efficiency}%\x1b[0m`);
     console.log();
 }
 function cmdStatus() {
@@ -345,7 +351,7 @@ function cmdList(options) {
         sessions = sessions.filter(s => s.tags.includes(options.tag));
     }
     // Limit
-    const limit = options.limit || 10;
+    const limit = options.limit ?? 10;
     sessions = sessions.slice(0, limit);
     console.log();
     showCaceSmall('历史记录');
@@ -481,7 +487,7 @@ async function main() {
         case 'start':
             await cmdStart(positional[0] || '', {
                 tag: options.tag,
-                estimate: options.estimate ? parseInt(options.estimate) : undefined
+                estimate: options.estimate ? (Number(options.estimate) > 0 ? parseInt(options.estimate) : undefined) : undefined
             });
             break;
         case 'mark':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cacinie/cace-timer",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "A minimal time tracking CLI with cute anime girl mascot",
   "main": "dist/index.js",
   "bin": {
@@ -11,10 +11,23 @@
     "build": "tsc",
     "dev": "ts-node src/index.ts",
     "start": "node dist/index.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "prepare": "npm run build"
   },
-  "files": ["dist", "README.md", "LICENSE"],
-  "keywords": ["time", "tracker", "cli", "timer", "productivity", "anime", "mascot"],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "time",
+    "tracker",
+    "cli",
+    "timer",
+    "productivity",
+    "anime",
+    "mascot"
+  ],
   "author": "CacinieP <cacinie@gmail.com>",
   "license": "MIT",
   "repository": {
@@ -25,6 +38,9 @@
     "url": "https://github.com/CacinieP/cace-timer/issues"
   },
   "homepage": "https://github.com/CacinieP/cace-timer#readme",
+  "engines": {
+    "node": ">=18"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -32,5 +48,6 @@
     "@types/node": "^20.10.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.3.0"
-  }
-}
+  },
+  "types": "dist/index.d.ts"
+}