clocktopus 1.8.1 → 1.9.0

package/README.md

@@ -49,18 +49,44 @@ That's it. Start/stop timers from the Home tab.
 
 ### 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                  |
+| 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                     |
+| `clocktopus hook:install`       | Install global git post-checkout hook      |
+| `clocktopus hook:uninstall`     | Remove the global git post-checkout hook   |
+| `clocktopus hook:install-husky` | Add `.husky/post-checkout` in current repo |
+
+### Git post-checkout hook
+
+Auto-prompt to start a timer when you `git checkout` a branch. Extracts Jira tickets from branch names (e.g. `feature/RST-100-login` → `RST-100`), fetches the ticket summary from Jira as the default description, and maps to a Clockify project.
+
+```bash
+clocktopus hook:install
+```
+
+Installs a global hook at `~/.clocktopus/hooks/post-checkout` and sets `git config --global core.hooksPath` + `init.templateDir`.
+
+**Opt out per repo:** `touch .clocktopus-ignore` at the repo root.
+**Opt out per session:** `export CLOCKTOPUS_HOOK_DISABLE=1`.
+
+#### Husky users
+
+Husky sets a **local** `core.hooksPath`, which overrides the global one — so the hook won't fire in husky repos by default. Inside each husky-enabled repo, run:
+
+```bash
+clocktopus hook:install-husky
+```
+
+This writes `.husky/post-checkout` that chains to the global hook. Commit it so teammates get it too.
 
 ### Desktop App (macOS)
 

package/dist/index.js

@@ -60,17 +60,14 @@ program
     .option('-j, --jira <ticket>', 'Jira ticket number')
     .option('--no-billable', 'Mark the time entry as non-billable')
     .action(async (message, options) => {
+    const { startTimer } = await import('./lib/start-timer.js');
     if (!isClockifyEnabled()) {
         if (!options.jira) {
             console.error(chalk.red('Jira-only mode requires --jira <ticket>.'));
             process.exit(1);
         }
-        const { v4: uuidv4 } = await import('uuid');
-        const { logSessionStart } = await import('./lib/db.js');
-        const sessionId = uuidv4();
-        const startedAt = new Date().toISOString();
         const description = (message && String(message).trim()) || options.jira;
-        logSessionStart(sessionId, null, description, startedAt, options.jira);
+        await startTimer({ description, ticket: options.jira, projectId: null, billable: options.billable });
         console.log(chalk.green(`Timer started for ${chalk.bold(options.jira)} (Jira-only mode).`));
         return;
     }
@@ -78,7 +75,6 @@ program
     let projects = await clockify.getProjects(workspaceId);
     let localProjects = await getLocalProjects();
     if (localProjects.length === 0) {
-        // If local-projects.json is empty or doesn't exist, populate it with all project IDs and names
         const allProjects = projects.map((p) => ({ id: p.id, name: p.name }));
         const localProjectsPath = path.join(__dirname, '../data/local-projects.json');
         fs.writeFileSync(localProjectsPath, JSON.stringify(allProjects, null, 2), 'utf8');
@@ -101,11 +97,14 @@ program
             choices: projects.map((p) => ({ name: p.name, value: p.id })),
         },
     ]);
-    const entry = await clockify.startTimer(workspaceId, selectedProjectId, message, options.jira, options.billable);
-    if (entry) {
-        const projectName = projects.find((p) => p.id === selectedProjectId)?.name;
-        console.log(chalk.green(`Timer started for project: ${chalk.bold(projectName)}`));
-    }
+    await startTimer({
+        description: message || options.jira || '',
+        ticket: options.jira ?? null,
+        projectId: selectedProjectId,
+        billable: options.billable,
+    });
+    const projectName = projects.find((p) => p.id === selectedProjectId)?.name;
+    console.log(chalk.green(`Timer started for project: ${chalk.bold(projectName)}`));
 });
 program
     .command('stop')
@@ -464,4 +463,60 @@ program
         console.log(chalk.yellow('Dashboard is not running.'));
     }
 });
+program
+    .command('hook:install')
+    .description('Install global git post-checkout hook (prompts to start timer on branch switch).')
+    .action(async () => {
+    const { installHook } = await import('./lib/hook-install.js');
+    await installHook();
+    console.log(chalk.green('Clocktopus post-checkout hook installed globally.'));
+    console.log(chalk.gray('  Disable per-repo: touch .clocktopus-ignore'));
+    console.log(chalk.gray('  Disable per-session: export CLOCKTOPUS_HOOK_DISABLE=1'));
+    console.log(chalk.gray('  Uninstall: clocktopus hook:uninstall'));
+    console.log();
+    console.log(chalk.yellow('Husky users: local core.hooksPath overrides global.'));
+    console.log(chalk.gray('  Inside each husky repo, run: clocktopus hook:install-husky'));
+});
+program
+    .command('hook:uninstall')
+    .description('Remove the global git post-checkout hook.')
+    .action(async () => {
+    const { uninstallHook } = await import('./lib/hook-install.js');
+    await uninstallHook();
+    console.log(chalk.green('Clocktopus post-checkout hook removed.'));
+});
+program
+    .command('hook:install-husky')
+    .description('Write a .husky/post-checkout in the current repo that chains to the global hook.')
+    .action(async () => {
+    const { installHuskyHook } = await import('./lib/husky-install.js');
+    const result = installHuskyHook(process.cwd());
+    if (result.installed) {
+        console.log(chalk.green(`Husky post-checkout installed at ${result.path}.`));
+        console.log(chalk.gray('  Commit it so teammates using husky get it too.'));
+        return;
+    }
+    if (result.reason === 'no-husky-dir') {
+        console.error(chalk.red('No .husky/ directory found. Run from the root of a husky-enabled repo.'));
+        process.exit(1);
+    }
+    if (result.reason === 'already-exists') {
+        console.log(chalk.yellow(`Existing ${result.path} left alone.`));
+        console.log(chalk.gray('  Add this line manually: exec ~/.clocktopus/hooks/post-checkout "$@"'));
+    }
+});
+program
+    .command('hook:prompt <branch>')
+    .description('(internal) Prompt to start a timer after git checkout.')
+    .action(async (branch) => {
+    const { runHookPrompt } = await import('./lib/hook-prompt.js');
+    try {
+        await runHookPrompt(branch, { cwd: process.cwd() });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        console.error(chalk.red(`Hook prompt failed: ${msg}`));
+        process.exit(0); // never block git checkout
+    }
+});
 program.parse(process.argv);

package/dist/lib/branch-parser.js

@@ -0,0 +1,7 @@
+const TICKET_REGEX = /([A-Za-z][A-Za-z0-9]+-\d+)/;
+export function extractTicket(branch) {
+    if (!branch)
+        return null;
+    const match = branch.match(TICKET_REGEX);
+    return match ? match[1].toUpperCase() : null;
+}

package/dist/lib/hook-ignore.js

@@ -0,0 +1,16 @@
+import * as fs from 'fs';
+import * as path from 'path';
+const MARKER_FILE = '.clocktopus-ignore';
+export function isRepoIgnored(cwd) {
+    if (process.env.CLOCKTOPUS_HOOK_DISABLE === '1')
+        return true;
+    let dir = path.resolve(cwd);
+    while (true) {
+        if (fs.existsSync(path.join(dir, MARKER_FILE)))
+            return true;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+}

package/dist/lib/hook-install.js

@@ -0,0 +1,35 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { getHookPaths } from './hook-paths.js';
+import { POST_CHECKOUT_SCRIPT } from './hook-script.js';
+function writeHookScript(target) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, POST_CHECKOUT_SCRIPT, { mode: 0o755 });
+}
+export async function installHook() {
+    const p = getHookPaths();
+    writeHookScript(p.hookScript);
+    writeHookScript(p.templateHookScript);
+    execSync(`git config --global core.hooksPath "${p.hooksDir}"`, { stdio: 'ignore' });
+    execSync(`git config --global init.templateDir "${p.templateDir}"`, { stdio: 'ignore' });
+}
+export async function uninstallHook() {
+    const p = getHookPaths();
+    try {
+        fs.rmSync(p.hookScript, { force: true });
+    }
+    catch { }
+    try {
+        fs.rmSync(p.templateHookScript, { force: true });
+    }
+    catch { }
+    try {
+        execSync('git config --global --unset core.hooksPath', { stdio: 'ignore' });
+    }
+    catch { }
+    try {
+        execSync('git config --global --unset init.templateDir', { stdio: 'ignore' });
+    }
+    catch { }
+}

package/dist/lib/hook-paths.js

@@ -0,0 +1,14 @@
+import * as os from 'os';
+import * as path from 'path';
+export function getHookPaths() {
+    const rootDir = path.join(os.homedir(), '.clocktopus');
+    const hooksDir = path.join(rootDir, 'hooks');
+    const templateDir = path.join(rootDir, 'git-template');
+    return {
+        rootDir,
+        hooksDir,
+        hookScript: path.join(hooksDir, 'post-checkout'),
+        templateDir,
+        templateHookScript: path.join(templateDir, 'hooks', 'post-checkout'),
+    };
+}

package/dist/lib/hook-prompt.js

@@ -0,0 +1,102 @@
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { extractTicket } from './branch-parser.js';
+import { isRepoIgnored as realIsRepoIgnored } from './hook-ignore.js';
+import { isClockifyEnabled as realIsClockifyEnabled } from './credentials.js';
+import { getJiraSummary as realGetJiraSummary } from './jira-summary.js';
+import { getOpenSession as realGetOpenSession } from './db.js';
+import { matchProjectByTicket } from './project-matcher.js';
+import { startTimer as realStartTimer } from './start-timer.js';
+function defaultReadProjects() {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    const p = path.join(__dirname, '../data/local-projects.json');
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+}
+export async function runHookPrompt(branch, opts) {
+    const d = opts.deps ?? {};
+    const isRepoIgnored = d.isRepoIgnored ?? realIsRepoIgnored;
+    const isClockifyEnabled = d.isClockifyEnabled ?? realIsClockifyEnabled;
+    const getJiraSummary = d.getJiraSummary ?? realGetJiraSummary;
+    const getOpenSession = d.getOpenSession ?? realGetOpenSession;
+    const readProjects = d.readProjects ?? defaultReadProjects;
+    const prompt = d.prompt ?? ((qs) => inquirer.prompt(qs));
+    const startTimer = d.startTimer ?? realStartTimer;
+    if (isRepoIgnored(opts.cwd)) {
+        return { started: false, ticket: null, projectId: null, description: null, reason: 'ignored' };
+    }
+    let ticket = extractTicket(branch);
+    const openSession = getOpenSession();
+    if (openSession) {
+        const answer = await prompt([
+            {
+                type: 'confirm',
+                name: 'continueAnyway',
+                message: `A timer is already running. Stop it manually first, then re-checkout. Continue anyway?`,
+                default: false,
+            },
+        ]);
+        if (!answer.continueAnyway) {
+            return { started: false, ticket, projectId: null, description: null, reason: 'declined' };
+        }
+    }
+    const promptMsg = ticket
+        ? `Start timer for ${chalk.bold(ticket)} (branch: ${branch})?`
+        : `Start timer for branch ${chalk.bold(branch)}?`;
+    const confirmAnswer = await prompt([{ type: 'confirm', name: 'confirmStart', message: promptMsg, default: true }]);
+    if (!confirmAnswer.confirmStart) {
+        return { started: false, ticket, projectId: null, description: null, reason: 'declined' };
+    }
+    if (!ticket) {
+        const ticketAnswer = await prompt([{ type: 'input', name: 'ticket', message: 'Enter ticket (empty to skip):' }]);
+        const entered = typeof ticketAnswer.ticket === 'string' ? ticketAnswer.ticket : '';
+        ticket = entered.trim() ? entered.trim().toUpperCase() : null;
+    }
+    let defaultDescription = branch;
+    if (ticket) {
+        const summary = await getJiraSummary(ticket);
+        if (summary)
+            defaultDescription = summary;
+        else
+            defaultDescription = ticket;
+    }
+    const descAnswer = await prompt([
+        { type: 'input', name: 'description', message: 'Description:', default: defaultDescription },
+    ]);
+    const description = String(descAnswer.description);
+    let projectId = null;
+    if (isClockifyEnabled()) {
+        const projects = readProjects();
+        const matched = matchProjectByTicket(ticket, projects);
+        if (matched) {
+            projectId = matched.id;
+            console.log(chalk.gray(`  Auto-selected project: ${matched.name}`));
+        }
+        else if (projects.length > 0) {
+            const picked = await prompt([
+                {
+                    type: 'list',
+                    name: 'projectId',
+                    message: 'Which project?',
+                    choices: projects.map((p) => ({ name: p.name, value: p.id })),
+                },
+            ]);
+            projectId = String(picked.projectId);
+        }
+        else {
+            console.log(chalk.yellow('No local projects configured. Run `clocktopus start` once to populate.'));
+            return { started: false, ticket, projectId: null, description, reason: 'no-ticket' };
+        }
+    }
+    await startTimer({ description, ticket, projectId, billable: true });
+    console.log(chalk.green(`Timer started${ticket ? ` for ${chalk.bold(ticket)}` : ''}.`));
+    return { started: true, ticket, projectId, description };
+}

package/dist/lib/hook-script.js

@@ -0,0 +1,29 @@
+export const POST_CHECKOUT_SCRIPT = `#!/bin/sh
+# Clocktopus post-checkout hook — auto-installed by \`clocktopus hook:install\`
+# Fires only on branch checkout (flag "1"), not on file checkout.
+
+if [ "$3" != "1" ]; then
+  exit 0
+fi
+
+# Require an attached tty; otherwise the prompt has nowhere to render.
+if ! [ -t 0 ] || ! [ -t 1 ]; then
+  exit 0
+fi
+
+# Respect user opt-out.
+if [ "$CLOCKTOPUS_HOOK_DISABLE" = "1" ]; then
+  exit 0
+fi
+
+branch=$(git symbolic-ref --short HEAD 2>/dev/null) || exit 0
+[ -z "$branch" ] && exit 0
+
+# Resolve clocktopus binary; silently skip if not installed globally.
+if ! command -v clocktopus >/dev/null 2>&1; then
+  exit 0
+fi
+
+clocktopus hook:prompt "$branch" </dev/tty >/dev/tty 2>&1 || true
+exit 0
+`;

package/dist/lib/husky-install.js

@@ -0,0 +1,21 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { getHookPaths } from './hook-paths.js';
+export function huskyHookBody() {
+    const { hookScript } = getHookPaths();
+    return `#!/bin/sh
+exec ${hookScript} "$@"
+`;
+}
+export function installHuskyHook(cwd) {
+    const huskyDir = path.join(cwd, '.husky');
+    if (!fs.existsSync(huskyDir) || !fs.statSync(huskyDir).isDirectory()) {
+        return { installed: false, reason: 'no-husky-dir' };
+    }
+    const target = path.join(huskyDir, 'post-checkout');
+    if (fs.existsSync(target)) {
+        return { installed: false, reason: 'already-exists', path: target };
+    }
+    fs.writeFileSync(target, huskyHookBody(), { mode: 0o755 });
+    return { installed: true, path: target };
+}

package/dist/lib/jira-summary.js

@@ -0,0 +1,11 @@
+import { getJiraTicket } from './jira.js';
+export async function getJiraSummary(key) {
+    try {
+        const issue = (await getJiraTicket(key));
+        const summary = issue?.fields?.summary;
+        return summary && summary.trim() ? summary.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/project-matcher.js

@@ -0,0 +1,14 @@
+export function matchProjectByTicket(ticket, projects) {
+    if (!ticket)
+        return null;
+    const prefix = ticket.split('-')[0]?.toUpperCase();
+    if (!prefix)
+        return null;
+    for (const p of projects) {
+        if (!p.ticketPrefixes)
+            continue;
+        if (p.ticketPrefixes.some((tp) => tp.toUpperCase() === prefix))
+            return p;
+    }
+    return null;
+}

package/dist/lib/start-timer.js

@@ -0,0 +1,30 @@
+import { isClockifyEnabled } from './credentials.js';
+export async function startTimer(input) {
+    if (!isClockifyEnabled()) {
+        if (!input.ticket) {
+            throw new Error('Jira-only mode: ticket required');
+        }
+        const { v4: uuidv4 } = await import('uuid');
+        const { logSessionStart } = await import('./db.js');
+        const sessionId = uuidv4();
+        const startedAt = new Date().toISOString();
+        const description = input.description?.trim() || input.ticket;
+        logSessionStart(sessionId, null, description, startedAt, input.ticket);
+        return { mode: 'jira-only', ticket: input.ticket, projectId: null, description };
+    }
+    if (!input.projectId) {
+        throw new Error('Clockify mode: projectId required');
+    }
+    const { Clockify } = await import('../clockify.js');
+    const clockify = new Clockify();
+    const user = await clockify.getUser();
+    if (!user)
+        throw new Error('Clockify auth failed');
+    await clockify.startTimer(user.defaultWorkspace, input.projectId, input.description, input.ticket ?? undefined, input.billable);
+    return {
+        mode: 'clockify',
+        ticket: input.ticket,
+        projectId: input.projectId,
+        description: input.description,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clocktopus",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "Time-tracking automation for Clockify with idle monitoring, Jira integration, Google Calendar sync, CLI, web dashboard, and desktop app.",
   "type": "module",
   "main": "dist/index.js",