clocktopus 1.0.6 → 1.1.0

package/README.md

@@ -6,7 +6,7 @@
 
 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.
 
@@ -45,14 +45,20 @@ Open [http://localhost:4001](http://localhost:4001) in your browser.
 
 That's it. Start/stop timers from the Home tab.
 
-### Dashboard Commands
-
-| Command                 | Description                          |
-| ----------------------- | ------------------------------------ |
-| `clocktopus dash`       | Start dashboard (foreground)         |
-| `clocktopus serve`      | Start dashboard as background daemon |
-| `clocktopus serve:stop` | Stop the dashboard daemon            |
-| `clocktopus serve:logs` | View dashboard daemon logs           |
+### Commands
+
+| Command                   | Description                             |
+| ------------------------- | --------------------------------------- |
+| `clocktopus dash`         | Start dashboard (foreground)            |
+| `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 as background daemon |
+| `clocktopus monitor:stop` | Stop the idle monitor                   |
+| `clocktopus monitor:logs` | View idle monitor logs                  |
 
 ### Desktop App (macOS)
 
@@ -68,9 +74,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
 
@@ -81,105 +85,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                                 |
 | ---------------- | ------------------------------------------------ |
@@ -188,56 +119,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)
-
-Power users can override credentials via environment variables or a `.env` file:
-
-```
-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.
+OAuth for Jira and Google is handled transparently through a [Cloudflare Worker proxy](docs/atlassian-proxy-flow.md) — no client credentials needed from users.
 
-### Local Project Filtering (CLI only)
+### Project Structure
 
-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)
 ```
 
 ---
@@ -246,37 +144,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,8 @@ import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const SCRIPT_PATH = path.resolve(__dirname, '../../index.js');
+const isDev = SCRIPT_PATH.includes('/Projects/') || SCRIPT_PATH.includes('/src/');
+const PM2_NAME = isDev ? 'clocktopus-monitor-dev' : 'clocktopus-monitor';
 const monitorRoutes = new Hono();
 function pm2Exec(command) {
     try {
@@ -20,15 +22,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 +39,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:run`);
     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/dist/index.js

@@ -137,8 +137,8 @@ function sleep(ms) {
     return new Promise((res) => setTimeout(res, ms));
 }
 program
-    .command('monitor')
-    .description('Monitor system idle time and screen state, and stop the Clockify timer if idle or screen is off.')
+    .command('monitor:run', { hidden: true })
+    .description('Run monitor in foreground (used by PM2).')
     .action(async () => {
     const { workspaceId, userId } = await getWorkspaceAndUser();
     async function stopTimerAndLog(reason) {
@@ -275,6 +275,56 @@ program
     .action(() => {
     startDashboard();
 });
+const isDev = __dirname.includes('/Projects/') || __dirname.includes('/src/');
+const MONITOR_PM2_NAME = isDev ? 'clocktopus-monitor-dev' : 'clocktopus-monitor';
+const DASH_PM2_NAME = isDev ? 'clocktopus-dash-dev' : 'clocktopus-dash';
+program
+    .command('monitor')
+    .description('Start idle monitor as a background daemon.')
+    .action(async () => {
+    const { execSync } = await import('child_process');
+    const bunPath = execSync('which bun', { encoding: 'utf-8' }).trim();
+    const scriptPath = path.join(__dirname, 'index.js');
+    try {
+        try {
+            execSync(`bunx pm2 delete ${MONITOR_PM2_NAME}`, { stdio: 'ignore' });
+        }
+        catch { }
+        execSync(`bunx pm2 start ${scriptPath} --name ${MONITOR_PM2_NAME} --interpreter ${bunPath} -- monitor:run`, {
+            stdio: 'inherit',
+        });
+        console.log(chalk.green('Idle monitor started in background.'));
+        console.log(chalk.gray('  Stop:   clocktopus monitor:stop'));
+        console.log(chalk.gray('  Logs:   clocktopus monitor:logs'));
+    }
+    catch {
+        console.error(chalk.red('Failed to start monitor.'));
+    }
+});
+program
+    .command('monitor:stop')
+    .description('Stop the idle monitor daemon.')
+    .action(async () => {
+    const { execSync } = await import('child_process');
+    try {
+        execSync(`bunx pm2 stop ${MONITOR_PM2_NAME}`, { stdio: 'inherit' });
+    }
+    catch {
+        console.log(chalk.yellow('Monitor is not running.'));
+    }
+});
+program
+    .command('monitor:logs')
+    .description('Show idle monitor logs.')
+    .action(async () => {
+    const { execSync } = await import('child_process');
+    try {
+        execSync(`bunx pm2 logs ${MONITOR_PM2_NAME} --lines 50`, { stdio: 'inherit' });
+    }
+    catch {
+        console.log(chalk.yellow('Monitor is not running.'));
+    }
+});
 program
     .command('serve')
     .description('Start dashboard as a background daemon (PM2).')
@@ -283,12 +333,11 @@ program
     const bunPath = execSync('which bun', { encoding: 'utf-8' }).trim();
     const scriptPath = path.join(__dirname, 'index.js');
     try {
-        // Stop existing if running
         try {
-            execSync('bunx pm2 delete clocktopus-dash', { stdio: 'ignore' });
+            execSync(`bunx pm2 delete ${DASH_PM2_NAME}`, { stdio: 'ignore' });
         }
         catch { }
-        execSync(`bunx pm2 start ${scriptPath} --name clocktopus-dash --interpreter ${bunPath} -- dash`, {
+        execSync(`bunx pm2 start ${scriptPath} --name ${DASH_PM2_NAME} --interpreter ${bunPath} -- dash`, {
             stdio: 'inherit',
         });
         console.log(chalk.green('Dashboard running at http://localhost:4001'));
@@ -305,7 +354,7 @@ program
     .action(async () => {
     const { execSync } = await import('child_process');
     try {
-        execSync('bunx pm2 stop clocktopus-dash', { stdio: 'inherit' });
+        execSync(`bunx pm2 stop ${DASH_PM2_NAME}`, { stdio: 'inherit' });
     }
     catch {
         console.log(chalk.yellow('Dashboard is not running.'));
@@ -317,7 +366,7 @@ program
     .action(async () => {
     const { execSync } = await import('child_process');
     try {
-        execSync('bunx pm2 logs clocktopus-dash --lines 50', { stdio: 'inherit' });
+        execSync(`bunx pm2 logs ${DASH_PM2_NAME} --lines 50`, { stdio: 'inherit' });
     }
     catch {
         console.log(chalk.yellow('Dashboard is not running.'));

package/dist/lib/db.js

@@ -2,7 +2,15 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { Database } from 'bun:sqlite';
 import { z } from 'zod';
-const DB_DIR = path.join(process.cwd(), 'data/db');
+function getDataDir() {
+    const scriptDir = path.dirname(new URL(import.meta.url).pathname);
+    const isDev = scriptDir.includes('/Projects/') || scriptDir.includes('/src/');
+    if (isDev) {
+        return path.join(process.cwd(), 'data/db');
+    }
+    return path.join(process.env.HOME || '~', '.clocktopus', 'data');
+}
+const DB_DIR = getDataDir();
 const DB_PATH = path.join(DB_DIR, 'sessions.db');
 if (!fs.existsSync(DB_DIR)) {
     fs.mkdirSync(DB_DIR, { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clocktopus",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -18,12 +18,11 @@
     "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 --",
-    "monitor": "bun run clockd monitor",
-    "monitor:restart": "bunx pm2 restart clocktopus",
-    "monitor:stop": "bunx pm2 stop clocktopus",
-    "monitor:logs": "bunx pm2 logs clocktopus",
-    "monitor:status": "bunx pm2 status clocktopus",
+    "monitor": "bun dist/index.js monitor",
+    "monitor:stop": "bun dist/index.js monitor:stop",
+    "monitor:restart": "bunx pm2 restart clocktopus-monitor-dev",
+    "monitor:logs": "bun dist/index.js monitor:logs",
+    "monitor:status": "bunx pm2 status clocktopus-monitor-dev",
     "prepare": "husky",
     "dashboard": "bun -e \"import('./dist/dashboard/server.js').then(m => m.startDashboard())\"",
     "db:cleanup": "bun dist/scripts/db-cleanup.js",