@blastin-dev/clocktopus-cli 0.1.3 → 0.2.0

package/README.md

@@ -38,24 +38,142 @@ 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. |
+
+### `clocktopus agent setup`
+
+```
+clocktopus agent setup [--name <label>] [--force]
+```
+
+Configures this machine to report AI agent spend — token cost, active time,
+and the repository each session worked in — so the true cost of a piece of
+work can be measured as human time × rate **plus** agent spend.
+
+It mints an ingest token, writes the exporter configuration and installs the
+`SessionStart` / `SessionEnd` hooks into `~/.claude/settings.json`, then
+confirms the receiver accepts the token before reporting success.
+
+| Option           | Description                                                                                                     |
+| ---------------- | --------------------------------------------------------------------------------------------------------------- |
+| `--name <label>` | Label for this machine's token. Defaults to the hostname — keep it recognisable, since revocation is per token. |
+| `--force`        | Mint a replacement token instead of reusing the one already installed.                                          |
+
+Re-running without `--force` is safe and idempotent: it repairs the hooks and
+refreshes the endpoint while keeping the existing token.
+
+**Restart Claude Code afterwards.** Both the OTLP exporter and the hook read
+their configuration once, at process start, so a session that is already open
+will not pick any of it up. This is the most common reason a correct setup
+appears to do nothing.
+
+Everything lands in `~/.claude/settings.json` — the exporter environment and
+the hooks in one file. That single source of truth is what lets
+`agent doctor` say which value is actually in force. Note the ingest token is
+stored there in plaintext: if you keep `~/.claude` in a dotfiles repository,
+ignore the file.
+
+Setup then checks the repository you ran it in, because configuring the
+machine is only half the job — sessions will arrive either way, but two
+things decide whether they mean anything, and neither is visible locally:
+
+| Check                            | If it fails                                                                      |
+| -------------------------------- | -------------------------------------------------------------------------------- |
+| Repository attached to a project | Spend is recorded, but lands in the unattributed row instead of against a client |
+| Push webhook delivering          | No human time entries, so there is nothing to compare the spend against          |
+
+The second does **not** stop agent→commit links — the SessionEnd hook
+resolves `git rev-list before..after` locally and posts the list, so those
+are created with no webhook involved. What is missing is the other side of
+the comparison: true cost is human time × rate _plus_ agent spend, and one
+term alone is not a smaller answer.
+
+Both are reported separately, with the exact next step, because they send
+you to two different places. Setup only tells you — it never changes your
+GitHub settings. Note the webhook URL is **per person, not per repository**,
+so on a shared repo each teammate adds their own.
+
+### `clocktopus agent status`
+
+Shows what the receiver has actually received. Local configuration is a
+claim; this is the evidence.
+
+The two ingest lanes are reported separately because they fail separately:
+
+| Lane    | Carries                          | If it alone goes quiet                                   |
+| ------- | -------------------------------- | -------------------------------------------------------- |
+| Hook    | repository, branch, commit range | spend is recorded but cannot be attributed to a project  |
+| Metrics | tokens, cost, active time        | sessions show `$0.00`, indistinguishable from cheap work |
+
+That second failure is why there is no single "connected" line — it is the
+one that silently understates what work cost.
+
+### `clocktopus agent doctor`
+
+Checks every link in the chain and names the first one that is broken:
+settings file parses, exporter variables present, both hooks installed, the
+hook command actually executes, the receiver accepts the token, the
+repository is attached to a project and delivering commits, no other file is
+shadowing the configuration, and whether Claude Code needs restarting.
+
+The receiver check is the one that cannot be done locally — it crosses the
+network to a different host than the dashboard, so a wrong endpoint and a
+revoked token are otherwise indistinguishable from an idle afternoon.
+
+### `clocktopus agent disable`
+
+```
+clocktopus agent disable [--revoke]
+```
+
+Removes this machine's telemetry configuration, leaving any hooks and
+environment variables you added yourself untouched.
+
+| Option     | Description                                                 |
+| ---------- | ----------------------------------------------------------- |
+| `--revoke` | Also revoke the ingest token, making it useless everywhere. |
+
+Stopping and revoking are separate on purpose: removing the local
+configuration stops _this_ machine reporting, but does nothing about a token
+that has already been copied elsewhere or committed.
 
 ## 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`
 
 Run `clocktopus logout` to clear stored credentials.
+
+The agent telemetry setup deliberately keeps **no** copy of the ingest token
+here. It has to live in `~/.claude/settings.json` for Claude Code's exporter
+to read it, and a second copy would be another thing to leak and another
+thing to fall out of date. Only the token id (needed to revoke) and its
+display prefix are kept.

package/dist/src/commands/agent/disable.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Removes this machine's telemetry configuration.
+ *
+ * Stopping and revoking are separate on purpose. Removing the local
+ * configuration stops *this* machine reporting; it does nothing about a
+ * token that has already been copied elsewhere or committed to a dotfiles
+ * repository. `--revoke` is the one that makes the token useless everywhere,
+ * and it is opt-in because the common case — moving machines, reinstalling —
+ * should not invalidate a token that CI or another workstation still uses.
+ */
+export declare function disableCommand(options: {
+    revoke?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=disable.d.ts.map

package/dist/src/commands/agent/disable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disable.d.ts","sourceRoot":"","sources":["../../../../src/commands/agent/disable.ts"],"names":[],"mappings":"AAcA;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+EhB"}

package/dist/src/commands/agent/disable.js

@@ -0,0 +1,72 @@
+import { clearHookState } from "../../lib/agent-hook-state.js";
+import { ApiError, request } from "../../lib/api.js";
+import { readSettings, removeTelemetrySettings, SettingsParseError, writeSettings, } from "../../lib/claude-settings.js";
+import { clearAgentConfig, getAgentConfig, isLoggedIn, } from "../../lib/config.js";
+/**
+ * Removes this machine's telemetry configuration.
+ *
+ * Stopping and revoking are separate on purpose. Removing the local
+ * configuration stops *this* machine reporting; it does nothing about a
+ * token that has already been copied elsewhere or committed to a dotfiles
+ * repository. `--revoke` is the one that makes the token useless everywhere,
+ * and it is opt-in because the common case — moving machines, reinstalling —
+ * should not invalidate a token that CI or another workstation still uses.
+ */
+export async function disableCommand(options) {
+    let removedEnvKeys = [];
+    let removedHooks = false;
+    try {
+        const current = readSettings();
+        if (current.exists) {
+            const result = removeTelemetrySettings(current.settings);
+            removedEnvKeys = result.removedEnvKeys;
+            removedHooks = result.removedHooks;
+            if (removedEnvKeys.length > 0 || removedHooks) {
+                writeSettings(result.settings, current.path);
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof SettingsParseError) {
+            console.error(`✗ ${error.message}`);
+            process.exit(1);
+        }
+        throw error;
+    }
+    const agent = getAgentConfig();
+    if (options.revoke) {
+        if (!agent.tokenId) {
+            console.log("⚠ No token id on record, so nothing was revoked. This machine's token\n" +
+                "  was minted by an older version or on another machine — revoke it\n" +
+                "  from the dashboard instead.");
+        }
+        else if (!isLoggedIn()) {
+            console.log("⚠ Not logged in, so the token could not be revoked. Run 'clocktopus\n" +
+                "  login' and try again — the local configuration was still removed.");
+        }
+        else {
+            try {
+                await request(`/api/agent/ingest-token?tokenId=${encodeURIComponent(agent.tokenId)}`, { method: "DELETE" });
+                console.log(`✓ Revoked ${agent.tokenPrefix ?? "the ingest token"}.`);
+            }
+            catch (error) {
+                console.error(`✗ Could not revoke the token: ${error instanceof ApiError || error instanceof Error
+                    ? error.message
+                    : "unknown error"}`);
+                console.error("  The local configuration was still removed.");
+            }
+        }
+    }
+    clearAgentConfig();
+    clearHookState();
+    if (removedEnvKeys.length === 0 && !removedHooks) {
+        console.log("Nothing to remove — agent telemetry was not configured here.");
+        return;
+    }
+    console.log(`✓ Removed ${removedEnvKeys.length} environment variable(s)${removedHooks ? " and the session hooks" : ""} from settings.json.`);
+    if (!options.revoke) {
+        console.log("\nThe ingest token is still valid. Revoke it with\n" +
+            "  clocktopus agent disable --revoke");
+    }
+    console.log("\nRestart Claude Code to stop the current session reporting.");
+}

package/dist/src/commands/agent/doctor.d.ts

@@ -0,0 +1,2 @@
+export declare function doctorCommand(): Promise<void>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/src/commands/agent/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../../src/commands/agent/doctor.ts"],"names":[],"mappings":"AAoCA,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CA8GnD"}

package/dist/src/commands/agent/doctor.js

@@ -0,0 +1,235 @@
+import { execSync } from "node:child_process";
+import { isAfter, parseISO } from "date-fns";
+import { findShadowedExports, maskToken, resolveAgentCredentials, } from "../../lib/agent-config.js";
+import { readLastRun } from "../../lib/agent-hook-state.js";
+import { verifyReceiver } from "../../lib/agent-receiver.js";
+import { readInstalledTelemetry, SettingsParseError, TELEMETRY_ENV_KEYS, } from "../../lib/claude-settings.js";
+import { isLoggedIn } from "../../lib/config.js";
+import { formatAgo } from "../../lib/format.js";
+import { fetchRepoStatus, repoChecks } from "../../lib/repo-guidance.js";
+export async function doctorCommand() {
+    const checks = [];
+    checks.push({
+        label: "Logged in",
+        ok: isLoggedIn(),
+        detail: isLoggedIn() ? "yes" : "no",
+        fix: "clocktopus login",
+    });
+    let installed = null;
+    try {
+        installed = readInstalledTelemetry();
+        checks.push({
+            label: "settings.json",
+            ok: installed.exists,
+            detail: installed.exists
+                ? `${installed.path} (modified ${formatAgo(installed.modifiedAt?.toISOString() ?? null)})`
+                : `${installed.path} does not exist`,
+            fix: "clocktopus agent setup",
+        });
+    }
+    catch (error) {
+        if (error instanceof SettingsParseError) {
+            checks.push({
+                label: "settings.json",
+                ok: false,
+                detail: "is not valid JSON",
+                fix: "Fix or move the file, then run 'clocktopus agent setup'",
+            });
+            report(checks);
+            return;
+        }
+        throw error;
+    }
+    const missingEnv = TELEMETRY_ENV_KEYS.filter((key) => !installed?.env[key]);
+    checks.push({
+        label: "Exporter config",
+        ok: missingEnv.length === 0,
+        detail: missingEnv.length === 0
+            ? `all ${TELEMETRY_ENV_KEYS.length} variables set`
+            : // Listing nine names when none are set is noise; the useful
+                // signal there is simply "nothing is configured".
+                missingEnv.length === TELEMETRY_ENV_KEYS.length
+                    ? "not configured in settings.json"
+                    : `missing ${missingEnv.join(", ")}`,
+        fix: "clocktopus agent setup",
+    });
+    // Both events are required, and for different reasons: SessionStart is the
+    // only source of the *before* SHA and of `cwd`, SessionEnd is the only
+    // source of the exact commit list. One without the other silently
+    // degrades what can be attributed.
+    const hookStart = installed.hookCommands.SessionStart;
+    const hookEnd = installed.hookCommands.SessionEnd;
+    checks.push({
+        label: "Hooks installed",
+        ok: Boolean(hookStart && hookEnd),
+        detail: hookStart && hookEnd
+            ? `SessionStart, SessionEnd → ${hookStart}`
+            : `missing ${[!hookStart && "SessionStart", !hookEnd && "SessionEnd"].filter(Boolean).join(", ")}`,
+        fix: "clocktopus agent setup",
+    });
+    if (hookStart) {
+        checks.push(checkHookRuns(hookStart));
+    }
+    const credentials = resolveAgentCredentials();
+    checks.push({
+        label: "Token in force",
+        ok: credentials.token !== null,
+        detail: credentials.token
+            ? `${maskToken(credentials.token)} (from ${credentials.tokenSource})`
+            : "none resolved",
+        fix: "clocktopus agent setup",
+    });
+    if (credentials.token && credentials.endpoint) {
+        const check = await verifyReceiver(credentials.endpoint, credentials.token);
+        checks.push({
+            label: "Receiver",
+            ok: check.ok,
+            detail: check.ok
+                ? `${credentials.endpoint} accepted the token`
+                : check.reason === "invalid_token"
+                    ? `${credentials.endpoint} rejected the token (401)`
+                    : check.reason === "unexpected_status"
+                        ? `${credentials.endpoint} answered HTTP ${check.status}`
+                        : `${credentials.endpoint} unreachable — ${check.message}`,
+            fix: check.ok || check.reason !== "invalid_token"
+                ? "Check the endpoint is reachable from this network"
+                : "clocktopus agent setup --force  (mints a replacement token)",
+        });
+    }
+    // Past this point the pipeline works; these two decide whether what it
+    // carries can be turned into a number. Both are server-side facts about
+    // the repository, not about this machine.
+    const repoStatus = await fetchRepoStatus();
+    if (repoStatus)
+        checks.push(...repoChecks(repoStatus));
+    checks.push(checkShadowedExports());
+    checks.push(checkRestartNeeded(installed.modifiedAt));
+    checks.push(checkLastHookRun());
+    report(checks);
+}
+/**
+ * Runs the installed hook command with empty stdin.
+ *
+ * This is a genuine no-op — the hook returns immediately when stdin carries
+ * no payload — so it sends nothing and records nothing, while still proving
+ * the exact command line in settings.json resolves and executes. Worth
+ * checking directly: hooks run under a shell whose PATH may differ from the
+ * interactive one, and a command that fails to resolve there fails
+ * silently, costing every session its repository context.
+ */
+function checkHookRuns(command) {
+    try {
+        execSync(command, {
+            input: "",
+            timeout: 15_000,
+            stdio: ["pipe", "ignore", "ignore"],
+        });
+        return {
+            label: "Hook executes",
+            ok: true,
+            detail: "command resolved and ran",
+        };
+    }
+    catch (error) {
+        return {
+            label: "Hook executes",
+            ok: false,
+            detail: `'${command}' failed — ${error instanceof Error ? error.message.split("\n")[0] : "unknown error"}`,
+            fix: "clocktopus agent setup  (rewrites the hook with a resolvable path)",
+        };
+    }
+}
+function checkShadowedExports() {
+    const shadowed = findShadowedExports();
+    if (shadowed.length === 0) {
+        return {
+            label: "Config conflicts",
+            ok: true,
+            detail: "settings.json is the only source",
+        };
+    }
+    return {
+        label: "Config conflicts",
+        ok: "warn",
+        detail: shadowed
+            .map(({ path, keys }) => `${path} exports ${keys.join(", ")}`)
+            .join("; "),
+        fix: "settings.json is applied over the inherited environment, so these are\n" +
+            "      ignored inside Claude Code. Remove them — two sources that\n" +
+            "      disagree is how spend lands on the wrong account.",
+    };
+}
+/**
+ * Did the configuration change after the last session used it?
+ *
+ * The exporter and the hook both read their configuration once, at process
+ * start, so a session already open when setup ran is still using the old
+ * values. This is the most common reason a correct configuration looks dead.
+ */
+function checkRestartNeeded(settingsModifiedAt) {
+    const lastRun = readLastRun();
+    if (!settingsModifiedAt || !lastRun?.at) {
+        return {
+            label: "Restart",
+            ok: "warn",
+            detail: "the hook has not run since this configuration was written",
+            fix: "Restart Claude Code, then run 'clocktopus agent status'",
+        };
+    }
+    const ranAfterConfig = isAfter(parseISO(lastRun.at), settingsModifiedAt);
+    return {
+        label: "Restart",
+        ok: ranAfterConfig ? true : "warn",
+        detail: ranAfterConfig
+            ? "a session has run since the last configuration change"
+            : "settings.json changed after the last session started",
+        fix: "Restart Claude Code so the exporter and hook pick up the new values",
+    };
+}
+function checkLastHookRun() {
+    const lastRun = readLastRun();
+    if (!lastRun) {
+        return {
+            label: "Last hook run",
+            ok: "warn",
+            detail: "no record — the hook has not run on this machine",
+            fix: "Restart Claude Code and start a session",
+        };
+    }
+    const failed = lastRun.status === null ||
+        lastRun.status === undefined ||
+        lastRun.status < 200 ||
+        lastRun.status >= 300;
+    return {
+        label: "Last hook run",
+        ok: !failed,
+        detail: failed
+            ? `${formatAgo(lastRun.at)} — ${lastRun.status ? `HTTP ${lastRun.status}` : (lastRun.error ?? "no response")}`
+            : `${formatAgo(lastRun.at)} — HTTP ${lastRun.status}`,
+        fix: lastRun.status === 401
+            ? "clocktopus agent setup --force  (the token was rejected)"
+            : "Check network access to the receiver",
+    };
+}
+function report(checks) {
+    console.log("\nAgent telemetry diagnosis\n");
+    for (const check of checks) {
+        const symbol = check.ok === true ? "✓" : check.ok === "warn" ? "⚠" : "✗";
+        console.log(`  ${symbol} ${check.label.padEnd(18)}${check.detail}`);
+        if (check.ok !== true && check.fix) {
+            console.log(`    → ${check.fix}`);
+        }
+    }
+    const failures = checks.filter((check) => check.ok === false).length;
+    const warnings = checks.filter((check) => check.ok === "warn").length;
+    console.log("");
+    if (failures === 0 && warnings === 0) {
+        console.log("Everything checks out. 'clocktopus agent status' shows what has arrived.");
+    }
+    else {
+        console.log(`${failures} failing, ${warnings} to review. Fix the first failure above —\n` +
+            "the later ones are usually consequences of it.");
+    }
+    if (failures > 0)
+        process.exitCode = 1;
+}

package/dist/src/commands/agent/hook.d.ts

@@ -0,0 +1,2 @@
+export declare function hookCommand(): Promise<void>;
+//# sourceMappingURL=hook.d.ts.map

package/dist/src/commands/agent/hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../../../src/commands/agent/hook.ts"],"names":[],"mappings":"AAuRA,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAMjD"}