clocktopus 1.0.5 → 1.0.7

package/README.md

@@ -6,20 +6,22 @@
 
 CLI-based time-tracking automation for Clockify with idle monitoring, Jira integration, Google Calendar sync, and a web dashboard.
 
-## Quick Start (Dashboard User)
+## Quick Start
 
 Most users only need the dashboard — a web UI to manage timers, connect integrations, and monitor idle time.
 
-### Install
+### Prerequisites
+
+[Bun](https://bun.sh) is required (used as the runtime):
 
 ```bash
-npm i -g clocktopus
+curl -fsSL https://bun.sh/install | bash
 ```
 
-Requires [Bun](https://bun.sh) runtime:
+### Install
 
 ```bash
-curl -fsSL https://bun.sh/install | bash
+bun i -g clocktopus
 ```
 
 ### Run
@@ -43,7 +45,7 @@ Open [http://localhost:4001](http://localhost:4001) in your browser.
 
 That's it. Start/stop timers from the Home tab.
 
-### Dashboard Commands
+### Commands
 
 | Command                 | Description                          |
 | ----------------------- | ------------------------------------ |
@@ -51,6 +53,10 @@ That's it. Start/stop timers from the Home tab.
 | `clocktopus serve`      | Start dashboard as background daemon |
 | `clocktopus serve:stop` | Stop the dashboard daemon            |
 | `clocktopus serve:logs` | View dashboard daemon logs           |
+| `clocktopus start`      | Start a timer (interactive)          |
+| `clocktopus stop`       | Stop the current timer               |
+| `clocktopus status`     | Check timer status                   |
+| `clocktopus monitor`    | Start idle monitor (foreground)      |
 
 ### Desktop App (macOS)
 
@@ -66,9 +72,7 @@ The dashboard server must be running (`clocktopus serve`). See [desktop/README.m
 
 ---
 
-## Power User Guide
-
-For CLI-based workflows, scripting, and advanced features.
+## Development
 
 ### Install from Source
 
@@ -79,105 +83,32 @@ bun install
 bun run build
 ```
 
-### Local Development
+### Local Commands
 
 When running from source, use `bun run clock` instead of `clocktopus`:
 
 ```bash
-# Build first
-bun run build
+bun run build                  # Build TypeScript
 
-# Dashboard
 bun run dashboard              # Start dashboard (foreground)
-
-# Timer
 bun run clock start "Task"     # Start a timer
 bun run clock start -j PROJ-1  # Start with Jira ticket
 bun run clock stop             # Stop timer
 bun run clock status           # Check timer status
 
-# Monitor
 bun run monitor                # Start idle monitor (PM2 daemon)
 bun run monitor:stop           # Stop monitor
 bun run monitor:restart        # Restart monitor
-bun run monitor:status         # Check monitor status
 bun run monitor:logs           # View monitor logs
 
-# Google Calendar
 bun run google-auth            # Authenticate Google account
 bun run log-calendar -t        # Log today's events
-
-# Database
 bun run db:cleanup             # Clean old session logs
 ```
 
-### CLI Commands
-
-#### Timer Management
-
-```bash
-# Start a timer (interactive project selection)
-clocktopus start "Task description"
-
-# Start with a Jira ticket (auto-fetches ticket title)
-clocktopus start -j TICKET-123
-
-# Stop the current timer
-clocktopus stop
-
-# Check timer status
-clocktopus status
-```
-
-#### Idle Monitor
-
-Automatically stops timers when you're idle (5 min) or lock your screen, and restarts when you're back.
-
-```bash
-# Run in foreground
-clocktopus monitor
-
-# Or manage via dashboard UI (Start/Stop/Restart buttons)
-```
-
-The dashboard's Idle Monitor buttons use PM2 under the hood:
-
-| Action      | What it does                   |
-| ----------- | ------------------------------ |
-| **Start**   | Launches monitor as PM2 daemon |
-| **Stop**    | Stops the monitor daemon       |
-| **Restart** | Restarts after code changes    |
-
-#### Google Calendar Integration
-
-Log Google Calendar events as Clockify time entries.
-
-```bash
-# Authenticate (one-time)
-clocktopus google-auth
-
-# Log events for a date range
-clocktopus log-calendar -s 2025-07-21 -e 2025-07-22
-
-# Log today's events
-clocktopus log-calendar -t
-```
-
-For each event, you'll be prompted to select a Clockify project. Selections are cached by event name for recurring meetings.
-
-#### Database Cleanup
-
-```bash
-# Delete session logs older than 5 days (default)
-clocktopus db:cleanup
-
-# Delete logs older than N days
-clocktopus db:cleanup 10
-```
-
 ### Configuration
 
-All configuration is stored in a local SQLite database (`data/sessions.db`) and managed through the dashboard Settings tab. No `.env` file is needed.
+All configuration is stored in a local SQLite database and managed through the dashboard Settings tab.
 
 | Setting          | How to configure                                 |
 | ---------------- | ------------------------------------------------ |
@@ -186,56 +117,23 @@ All configuration is stored in a local SQLite database (`data/sessions.db`) and
 | Jira (API token) | Dashboard > Settings > "or use API token"        |
 | Google Calendar  | Dashboard > Settings > Click "Connect Google"    |
 
-#### OAuth Architecture
-
-- **Jira**: OAuth tokens are exchanged through a [Cloudflare Worker proxy](docs/atlassian-proxy-flow.md) that holds the client secret securely. Users just click Connect.
-- **Google**: Uses a Desktop-type OAuth client. Credentials are handled transparently.
-- **Clockify**: Each user provides their own API key.
-
-#### Environment Variables (Optional Override)
+OAuth for Jira and Google is handled transparently through a [Cloudflare Worker proxy](docs/atlassian-proxy-flow.md) — no client credentials needed from users.
 
-Power users can override credentials via environment variables or a `.env` file:
+### Project Structure
 
 ```
-CLOCKIFY_API_KEY="your_key"
-ATLASSIAN_CLIENT_ID="your_id"
-ATLASSIAN_CLIENT_SECRET="your_secret"
-GOOGLE_CLIENT_ID="your_id"
-GOOGLE_CLIENT_SECRET="your_secret"
-```
-
-The app checks the database first, then falls back to environment variables.
-
-### Local Project Filtering (CLI only)
-
-On first `clocktopus start`, all projects are saved to `data/local-projects.json`. Edit this file to keep only your frequently used projects:
-
-```json
-[
-  { "id": "671b783fbd91bc5e5ddcb944", "name": "Project A" },
-  { "id": "another_id", "name": "Project B" }
-]
-```
-
-### Shell Aliases
-
-For quick access, add to `~/.zshrc`:
-
-```bash
-CLOCKTOPUS_PATH="$HOME/Projects/Personal/clocktopus"
-
-clockto() {
-  cd "$CLOCKTOPUS_PATH" || return
-  bun run "$@"
-}
-
-alias cbuild="clockto build"
-alias cstart="clockto clock start"
-alias cstop="clockto clock stop"
-alias mstart="clockto monitor"
-alias mstop="clockto monitor:stop"
-alias mrestart="clockto monitor:restart"
-alias mlogs="clockto monitor:logs"
+clocktopus/
+├── index.ts              # CLI entry point (Commander)
+├── clockify.ts           # Clockify API client
+├── lib/                  # Core libraries (db, auth, credentials)
+├── dashboard/            # Web dashboard (Hono server)
+│   ├── server.ts         # Dashboard server
+│   ├── views.ts          # HTML/CSS/JS (single-page app)
+│   └── routes/           # API routes
+├── desktop/              # Tauri macOS menu bar app
+├── proxy/                # Cloudflare Worker (OAuth proxy)
+├── scripts/              # Google auth & calendar scripts
+└── data/                 # SQLite DB & config (gitignored)
 ```
 
 ---
@@ -244,37 +142,18 @@ alias mlogs="clockto monitor:logs"
 
 ### No notifications on macOS
 
-Go to **System Settings > Notifications** and ensure **terminal-notifier** (or your terminal app) has notifications enabled.
+Go to **System Settings > Notifications** and ensure **terminal-notifier** has notifications enabled.
 
 ### Monitor not detecting display off
 
-The idle monitor detects screen lock and system idle (5 min). If your Mac's display turns off without locking, enable **Require password immediately** in System Settings > Lock Screen.
+Enable **Require password immediately** in System Settings > Lock Screen.
 
-### Linux Requirements
+### Linux
 
 ```bash
 apt install libxss-dev pkg-config build-essential
 ```
 
----
-
-## Project Structure
-
-```
-clocktopus/
-├── index.ts              # CLI entry point (Commander)
-├── clockify.ts           # Clockify API client
-├── lib/                  # Core libraries (db, auth, credentials)
-├── dashboard/            # Web dashboard (Hono server)
-│   ├── server.ts         # Dashboard server
-│   ├── views.ts          # HTML/CSS/JS (single-page app)
-│   └── routes/           # API routes
-├── desktop/              # Tauri macOS menu bar app
-├── proxy/                # Cloudflare Worker (OAuth proxy)
-├── scripts/              # Google auth & calendar scripts
-└── data/                 # SQLite DB & config (gitignored)
-```
-
 ## License
 
 MIT

package/dist/dashboard/routes/monitor.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const SCRIPT_PATH = path.resolve(__dirname, '../../index.js');
+const PM2_NAME = 'clocktopus-monitor';
 const monitorRoutes = new Hono();
 function pm2Exec(command) {
     try {
@@ -20,15 +21,15 @@ monitorRoutes.get('/monitor/status', (c) => {
     try {
         const output = execSync('bunx pm2 jlist', { encoding: 'utf-8', timeout: 10000 });
         const processes = JSON.parse(output);
-        const clocktopus = processes.find((p) => p.name === 'clocktopus');
-        if (!clocktopus) {
+        const proc = processes.find((p) => p.name === PM2_NAME);
+        if (!proc) {
             return c.json({ running: false, status: 'not found' });
         }
         return c.json({
-            running: clocktopus.pm2_env.status === 'online',
-            status: clocktopus.pm2_env.status,
-            uptime: clocktopus.pm2_env.pm_uptime,
-            restarts: clocktopus.pm2_env.restart_time,
+            running: proc.pm2_env.status === 'online',
+            status: proc.pm2_env.status,
+            uptime: proc.pm2_env.pm_uptime,
+            restarts: proc.pm2_env.restart_time,
         });
     }
     catch {
@@ -37,15 +38,20 @@ monitorRoutes.get('/monitor/status', (c) => {
 });
 monitorRoutes.post('/monitor/start', (c) => {
     const bunPath = execSync('which bun', { encoding: 'utf-8' }).trim();
-    const result = pm2Exec(`bunx pm2 start ${SCRIPT_PATH} --name clocktopus --interpreter ${bunPath} -- monitor`);
+    // Delete any existing process to avoid duplicates
+    try {
+        execSync(`bunx pm2 delete ${PM2_NAME}`, { stdio: 'ignore' });
+    }
+    catch { }
+    const result = pm2Exec(`bunx pm2 start ${SCRIPT_PATH} --name ${PM2_NAME} --interpreter ${bunPath} -- monitor`);
     return c.json(result);
 });
 monitorRoutes.post('/monitor/stop', (c) => {
-    const result = pm2Exec('bunx pm2 stop clocktopus');
+    const result = pm2Exec(`bunx pm2 stop ${PM2_NAME}`);
     return c.json(result);
 });
 monitorRoutes.post('/monitor/restart', (c) => {
-    const result = pm2Exec('bunx pm2 restart clocktopus');
+    const result = pm2Exec(`bunx pm2 restart ${PM2_NAME}`);
     return c.json(result);
 });
 export default monitorRoutes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clocktopus",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -15,6 +15,7 @@
   "scripts": {
     "build": "bunx tsc",
     "prepublishOnly": "bunx tsc",
+    "postinstall": "cd node_modules/macos-notification-state && node-gyp rebuild 2>/dev/null; cd ../desktop-idle && node-gyp rebuild 2>/dev/null; true",
     "lint": "eslint . --ext .ts",
     "clock": "bun dist/index.js",
     "clockd": "bunx pm2 start dist/index.js --name clocktopus --",
@@ -41,9 +42,9 @@
     "inquirer": "^8.2.4",
     "macos-notification-state": "^3.0.0",
     "node-notifier": "^10.0.1",
+    "pm2": "^6.0.8",
     "uuid": "^11.1.0",
-    "zod": "^3.25.76",
-    "pm2": "^6.0.8"
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/bun": "^1.3.11",