clocktopus 1.0.0

package/README.md

@@ -0,0 +1,297 @@
+# Clocktopus
+
+<p align="center">
+  <img src="assets/logo.png" alt="Clocktopus Logo" width="300px" />
+</p>
+
+## About
+
+Clocktopus is a powerful command-line interface tool designed to streamline your time tracking with platforms like Clockify and Jira. It offers a suite of features to automate and simplify the process of logging your work, ensuring accuracy and efficiency.
+
+### Key Features
+
+- **Automated Idle Monitoring:** Automatically stops and restarts timers based on your system's idle activity.
+- **Jira Integration:** Seamlessly link your time entries to Jira tickets, fetching and prepending ticket titles to descriptions.
+- **Google Calendar Integration:** Log your Google Calendar events directly as Clockify time entries, with intelligent project caching for recurring events.
+- **Local Project Filtering:** Curate a personalized list of projects for quick selection, reducing clutter.
+- **Session Management:** Start, stop, and check the status of your time entries directly from the terminal.
+- **Database Cleanup:** Easily manage and clean up old session logs from the local SQLite database.
+
+## Installation
+
+To get started with the Clocktopus CLI, follow these steps:
+
+1.  **Clone the repository:**
+
+    ```bash
+    git clone <repository_url>
+    cd clocktopus
+    ```
+
+2.  **Install dependencies:**
+    ```bash
+    bun install
+    ```
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file in the `data/` directory with the following variables:
+
+```
+CLOCKIFY_API_KEY="your_clockify_api_key_here"
+ATLASSIAN_CLIENT_ID="your_atlassian_oauth_client_id"
+ATLASSIAN_CLIENT_SECRET="your_atlassian_oauth_client_secret"
+GOOGLE_CLIENT_ID="google_client_id"
+GOOGLE_CLIENT_SECRET="google_client_secret"
+```
+
+You can get your Clockify API key from [Manage API Keys](https://app.clockify.me/manage-api-keys).
+
+### Jira Integration (Atlassian OAuth)
+
+Clocktopus uses Atlassian OAuth 2.0 so users can connect their Jira account with a single click from the dashboard instead of manually copying API tokens.
+
+#### Setting up the Atlassian OAuth App
+
+1. Go to [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) and create a new **OAuth 2.0 (3LO)** app
+2. Under **Authorization**, set the callback URL to:
+   ```
+   http://localhost:4001/api/jira/callback
+   ```
+3. Under **Permissions**, add the following scopes:
+   - **Jira API**: `read:jira-work`, `write:jira-work`
+   - **User identity API**: `read:me`
+4. Copy the **Client ID** and **Client Secret** from the app's **Settings** page
+5. Add them to your `.env` file as `ATLASSIAN_CLIENT_ID` and `ATLASSIAN_CLIENT_SECRET`
+6. Start the dashboard (`bun run dashboard`) and click **Connect Atlassian**
+
+> **Fallback:** If you prefer using an API token instead of OAuth, you can expand the "or use API token" section on the dashboard and enter your credentials manually. For this, set the following in `.env`:
+>
+> ```
+> ATLASSIAN_URL="https://your_org.atlassian.net/rest/api/3"
+> ATLASSIAN_API_TOKEN="your_atlassian_api_token_here"
+> ATLASSIAN_EMAIL="username@example.com"
+> ```
+
+### Local Projects Filtering
+
+The CLI allows you to filter the projects displayed when starting a new time entry. On the first run of the `clock start` command, the application will fetch all your Clockify projects and populate `data/local-projects.json` with their IDs and names. You can then edit this file to keep only the projects you frequently work on.
+
+Example `data/local-projects.json`:
+
+```json
+[
+  {
+    "id": "671b783fbd91bc5e5ddcb944",
+    "name": "2024 Project Management Traineeship"
+  },
+  {
+    "id": "another_project_id",
+    "name": "Another Project Name"
+  }
+]
+```
+
+Remove any project objects (both `id` and `name`) that you don't want to appear in the project selection list.
+
+## Usage
+
+### Build the application
+
+Before running, you need to compile the TypeScript code:
+
+```bash
+bun run build
+```
+
+### Run the application
+
+Once built, you can run the CLI commands using the following commands:
+
+- **Monitor idle state and auto-manage timers:**
+
+  ```bash
+  bun run monitor
+  ```
+
+  This command will monitor your system's idle time and automatically manage your Clockify timer:
+  - If you are idle for more than 5 minutes, the currently running timer will be stopped.
+  - When you become active again (move the mouse, press a key, etc.), if your last session was auto-completed due to idleness, a new timer will automatically be created for the last used project.
+  - All session events (start, stop, auto-complete, resume) are logged locally in the SQLite database, including project and description.
+
+  This ensures your time tracking is accurate even if you step away from your computer or forget to manually stop and restart your timer.
+
+  > Note: This ensures your time tracking is accurate even if you step away from your computer or forget to manually stop and restart your timer.
+  > If you do not want the background process to check your idle state, you can skip this.
+
+- **Start a new time entry:**
+
+  ```bash
+  bun run clock start "Task description"
+  ```
+
+  This will prompt you to select a project from your curated list.
+
+- **Start a new time entry with a Jira ticket:**
+
+  ```bash
+  bun run clock start -j TICKET-123
+  ```
+
+  When you provide a Jira ticket number with the `-j` flag, the tool will automatically fetch the ticket's title from Jira and prepend it to your time entry description. For example, if the title of `TICKET-123` is "Fix the login button", the description will be saved as `TICKET-123 Fix the login button`. If you also provide a description, it will be appended after the Jira title.
+
+- **Stop the currently running time entry:**
+
+  ```bash
+  bun run clock stop
+  ```
+
+- **Check the status of the current timer:**
+  ```bash
+  bun run clock status
+  ```
+
+### Manage Monitor
+
+- **Restart the monitor process (after code changes):**
+
+  ```bash
+  bun run monitor:restart
+  ```
+
+  Use this command to restart the monitor process, for example after making code changes or updating dependencies. This ensures the monitor is running the latest version of your code.
+
+- **Stop the monitor process:**
+
+  ```bash
+  bun run monitor:stop
+  ```
+
+  This command will stop the monitor process if it is running in the background. Use this when you want to fully halt all automatic idle monitoring and timer management.
+
+- **Show monitor logs:**
+
+  ```bash
+  bun run monitor:logs
+  ```
+
+  This command will display logs related to the monitor process. Use it to review idle/active transitions, timer events, and session details that have been recorded while the monitor was running. This is useful for troubleshooting, auditing, or reviewing your time tracking history.
+
+### Database Cleanup
+
+To delete old session logs from the local SQLite database, use the `db:cleanup` command:
+
+```bash
+bun run db:cleanup <older-than-number-in-days>
+```
+
+- `<older-than-number-in-days>` (Optional): Specifies the number of days. Session logs older than this number of days will be deleted. If not provided, logs older than 5 days will be deleted by default.
+
+Examples:
+
+- Delete logs older than 5 days (default):
+
+  ```bash
+  bun run db:cleanup
+  ```
+
+- Delete logs older than 5 days:
+  ```bash
+  bun run db:cleanup 5
+  ```
+
+### Google Calendar Integration
+
+This tool can log your Google Calendar events as time entries in Clockify. This is particularly useful for automatically tracking time spent in meetings or other scheduled events.
+
+#### 1. Google Authentication
+
+Before you can log calendar events, you need to authenticate with your Google account. This will grant the tool read-only access to your Google Calendar.
+
+```bash
+bun run google-auth
+```
+
+Follow the prompts in your browser to complete the authentication process. A token will be stored locally to maintain your session.
+
+#### 2. Log Calendar Events
+
+Once authenticated, you can log events for a specific date range:
+
+```bash
+bun run log-calendar -s <start-date> -e <end-date>
+```
+
+- `<start-date>`: The start date for fetching calendar events (e.g., `2025-07-21`).
+- `<end-date>`: The end date for fetching calendar events (e.g., `2025-07-22`).
+
+You can also log events for today using the `-t` or `--today` flag:
+
+```bash
+bun run log-calendar -t
+```
+
+For each calendar event, the tool will prompt you to select a Clockify project. Your selection will be cached based on the event's summary (name), so if you have recurring events with the same name, you will only be asked once for the project. If you provide a `project-id` using the `-p` flag, all events will be logged to that project without prompting.
+
+Example:
+
+```bash
+bun run log-calendar -s 2025-07-21 -e 2025-07-22
+```
+
+Or, to log all events to a specific project:
+
+```bash
+bun run log-calendar -s 2025-07-21 -e 2025-07-22 -p your_clockify_project_id
+```
+
+## Troubleshooting
+
+### No notifications on macOS
+
+If you are not receiving notifications on macOS, you may need to adjust your system settings.
+
+- **Check System Settings for Notifications:**
+  - Go to **System Settings > Notifications**.
+  - Look for **Terminal** (or your specific terminal application if you use another one like iTerm).
+  - Make sure that **Allow Notifications** is turned on for it.
+  - If you see an entry for **Node**, ensure it also has permissions.
+
+Often, the first time a script tries to send a notification, macOS will ask for permission. If this was accidentally denied, you won't see any notifications.
+
+## Linux Requirements
+
+X server development package and pkg-config are required to run `desktop-idle` package:
+
+```
+apt install libxss-dev pkg-config build-essential
+```
+
+## Zsh Alias
+
+If you super lazy just like me, then you can add aliases for different actions. Here is what I use:
+
+```bash
+# Clocktopus
+CLOCKTOPUS_PATH="$HOME/Projects/Personal/clocktopus"
+
+clocktopus() {
+  cd "$CLOCKTOPUS_PATH" || return
+  bun run "$@"
+}
+
+alias cbuild="clocktopus build"
+alias cstart="clocktopus clock start"
+alias cstop="clocktopus clock stop"
+alias mstart="clocktopus monitor"
+alias mstop="clocktopus monitor:stop"
+alias mrestart="clocktopus monitor:restart"
+alias mstatus="clocktopus monitor:status"
+alias mlogs="clocktopus monitor:logs"
+alias cgcalauth="clocktopus google-auth"
+alias cgcal="clocktopus log-calendar"
+```
+
+Copy the above code in `.zshrc` file, change `CLOCKTOPUS_PATH` based on your path and save it. Then source the file using `source ~/.zshrc`.

package/dist/clockify.js

@@ -0,0 +1,188 @@
+import { HttpClient } from './lib/http-client.js';
+import { logSessionStart } from './lib/db.js';
+import { v4 as uuidv4 } from 'uuid';
+import { NotificationCenter } from 'node-notifier';
+import { getJiraTicket } from './lib/jira.js';
+export class Clockify {
+    constructor() {
+        this.httpClient = new HttpClient().getClient();
+        this.notifier = new NotificationCenter();
+    }
+    sendNotification(title, message, actions, callback) {
+        this.notifier.notify({
+            title,
+            message,
+            sound: true,
+            wait: true,
+            actions,
+        }, callback ??
+            ((err) => {
+                if (err)
+                    console.error('Notification error:', err);
+            }));
+    }
+    async getUser() {
+        try {
+            const response = await this.httpClient.get('/user');
+            return response.data;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                console.error('[clockify] Could not connect to Clockify. Please check your API key.', error.message);
+            }
+            else {
+                console.error('[clockify] An unknown error occurred.');
+            }
+            return null;
+        }
+    }
+    async getProjects(workspaceId) {
+        try {
+            let allProjects = [];
+            let page = 1;
+            const pageSize = 50;
+            let hasMore = true;
+            while (hasMore) {
+                const response = await this.httpClient.get(`/workspaces/${workspaceId}/projects`, {
+                    params: {
+                        page: page,
+                        'page-size': pageSize,
+                        archived: false,
+                    },
+                });
+                if (response.data.length > 0) {
+                    allProjects = allProjects.concat(response.data);
+                    page++;
+                }
+                else {
+                    hasMore = false;
+                }
+            }
+            return allProjects;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                console.error('Error fetching projects:', error.message);
+            }
+            else {
+                console.error('Error fetching projects: An unknown error occurred.');
+            }
+            return [];
+        }
+    }
+    async getProjectById(workspaceId, projectId) {
+        try {
+            const response = await this.httpClient.get(`/workspaces/${workspaceId}/projects/${projectId}`);
+            return response.data;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                console.error('Error fetching project:', error.message);
+            }
+            else {
+                console.error('Error fetching project: An unknown error occurred.');
+            }
+            return null;
+        }
+    }
+    async startTimer(workspaceId, projectId, description = 'Working on a task...', jiraTicket) {
+        try {
+            const user = await this.getUser();
+            if (!user) {
+                return null;
+            }
+            let finalDescription = description;
+            if (jiraTicket) {
+                const ticket = await getJiraTicket(jiraTicket);
+                if (ticket) {
+                    finalDescription = `${jiraTicket} ${ticket.fields.summary}`;
+                }
+            }
+            const startedAt = new Date().toISOString();
+            const sessionId = uuidv4();
+            const response = await this.httpClient.post(`/workspaces/${workspaceId}/time-entries`, {
+                projectId: projectId,
+                description: finalDescription,
+                start: startedAt,
+            });
+            // Log session to SQLite
+            logSessionStart(sessionId, projectId, finalDescription, startedAt, jiraTicket);
+            const project = await this.getProjectById(workspaceId, projectId);
+            this.sendNotification(`Timer started for ${project ? project.name : 'a project'}`, finalDescription, ['Stop'], (err, response, metadata) => {
+                if (err) {
+                    console.error(err);
+                    return;
+                }
+                if (metadata.activationValue === 'Stop') {
+                    this.stopTimer(workspaceId, user.id);
+                }
+            });
+            return response.data;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                console.error('Error starting timer:', error.message);
+            }
+            else {
+                console.error('Error starting timer: An unknown error occurred.');
+            }
+            return null;
+        }
+    }
+    async stopTimer(workspaceId, userId) {
+        try {
+            const response = await this.httpClient.patch(`/workspaces/${workspaceId}/user/${userId}/time-entries`, {
+                end: new Date().toISOString(),
+            });
+            this.sendNotification('Timer stopped', 'Your timer has been stopped.');
+            return response.data;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                console.error('Error stopping timer:', error.message);
+            }
+            else {
+                console.error('Error stopping timer: An unknown error occurred.');
+            }
+            return null;
+        }
+    }
+    async getActiveTimer(workspaceId, userId) {
+        try {
+            const response = await this.httpClient.get(`/workspaces/${workspaceId}/user/${userId}/time-entries?in-progress=true`);
+            return response.data[0];
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                console.error('Error fetching active timer:', error.message);
+            }
+            else {
+                console.error('Error fetching active timer: An unknown error occurred.');
+            }
+            return null;
+        }
+    }
+    async logTime(workspaceId, projectId, start, end, description) {
+        if (!projectId) {
+            return null;
+        }
+        try {
+            const response = await this.httpClient.post(`/workspaces/${workspaceId}/time-entries`, {
+                projectId: projectId,
+                start: start,
+                end: end,
+                description: description,
+            });
+            return response.data;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                console.error('Error logging time:', error.message);
+            }
+            else {
+                console.error('Error logging time: An unknown error occurred.');
+            }
+            return null;
+        }
+    }
+}

package/dist/config/clockify.js

@@ -0,0 +1,7 @@
+import { resolveCredential } from '../lib/credentials.js';
+export default {
+    baseUrl: 'https://api.clockify.me/api/v1',
+    get apiKey() {
+        return resolveCredential('CLOCKIFY_API_KEY');
+    },
+};

package/dist/dashboard/routes/clockify.js

@@ -0,0 +1,25 @@
+import { Hono } from 'hono';
+import axios from 'axios';
+import { saveCredential } from '../../lib/credentials.js';
+const clockifyRoutes = new Hono();
+clockifyRoutes.post('/clockify', async (c) => {
+    const { apiKey } = await c.req.json();
+    if (!apiKey) {
+        return c.json({ ok: false, error: 'API key is required.' }, 400);
+    }
+    try {
+        const res = await axios.get('https://api.clockify.me/api/v1/user', {
+            headers: { 'X-Api-Key': apiKey },
+            timeout: 5000,
+        });
+        if (res.status === 200) {
+            saveCredential('CLOCKIFY_API_KEY', apiKey);
+            return c.json({ ok: true, user: res.data.name });
+        }
+        return c.json({ ok: false, error: 'Invalid API key.' });
+    }
+    catch {
+        return c.json({ ok: false, error: 'Could not validate API key with Clockify.' });
+    }
+});
+export default clockifyRoutes;

package/dist/dashboard/routes/data.js

@@ -0,0 +1,61 @@
+import { Hono } from 'hono';
+import { getRecentSessions, getSessionCount, getActiveProjects, getAllProjects, upsertProjects, toggleProjectActive, } from '../../lib/db.js';
+import { Clockify } from '../../clockify.js';
+const dataRoutes = new Hono();
+// Active projects for timer dropdown
+dataRoutes.get('/projects', (c) => {
+    const projects = getActiveProjects();
+    return c.json(projects);
+});
+// All projects for settings management
+dataRoutes.get('/projects/all', (c) => {
+    const projects = getAllProjects();
+    return c.json(projects);
+});
+// Fetch projects from Clockify and save to DB
+dataRoutes.post('/projects/fetch', async (c) => {
+    try {
+        const clockify = new Clockify();
+        const user = await clockify.getUser();
+        if (!user)
+            return c.json({ ok: false, error: 'Could not connect to Clockify.' }, 500);
+        const projects = await clockify.getProjects(user.defaultWorkspace);
+        if (projects.length === 0)
+            return c.json({ ok: false, error: 'No projects found.' }, 404);
+        upsertProjects(projects);
+        return c.json({ ok: true, count: projects.length });
+    }
+    catch {
+        return c.json({ ok: false, error: 'Failed to fetch projects.' }, 500);
+    }
+});
+// Toggle project active status
+dataRoutes.post('/projects/toggle', async (c) => {
+    const { id, active } = await c.req.json();
+    if (!id)
+        return c.json({ ok: false, error: 'Project ID required.' }, 400);
+    toggleProjectActive(id, active);
+    return c.json({ ok: true });
+});
+// Sessions with pagination
+dataRoutes.get('/sessions', (c) => {
+    const page = Math.max(1, parseInt(c.req.query('page') || '1', 10));
+    const limit = Math.min(50, Math.max(1, parseInt(c.req.query('limit') || '10', 10)));
+    const offset = (page - 1) * limit;
+    const sessions = getRecentSessions(limit, offset);
+    const total = getSessionCount();
+    const allProjects = getAllProjects();
+    const projectMap = new Map(allProjects.map((p) => [p.id, p.name]));
+    const enriched = sessions.map((s) => ({
+        ...s,
+        projectName: projectMap.get(s.projectId) ?? 'Unknown',
+    }));
+    return c.json({
+        data: enriched,
+        page,
+        limit,
+        total,
+        totalPages: Math.ceil(total / limit),
+    });
+});
+export default dataRoutes;

package/dist/dashboard/routes/google.js

@@ -0,0 +1,49 @@
+import { Hono } from 'hono';
+import { google } from 'googleapis';
+import { getAuthenticatedClient, getAuthUrl, exchangeGoogleCode } from '../../lib/google.js';
+import { storeToken } from '../../lib/db.js';
+import { saveCredential } from '../../lib/credentials.js';
+const DASHBOARD_REDIRECT_URI = 'http://localhost:4001/api/google/callback';
+const SCOPES = ['https://www.googleapis.com/auth/calendar.readonly', 'https://www.googleapis.com/auth/userinfo.email'];
+const googleRoutes = new Hono();
+googleRoutes.get('/google/connect', async (c) => {
+    try {
+        const url = await getAuthUrl(DASHBOARD_REDIRECT_URI, SCOPES);
+        return c.redirect(url);
+    }
+    catch {
+        return c.json({ ok: false, error: 'Failed to generate Google auth URL.' }, 500);
+    }
+});
+googleRoutes.get('/google/auth-url', async (c) => {
+    try {
+        const url = await getAuthUrl(DASHBOARD_REDIRECT_URI, SCOPES);
+        return c.json({ url });
+    }
+    catch {
+        return c.json({ ok: false, error: 'Failed to generate Google auth URL.' }, 500);
+    }
+});
+googleRoutes.get('/google/callback', async (c) => {
+    const code = c.req.query('code');
+    if (!code) {
+        return c.text('Missing authorization code.', 400);
+    }
+    try {
+        const tokens = await exchangeGoogleCode(code, DASHBOARD_REDIRECT_URI);
+        storeToken(tokens);
+        // Fetch and store the user's email
+        const oAuth2Client = getAuthenticatedClient(DASHBOARD_REDIRECT_URI);
+        oAuth2Client.setCredentials(tokens);
+        const oauth2 = google.oauth2({ version: 'v2', auth: oAuth2Client });
+        const { data } = await oauth2.userinfo.get();
+        if (data.email) {
+            saveCredential('GOOGLE_ACCOUNT_EMAIL', data.email);
+        }
+        return c.redirect('/?google=connected');
+    }
+    catch {
+        return c.text('Failed to exchange authorization code for tokens.', 500);
+    }
+});
+export default googleRoutes;