@blastin-dev/clocktopus-cli 0.1.2 → 0.1.4

package/README.md

@@ -38,23 +38,38 @@ Clear stored credentials.
 
 Display the current authenticated user.
 
-### `clocktopus clock in`
+### `clocktopus clock (in|out)`
 
-Record a clock-in signal.
+```
+clocktopus clock (in|out) [--ago <duration> | --at <time>]
+```
 
-### `clocktopus clock out`
+Record the start or end of a work session. Defaults to "now" when no
+flag is passed.
 
-Record a clock-out signal.
+| Option | Description |
+| --- | --- |
+| `--ago <duration>` | Backdate by a duration from now (`15m`, `1h`, `1h30m`). Mutually exclusive with `--at`. |
+| `--at <time>` | Backdate to an absolute wall-clock time today (`HH:mm` or `HH:mm:ss`). |
 
 ### `clocktopus clock status`
 
-Show signals for a given date.
+```
+clocktopus clock status [-d <YYYY-MM-DD>]
+```
+
+Show clock signals for a given date.
+
+| Option | Description |
+| --- | --- |
+| `-d, --date <date>` | Show signals for a specific date in `YYYY-MM-DD` format. Defaults to today. |
 
 ## Token Storage
 
 Credentials are stored in a platform-specific config directory:
 
-- **macOS**: `~/Library/Preferences/clocktopus-cli-nodejs/config.json`
+- **macOS**: `~/Library/Preferences/clocktopus-cli-nodejs/conf
+ig.json`
 - **Linux**: `~/.config/clocktopus-cli-nodejs/config.json`
 - **Windows**: `%APPDATA%/clocktopus-cli-nodejs/config.json`
 

package/dist/src/commands/clock.d.ts

@@ -1,11 +1,33 @@
 /**
- * Record a clock-in signal for today
+ * Record a clock-in signal for today.
+ *
+ * Accepts the same backdate flags as `clock out`:
+ *   --ago <duration>  e.g. "45m", "1h", "1h30m"
+ *   --at  <HH:mm>     absolute wall-clock time in the user's timezone
+ *
+ * The server silently clamps the requested time if it would fall outside
+ * the allowed window (before start-of-today, before the day's last
+ * clock-out, or after the first existing time entry on the day).
  */
-export declare function clockInCommand(): Promise<void>;
+export declare function clockInCommand(options?: {
+    ago?: string;
+    at?: string;
+}): Promise<void>;
 /**
- * Record a clock-out signal for today
+ * Record a clock-out signal for today.
+ *
+ * Accepts optional backdate flags:
+ *   --ago <duration>  e.g. "45m", "1h", "1h30m"
+ *   --at  <HH:mm>     absolute wall-clock time in the user's timezone
+ *
+ * The two flags are mutually exclusive. The server silently clamps the
+ * requested time if it would predate the session's clock-in or the
+ * session's last time entry.
  */
-export declare function clockOutCommand(): Promise<void>;
+export declare function clockOutCommand(options?: {
+    ago?: string;
+    at?: string;
+}): Promise<void>;
 /**
  * Show clock signals status for a given date (default: today)
  */

package/dist/src/commands/clock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../../src/commands/clock.ts"],"names":[],"mappings":"AAuDA;;GAEG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAqCpD;AAED;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAuCrD;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,IAAI,CAAC,CAiDhB"}
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../../src/commands/clock.ts"],"names":[],"mappings":"AAgFA;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1C,OAAO,CAAC,IAAI,CAAC,CA0Ef;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1C,OAAO,CAAC,IAAI,CAAC,CAsEf;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,IAAI,CAAC,CAiDhB"}

package/dist/src/commands/clock.js

@@ -16,8 +16,30 @@ const ClockSignalResponseSchema = z.object({
         signalTimestamp: z.string(),
         alreadyExists: z.boolean(),
         blockedReason: z.enum(["already_clocked_in", "not_clocked_in"]).nullable(),
+        clamped: z.boolean().optional(),
+        requestedTime: z.string().nullable().optional(),
+        reopened: z.boolean().optional(),
     }),
 });
+/**
+ * Parses "15m", "1h", "1h30m" → whole minutes. Mirrors
+ * `packages/core/src/utils/duration.ts` (the CLI is a standalone package
+ * and doesn't depend on @repo/core).
+ */
+function parseDurationToMinutes(input) {
+    const trimmed = input.trim().toLowerCase();
+    const match = /^(?:(\d+)h)?(?:(\d+)m)?$/.exec(trimmed);
+    if (!match || (!match[1] && !match[2])) {
+        throw new Error(`Invalid duration "${input}". Use formats like 15m, 1h, or 1h30m.`);
+    }
+    const hours = match[1] ? Number(match[1]) : 0;
+    const minutes = match[2] ? Number(match[2]) : 0;
+    const total = hours * 60 + minutes;
+    if (total <= 0) {
+        throw new Error(`Duration must be greater than zero: "${input}".`);
+    }
+    return total;
+}
 /**
  * Schema for clock signals list response
  */
@@ -44,14 +66,43 @@ function formatSignalType(type) {
     return type === "clock_in" ? "Clock In" : "Clock Out";
 }
 /**
- * Record a clock-in signal for today
+ * Record a clock-in signal for today.
+ *
+ * Accepts the same backdate flags as `clock out`:
+ *   --ago <duration>  e.g. "45m", "1h", "1h30m"
+ *   --at  <HH:mm>     absolute wall-clock time in the user's timezone
+ *
+ * The server silently clamps the requested time if it would fall outside
+ * the allowed window (before start-of-today, before the day's last
+ * clock-out, or after the first existing time entry on the day).
  */
-export async function clockInCommand() {
+export async function clockInCommand(options = {}) {
     if (!checkAuth()) {
         process.exit(1);
     }
+    if (options.ago && options.at) {
+        console.error("Cannot use --ago and --at together. Pick one.");
+        process.exit(1);
+    }
+    const body = { signalType: "clock_in" };
+    if (options.ago) {
+        try {
+            body.minutesAgo = parseDurationToMinutes(options.ago);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    }
+    if (options.at) {
+        if (!/^\d{2}:\d{2}(:\d{2})?$/.test(options.at)) {
+            console.error(`Invalid time "${options.at}". Use HH:mm or HH:mm:ss format.`);
+            process.exit(1);
+        }
+        body.effectiveTime = options.at;
+    }
     try {
-        const data = await post("/api/clock-signal", { signalType: "clock_in" });
+        const data = await post("/api/clock-signal", body);
         const response = ClockSignalResponseSchema.parse(data);
         if (response.signal.alreadyExists) {
             console.log(`\nAlready clocked in - must clock out first.`);
@@ -60,11 +111,21 @@ export async function clockInCommand() {
             console.log(`    Time: ${response.signal.effectiveTime}`);
             console.log(`    Timezone: ${response.signal.timezone}`);
         }
+        else if (response.signal.reopened) {
+            console.log(`\nPrevious session reopened — clock-out removed.`);
+            console.log(`  Clocked in since:`);
+            console.log(`    Date: ${response.signal.workDate}`);
+            console.log(`    Time: ${response.signal.effectiveTime}`);
+            console.log(`    Timezone: ${response.signal.timezone}`);
+        }
         else {
             console.log(`\nClock In recorded!`);
             console.log(`  Date: ${response.signal.workDate}`);
             console.log(`  Time: ${response.signal.effectiveTime}`);
             console.log(`  Timezone: ${response.signal.timezone}`);
+            if (response.signal.clamped && response.signal.requestedTime) {
+                console.log(`  Adjusted: you asked for ${response.signal.requestedTime}, but that's outside the allowed window for this day.`);
+            }
         }
     }
     catch (error) {
@@ -83,14 +144,43 @@ export async function clockInCommand() {
     }
 }
 /**
- * Record a clock-out signal for today
+ * Record a clock-out signal for today.
+ *
+ * Accepts optional backdate flags:
+ *   --ago <duration>  e.g. "45m", "1h", "1h30m"
+ *   --at  <HH:mm>     absolute wall-clock time in the user's timezone
+ *
+ * The two flags are mutually exclusive. The server silently clamps the
+ * requested time if it would predate the session's clock-in or the
+ * session's last time entry.
  */
-export async function clockOutCommand() {
+export async function clockOutCommand(options = {}) {
     if (!checkAuth()) {
         process.exit(1);
     }
+    if (options.ago && options.at) {
+        console.error("Cannot use --ago and --at together. Pick one.");
+        process.exit(1);
+    }
+    const body = { signalType: "clock_out" };
+    if (options.ago) {
+        try {
+            body.minutesAgo = parseDurationToMinutes(options.ago);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    }
+    if (options.at) {
+        if (!/^\d{2}:\d{2}(:\d{2})?$/.test(options.at)) {
+            console.error(`Invalid time "${options.at}". Use HH:mm or HH:mm:ss format.`);
+            process.exit(1);
+        }
+        body.effectiveTime = options.at;
+    }
     try {
-        const data = await post("/api/clock-signal", { signalType: "clock_out" });
+        const data = await post("/api/clock-signal", body);
         const response = ClockSignalResponseSchema.parse(data);
         if (response.signal.alreadyExists) {
             console.log(`\nNot clocked in - must clock in first.`);
@@ -106,6 +196,9 @@ export async function clockOutCommand() {
             console.log(`  Date: ${response.signal.workDate}`);
             console.log(`  Time: ${response.signal.effectiveTime}`);
             console.log(`  Timezone: ${response.signal.timezone}`);
+            if (response.signal.clamped && response.signal.requestedTime) {
+                console.log(`  Adjusted: you asked for ${response.signal.requestedTime}, but that's before this session's earliest allowed time.`);
+            }
         }
     }
     catch (error) {

package/dist/src/commands/login.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../../src/commands/login.ts"],"names":[],"mappings":"AAKA,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAsFlD"}
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../../src/commands/login.ts"],"names":[],"mappings":"AAKA,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAmFlD"}

package/dist/src/commands/login.js

@@ -1,12 +1,12 @@
 import { get } from "../lib/api.js";
 import { pollForToken, requestDeviceCode, sleep } from "../lib/auth.js";
-import { isLoggedIn, setToken } from "../lib/config.js";
+import { setToken } from "../lib/config.js";
 import { UserSchema } from "../lib/validators.js";
 export async function loginCommand() {
-    if (isLoggedIn()) {
-        console.log("You are already logged in. Use 'clocktopus logout' to log out first.");
-        return;
-    }
+    // If the user is already logged in we still start a fresh device flow
+    // — `setToken` on success overwrites the existing token. We don't
+    // clear the old token up-front, so a failed/cancelled/timed-out login
+    // leaves the previously-valid session intact.
     console.log("Starting device authorization...\n");
     try {
         const deviceCode = await requestDeviceCode();

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAqEA,wBAAgB,GAAG,IAAI,IAAI,CAE1B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAgGA,wBAAgB,GAAG,IAAI,IAAI,CAE1B"}

package/dist/src/index.js

@@ -1,14 +1,21 @@
+import { createRequire } from "node:module";
 import { Command } from "commander";
+import { z } from "zod";
 import { clockInCommand, clockOutCommand, clockStatusCommand, } from "./commands/clock.js";
 import { loginCommand } from "./commands/login.js";
 import { logoutCommand } from "./commands/logout.js";
 import { whoamiCommand } from "./commands/whoami.js";
-import { ENVIRONMENTS, setRuntimeEnvironment, } from "./lib/config.js";
+import { ENVIRONMENTS, setRuntimeEnvironment } from "./lib/config.js";
+const require = createRequire(import.meta.url);
+const parsedJson = z
+    .object({ version: z.string() })
+    .safeParse(require("../../package.json"));
+const version = parsedJson.success ? parsedJson.data.version : "0.0.0";
 const program = new Command();
 program
     .name("clocktopus")
     .description("CLI for Clocktopus time tracking")
-    .version("0.1.0")
+    .version(version)
     .option("-e, --env <environment>", "Use environment (dev or prod)")
     .hook("preAction", (thisCommand) => {
     const opts = thisCommand.opts();
@@ -38,12 +45,16 @@ const clock = program
     .description("Record clock-in and clock-out signals");
 clock
     .command("in")
-    .description("Record clock-in for today")
-    .action(clockInCommand);
+    .description("Record clock-in for today (optionally backdated)")
+    .option("--ago <duration>", "Backdate by a duration relative to now (e.g. 45m, 1h, 1h30m)")
+    .option("--at <time>", "Backdate to an absolute time in your timezone (HH:mm or HH:mm:ss)")
+    .action((options) => clockInCommand(options));
 clock
     .command("out")
-    .description("Record clock-out for today")
-    .action(clockOutCommand);
+    .description("Record clock-out for today (optionally backdated)")
+    .option("--ago <duration>", "Backdate by a duration relative to now (e.g. 45m, 1h, 1h30m)")
+    .option("--at <time>", "Backdate to an absolute time in your timezone (HH:mm or HH:mm:ss)")
+    .action((options) => clockOutCommand(options));
 clock
     .command("status")
     .description("Show clock signals for a specific date")

package/dist/src/lib/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/lib/api.ts"],"names":[],"mappings":"AAEA,KAAK,cAAc,GAAG;IACpB,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,qBAAa,QAAS,SAAQ,KAAK;IAExB,MAAM,EAAE,MAAM;IACd,UAAU,EAAE,MAAM;gBADlB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EACzB,OAAO,CAAC,EAAE,MAAM;CAKnB;AAED,wBAAsB,OAAO,CAAC,CAAC,EAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,CAAC,CAAC,CA6BZ;AAED,wBAAsB,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,UAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAE3E;AAED,wBAAsB,IAAI,CAAC,CAAC,EAC1B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,aAAa,UAAO,GACnB,OAAO,CAAC,CAAC,CAAC,CAEZ"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/lib/api.ts"],"names":[],"mappings":"AAEA,KAAK,cAAc,GAAG;IACpB,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,qBAAa,QAAS,SAAQ,KAAK;IAExB,MAAM,EAAE,MAAM;IACd,UAAU,EAAE,MAAM;gBADlB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EACzB,OAAO,CAAC,EAAE,MAAM;CAKnB;AAED,wBAAsB,OAAO,CAAC,CAAC,EAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAqCZ;AAuBD,wBAAsB,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,UAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAE3E;AAED,wBAAsB,IAAI,CAAC,CAAC,EAC1B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,aAAa,UAAO,GACnB,OAAO,CAAC,CAAC,CAAC,CAEZ"}

package/dist/src/lib/api.js

@@ -29,10 +29,37 @@ export async function request(path, options = {}) {
     });
     if (!response.ok) {
         const errorText = await response.text();
-        throw new ApiError(response.status, response.statusText, errorText);
+        // The frontend's `handleApiError` serializes errors as
+        // `{ error: { message, stack? }, timestamp, path }`. Pull the
+        // `message` out so the user sees the actual reason (e.g. "Signal
+        // time cannot be in the future…") rather than a raw JSON blob.
+        throw new ApiError(response.status, response.statusText, extractErrorMessage(errorText) ?? errorText);
     }
     return response.json();
 }
+function extractErrorMessage(body) {
+    if (!body)
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed && typeof parsed === "object") {
+            const record = parsed;
+            const err = record.error;
+            if (err && typeof err === "object") {
+                const msg = err.message;
+                if (typeof msg === "string" && msg.length > 0)
+                    return msg;
+            }
+            if (typeof record.message === "string" && record.message.length > 0) {
+                return record.message;
+            }
+        }
+    }
+    catch {
+        // Not JSON — fall through and let the caller show the raw text.
+    }
+    return null;
+}
 export async function get(path, authenticated = true) {
     return request(path, { method: "GET", authenticated });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blastin-dev/clocktopus-cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "bin": {
     "clocktopus": "./dist/bin/clocktopus.js"
@@ -11,16 +11,17 @@
   "dependencies": {
     "commander": "^13.0.0",
     "conf": "^13.0.0",
-    "zod": "4.1.12",
-    "date-fns": "4.1.0"
+    "date-fns": "4.1.0",
+    "zod": "4.1.12"
   },
   "devDependencies": {
     "@types/node": "22.15.3",
-    "eslint": "^9.28.0",
+    "eslint": "9.37.0",
+    "eslint-plugin-import-x": "^4.16.1",
     "typescript": "5.9.2",
     "@repo/eslint-config": "0.0.0",
-    "@repo/typescript-config": "0.0.0",
-    "@repo/prettier-config": "0.1.0"
+    "@repo/prettier-config": "0.1.0",
+    "@repo/typescript-config": "0.0.0"
   },
   "prettier": "@repo/prettier-config",
   "scripts": {