@blastin-dev/clocktopus-cli 0.1.3 → 0.2.0

package/dist/src/lib/agent-receiver.js

@@ -0,0 +1,44 @@
+/**
+ * Talks to the OTLP receiver directly, which is the whole point.
+ *
+ * The receiver is a different host from the web app — its own Router, its
+ * own Lambda, its own domain — so a token that works against the dashboard
+ * proves nothing about whether telemetry can reach ingest. This check is
+ * the only local way to tell "nothing has happened yet" apart from "nothing
+ * can happen": a wrong endpoint, a revoked token and an idle afternoon all
+ * look identical otherwise.
+ */
+const TIMEOUT_MS = 8000;
+export async function verifyReceiver(endpoint, token) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+        const response = await fetch(`${endpoint.replace(/\/$/, "")}/v1/verify`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${token}`,
+            },
+            body: "{}",
+            signal: controller.signal,
+        });
+        if (response.ok)
+            return { ok: true };
+        if (response.status === 401)
+            return { ok: false, reason: "invalid_token" };
+        // A 404 here is worth distinguishing in the caller's advice: it means the
+        // URL resolved to something that is not this receiver, or to a receiver
+        // deployed before /v1/verify existed.
+        return { ok: false, reason: "unexpected_status", status: response.status };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "unreachable",
+            message: error instanceof Error ? error.message : "request failed",
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

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/dist/src/lib/claude-settings.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Reads and edits `~/.claude/settings.json` on the user's behalf.
+ *
+ * Two rules govern everything here, both of them about not destroying a file
+ * we do not own:
+ *
+ * 1. **Never write over JSON we could not parse.** A malformed settings file
+ *    is far more likely to be a half-finished edit than something to
+ *    overwrite, and overwriting it would lose the user's own hooks,
+ *    permissions and MCP servers. Parse failures raise instead.
+ * 2. **Only ever touch keys we put there.** Merging into `env` and appending
+ *    to `hooks` leaves everything else untouched, and removal matches our
+ *    own hook command rather than clearing the arrays.
+ */
+export declare const SETTINGS_FILENAME = "settings.json";
+/** Env keys `clocktopus agent setup` owns — and the only ones it removes. */
+export declare const TELEMETRY_ENV_KEYS: readonly ["CLAUDE_CODE_ENABLE_TELEMETRY", "OTEL_METRICS_EXPORTER", "OTEL_EXPORTER_OTLP_PROTOCOL", "OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_HEADERS", "OTEL_METRICS_INCLUDE_SESSION_ID", "OTEL_METRIC_EXPORT_INTERVAL", "CLOCKTOPUS_INGEST_TOKEN", "CLOCKTOPUS_OTEL_ENDPOINT"];
+/**
+ * How often Claude Code's exporter ships metrics.
+ *
+ * Also the resolution of every "last export received" answer the status
+ * command can give — a session that started 30s ago has genuinely not
+ * exported yet, which is why status treats silence under one interval as
+ * "waiting" rather than "broken".
+ */
+export declare const METRIC_EXPORT_INTERVAL_MS = 60000;
+/**
+ * Seconds Claude Code will wait for the hook before giving up on it.
+ *
+ * Comfortably above the hook's own 4s request timeout, so a slow network
+ * produces the hook's own recorded failure — which `agent doctor` can read
+ * back — rather than a kill from the host, which leaves no trace anywhere.
+ */
+export declare const HOOK_TIMEOUT_SECONDS = 10;
+export type ClaudeSettings = Record<string, unknown>;
+export declare class SettingsParseError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+export declare function claudeConfigDir(): string;
+export declare function settingsPath(): string;
+export declare function readSettings(path?: string): {
+    path: string;
+    exists: boolean;
+    modifiedAt: Date | null;
+    settings: ClaudeSettings;
+};
+/**
+ * Writes settings, keeping a one-deep backup of what was there before.
+ *
+ * The rename is what makes it atomic: a crash midway leaves either the old
+ * file or the new one, never a truncated file that Claude Code would refuse
+ * to start with.
+ */
+export declare function writeSettings(settings: ClaudeSettings, path?: string): {
+    backupPath: string | null;
+};
+export declare function buildTelemetryEnv(input: {
+    token: string;
+    endpoint: string;
+}): Record<string, string>;
+declare const HOOK_EVENTS: readonly ["SessionStart", "SessionEnd"];
+export declare function applyTelemetrySettings(settings: ClaudeSettings, input: {
+    token: string;
+    endpoint: string;
+    hookCommand: string;
+}): ClaudeSettings;
+export declare function removeTelemetrySettings(settings: ClaudeSettings): {
+    settings: ClaudeSettings;
+    removedEnvKeys: string[];
+    removedHooks: boolean;
+};
+/** What settings.json currently declares, for `status` and `doctor`. */
+export declare function readInstalledTelemetry(path?: string): {
+    path: string;
+    exists: boolean;
+    modifiedAt: Date | null;
+    env: Record<string, string>;
+    hookCommands: Partial<Record<(typeof HOOK_EVENTS)[number], string>>;
+};
+export {};
+//# sourceMappingURL=claude-settings.d.ts.map

package/dist/src/lib/claude-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-settings.d.ts","sourceRoot":"","sources":["../../../src/lib/claude-settings.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAEjD,6EAA6E;AAC7E,eAAO,MAAM,kBAAkB,yRAUrB,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AASrD,qBAAa,kBAAmB,SAAQ,KAAK;aACf,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM;CAMzC;AAED,wBAAgB,eAAe,IAAI,MAAM,CAIxC;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,YAAY,CAAC,IAAI,SAAiB,GAAG;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,cAAc,CAAC;CAC1B,CA6BA;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,cAAc,EACxB,IAAI,SAAiB,GACpB;IAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAiB/B;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBzB;AAED,QAAA,MAAM,WAAW,yCAA0C,CAAC;AAqC5D,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,cAAc,EACxB,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC9D,cAAc,CA6ChB;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,cAAc,GAAG;IACjE,QAAQ,EAAE,cAAc,CAAC;IACzB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,OAAO,CAAC;CACvB,CAmCA;AAED,wEAAwE;AACxE,wBAAgB,sBAAsB,CAAC,IAAI,SAAiB,GAAG;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;CACrE,CAmCA"}

package/dist/src/lib/claude-settings.js

@@ -0,0 +1,271 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/**
+ * Reads and edits `~/.claude/settings.json` on the user's behalf.
+ *
+ * Two rules govern everything here, both of them about not destroying a file
+ * we do not own:
+ *
+ * 1. **Never write over JSON we could not parse.** A malformed settings file
+ *    is far more likely to be a half-finished edit than something to
+ *    overwrite, and overwriting it would lose the user's own hooks,
+ *    permissions and MCP servers. Parse failures raise instead.
+ * 2. **Only ever touch keys we put there.** Merging into `env` and appending
+ *    to `hooks` leaves everything else untouched, and removal matches our
+ *    own hook command rather than clearing the arrays.
+ */
+export const SETTINGS_FILENAME = "settings.json";
+/** Env keys `clocktopus agent setup` owns — and the only ones it removes. */
+export const TELEMETRY_ENV_KEYS = [
+    "CLAUDE_CODE_ENABLE_TELEMETRY",
+    "OTEL_METRICS_EXPORTER",
+    "OTEL_EXPORTER_OTLP_PROTOCOL",
+    "OTEL_EXPORTER_OTLP_ENDPOINT",
+    "OTEL_EXPORTER_OTLP_HEADERS",
+    "OTEL_METRICS_INCLUDE_SESSION_ID",
+    "OTEL_METRIC_EXPORT_INTERVAL",
+    "CLOCKTOPUS_INGEST_TOKEN",
+    "CLOCKTOPUS_OTEL_ENDPOINT",
+];
+/**
+ * How often Claude Code's exporter ships metrics.
+ *
+ * Also the resolution of every "last export received" answer the status
+ * command can give — a session that started 30s ago has genuinely not
+ * exported yet, which is why status treats silence under one interval as
+ * "waiting" rather than "broken".
+ */
+export const METRIC_EXPORT_INTERVAL_MS = 60_000;
+/**
+ * Seconds Claude Code will wait for the hook before giving up on it.
+ *
+ * Comfortably above the hook's own 4s request timeout, so a slow network
+ * produces the hook's own recorded failure — which `agent doctor` can read
+ * back — rather than a kill from the host, which leaves no trace anywhere.
+ */
+export const HOOK_TIMEOUT_SECONDS = 10;
+export class SettingsParseError extends Error {
+    path;
+    constructor(path) {
+        super(`${path} is not valid JSON. Fix or move it, then run 'clocktopus agent setup' again.`);
+        this.path = path;
+        this.name = "SettingsParseError";
+    }
+}
+export function claudeConfigDir() {
+    // Claude Code honours CLAUDE_CONFIG_DIR; following it means setup writes
+    // where that installation actually reads.
+    return process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+}
+export function settingsPath() {
+    return join(claudeConfigDir(), SETTINGS_FILENAME);
+}
+export function readSettings(path = settingsPath()) {
+    if (!existsSync(path)) {
+        return { path, exists: false, modifiedAt: null, settings: {} };
+    }
+    const raw = readFileSync(path, "utf8");
+    const modifiedAt = statSync(path).mtime;
+    // An empty file is a normal state (some installers touch it) and is safe
+    // to treat as an empty object; anything else that fails to parse is not.
+    if (raw.trim() === "") {
+        return { path, exists: true, modifiedAt, settings: {} };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new SettingsParseError(path);
+        }
+        return {
+            path,
+            exists: true,
+            modifiedAt,
+            settings: parsed,
+        };
+    }
+    catch (error) {
+        if (error instanceof SettingsParseError)
+            throw error;
+        throw new SettingsParseError(path);
+    }
+}
+/**
+ * Writes settings, keeping a one-deep backup of what was there before.
+ *
+ * The rename is what makes it atomic: a crash midway leaves either the old
+ * file or the new one, never a truncated file that Claude Code would refuse
+ * to start with.
+ */
+export function writeSettings(settings, path = settingsPath()) {
+    mkdirSync(dirname(path), { recursive: true });
+    let backupPath = null;
+    if (existsSync(path)) {
+        backupPath = `${path}.clocktopus-backup`;
+        copyFileSync(path, backupPath);
+    }
+    const temporaryPath = `${path}.clocktopus-tmp`;
+    writeFileSync(temporaryPath, `${JSON.stringify(settings, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    renameSync(temporaryPath, path);
+    return { backupPath };
+}
+export function buildTelemetryEnv(input) {
+    const endpoint = input.endpoint.replace(/\/$/, "");
+    return {
+        CLAUDE_CODE_ENABLE_TELEMETRY: "1",
+        OTEL_METRICS_EXPORTER: "otlp",
+        // The receiver answers protobuf with an explicit 415 rather than a
+        // parse error, but only JSON actually works.
+        OTEL_EXPORTER_OTLP_PROTOCOL: "http/json",
+        OTEL_EXPORTER_OTLP_ENDPOINT: endpoint,
+        OTEL_EXPORTER_OTLP_HEADERS: `Authorization=Bearer ${input.token}`,
+        // Without the session id the metric stream cannot be joined to the hook
+        // stream, and every session loses its repository and branch.
+        OTEL_METRICS_INCLUDE_SESSION_ID: "true",
+        OTEL_METRIC_EXPORT_INTERVAL: String(METRIC_EXPORT_INTERVAL_MS),
+        // The hook's own channel. Same token, different transport.
+        CLOCKTOPUS_INGEST_TOKEN: input.token,
+        CLOCKTOPUS_OTEL_ENDPOINT: endpoint,
+    };
+}
+const HOOK_EVENTS = ["SessionStart", "SessionEnd"];
+/**
+ * Recognises a hook entry as ours, across every spelling we have shipped.
+ *
+ * The `claude-hook.mjs` clause matters for upgrades: before this command
+ * existed the hook was a script inside a checkout of the Clocktopus repo,
+ * and anyone who set that up by hand still has it. Failing to recognise it
+ * would leave it installed next to the new one and POST every SessionStart
+ * twice.
+ */
+function isClocktopusHook(entry) {
+    const command = typeof entry.command === "string" ? entry.command : "";
+    if (/claude-hook\.mjs/.test(command))
+        return true;
+    return /clocktopus/i.test(command) && /agent\s+hook/.test(command);
+}
+function asMatchers(value) {
+    return Array.isArray(value) ? value : [];
+}
+/** Strips our hook from one event's matcher list, leaving the user's alone. */
+function withoutOurHooks(matchers) {
+    return (matchers
+        .map((matcher) => ({
+        ...matcher,
+        hooks: (matcher.hooks ?? []).filter((entry) => !isClocktopusHook(entry)),
+    }))
+        // A matcher group that only ever held our hook is ours to remove; one
+        // that still has entries belongs to the user and stays.
+        .filter((matcher) => (matcher.hooks ?? []).length > 0));
+}
+export function applyTelemetrySettings(settings, input) {
+    const existingEnv = settings.env &&
+        typeof settings.env === "object" &&
+        !Array.isArray(settings.env)
+        ? settings.env
+        : {};
+    const existingHooks = settings.hooks &&
+        typeof settings.hooks === "object" &&
+        !Array.isArray(settings.hooks)
+        ? settings.hooks
+        : {};
+    const hooks = { ...existingHooks };
+    for (const event of HOOK_EVENTS) {
+        // Remove-then-append rather than append: re-running setup after a
+        // reinstall must not leave two hooks firing per session, which would
+        // double every SessionStart POST.
+        hooks[event] = [
+            ...withoutOurHooks(asMatchers(existingHooks[event])),
+            {
+                hooks: [
+                    {
+                        type: "command",
+                        command: input.hookCommand,
+                        // Both fields are about not making the user wait on telemetry.
+                        // The hook does network I/O — its own POST, plus a sweep of
+                        // abandoned sessions at SessionStart — and running it inline
+                        // would add that latency to the start of every session.
+                        timeout: HOOK_TIMEOUT_SECONDS,
+                        async: true,
+                    },
+                ],
+            },
+        ];
+    }
+    return {
+        ...settings,
+        env: { ...existingEnv, ...buildTelemetryEnv(input) },
+        hooks,
+    };
+}
+export function removeTelemetrySettings(settings) {
+    const next = { ...settings };
+    const removedEnvKeys = [];
+    if (next.env && typeof next.env === "object" && !Array.isArray(next.env)) {
+        const env = { ...next.env };
+        for (const key of TELEMETRY_ENV_KEYS) {
+            if (key in env) {
+                delete env[key];
+                removedEnvKeys.push(key);
+            }
+        }
+        if (Object.keys(env).length > 0)
+            next.env = env;
+        else
+            delete next.env;
+    }
+    let removedHooks = false;
+    if (next.hooks &&
+        typeof next.hooks === "object" &&
+        !Array.isArray(next.hooks)) {
+        const hooks = { ...next.hooks };
+        for (const event of HOOK_EVENTS) {
+            const before = asMatchers(hooks[event]);
+            const after = withoutOurHooks(before);
+            if (JSON.stringify(before) !== JSON.stringify(after))
+                removedHooks = true;
+            if (after.length > 0)
+                hooks[event] = after;
+            else
+                delete hooks[event];
+        }
+        if (Object.keys(hooks).length > 0)
+            next.hooks = hooks;
+        else
+            delete next.hooks;
+    }
+    return { settings: next, removedEnvKeys, removedHooks };
+}
+/** What settings.json currently declares, for `status` and `doctor`. */
+export function readInstalledTelemetry(path = settingsPath()) {
+    const { settings, exists, modifiedAt } = readSettings(path);
+    const rawEnv = settings.env &&
+        typeof settings.env === "object" &&
+        !Array.isArray(settings.env)
+        ? settings.env
+        : {};
+    const env = {};
+    for (const key of TELEMETRY_ENV_KEYS) {
+        if (typeof rawEnv[key] === "string")
+            env[key] = rawEnv[key];
+    }
+    const rawHooks = settings.hooks &&
+        typeof settings.hooks === "object" &&
+        !Array.isArray(settings.hooks)
+        ? settings.hooks
+        : {};
+    const hookCommands = {};
+    for (const event of HOOK_EVENTS) {
+        for (const matcher of asMatchers(rawHooks[event])) {
+            const ours = (matcher.hooks ?? []).find(isClocktopusHook);
+            if (ours?.command) {
+                hookCommands[event] = ours.command;
+                break;
+            }
+        }
+    }
+    return { path, exists, modifiedAt, env, hookCommands };
+}

package/dist/src/lib/claude-settings.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=claude-settings.test.d.ts.map

package/dist/src/lib/claude-settings.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-settings.test.d.ts","sourceRoot":"","sources":["../../../src/lib/claude-settings.test.ts"],"names":[],"mappings":""}

package/dist/src/lib/claude-settings.test.js

@@ -0,0 +1,193 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { applyTelemetrySettings, buildTelemetryEnv, readInstalledTelemetry, readSettings, removeTelemetrySettings, SettingsParseError, writeSettings, } from "./claude-settings";
+/**
+ * These tests exist because this module edits a file we do not own.
+ * `~/.claude/settings.json` holds the user's model choice, their own hooks,
+ * their permissions and their MCP servers, and a merge bug here destroys
+ * work that has nothing to do with us.
+ */
+const INSTALL = {
+    token: "ctop_agt_testtoken",
+    endpoint: "https://otel.example.com",
+    hookCommand: "clocktopus agent hook",
+};
+/** A settings file with the user's own configuration already in it. */
+function userSettings() {
+    return {
+        model: "opus",
+        env: { MY_OWN_VAR: "keep-me" },
+        hooks: {
+            SessionStart: [
+                { hooks: [{ type: "command", command: "echo user-session-start" }] },
+            ],
+            PreToolUse: [
+                {
+                    matcher: "Bash",
+                    hooks: [{ type: "command", command: "echo bash-guard" }],
+                },
+            ],
+        },
+    };
+}
+describe("applyTelemetrySettings", () => {
+    it("leaves everything it did not put there alone", () => {
+        const next = applyTelemetrySettings(userSettings(), INSTALL);
+        expect(next.model).toBe("opus");
+        expect(next.env.MY_OWN_VAR).toBe("keep-me");
+        expect(next.hooks.PreToolUse).toEqual(userSettings().hooks.PreToolUse);
+    });
+    it("keeps the user's own SessionStart hook alongside ours", () => {
+        const next = applyTelemetrySettings(userSettings(), INSTALL);
+        const commands = (next.hooks.SessionStart ?? []).flatMap((matcher) => matcher.hooks.map((entry) => entry.command));
+        expect(commands).toContain("echo user-session-start");
+        expect(commands).toContain("clocktopus agent hook");
+    });
+    it("installs both events — one without the other loses attribution", () => {
+        // SessionStart is the only source of `cwd` and the *before* SHA;
+        // SessionEnd is the only source of the exact commit list.
+        const next = applyTelemetrySettings({}, INSTALL);
+        const hooks = next.hooks;
+        expect(hooks.SessionStart).toBeDefined();
+        expect(hooks.SessionEnd).toBeDefined();
+    });
+    it("is idempotent — re-running setup does not fire the hook twice", () => {
+        const once = applyTelemetrySettings(userSettings(), INSTALL);
+        const twice = applyTelemetrySettings(once, INSTALL);
+        const ours = (twice.hooks.SessionStart ?? [])
+            .flatMap((matcher) => matcher.hooks)
+            .filter((entry) => entry.command === "clocktopus agent hook");
+        expect(ours).toHaveLength(1);
+    });
+    it("runs the hook out of band, so telemetry never delays session start", () => {
+        const next = applyTelemetrySettings({}, INSTALL);
+        const entry = next.hooks.SessionStart[0].hooks[0];
+        expect(entry.async).toBe(true);
+        // Above the hook's own 4s request timeout, so a slow network leaves the
+        // hook's recorded failure behind instead of being killed without trace.
+        expect(entry.timeout).toBe(10);
+    });
+    it("replaces the pre-CLI script hook instead of firing both", () => {
+        // Anyone who wired this up before the CLI existed points at a script
+        // inside a checkout of this repo. Leaving it installed alongside the new
+        // hook would POST every SessionStart twice.
+        const legacy = {
+            hooks: {
+                SessionStart: [
+                    {
+                        hooks: [
+                            {
+                                type: "command",
+                                command: "node /home/me/Projects/clocktopus/scripts/agent-telemetry/claude-hook.mjs",
+                                timeout: 10,
+                                async: true,
+                            },
+                        ],
+                    },
+                ],
+            },
+        };
+        const next = applyTelemetrySettings(legacy, INSTALL);
+        const commands = next.hooks.SessionStart.flatMap((matcher) => matcher.hooks.map((entry) => entry.command));
+        expect(commands).toEqual(["clocktopus agent hook"]);
+    });
+    it("replaces our hook when the command changes, rather than adding one", () => {
+        const first = applyTelemetrySettings({}, INSTALL);
+        const moved = applyTelemetrySettings(first, {
+            ...INSTALL,
+            hookCommand: "/usr/local/bin/node /opt/clocktopus/cli.js agent hook",
+        });
+        const commands = (moved.hooks.SessionEnd ?? []).flatMap((matcher) => matcher.hooks.map((entry) => entry.command));
+        expect(commands).toEqual([
+            "/usr/local/bin/node /opt/clocktopus/cli.js agent hook",
+        ]);
+    });
+});
+describe("buildTelemetryEnv", () => {
+    it("configures the exporter the only way the receiver accepts", () => {
+        const env = buildTelemetryEnv(INSTALL);
+        // Protobuf gets an explicit 415 from the receiver.
+        expect(env.OTEL_EXPORTER_OTLP_PROTOCOL).toBe("http/json");
+        expect(env.OTEL_EXPORTER_OTLP_HEADERS).toBe("Authorization=Bearer ctop_agt_testtoken");
+        // Without the session id the metric stream cannot be joined to the hook
+        // stream, and every session loses its repository and branch.
+        expect(env.OTEL_METRICS_INCLUDE_SESSION_ID).toBe("true");
+    });
+    it("normalises a trailing slash so paths do not double up", () => {
+        const env = buildTelemetryEnv({
+            ...INSTALL,
+            endpoint: "https://otel.example.com/",
+        });
+        expect(env.OTEL_EXPORTER_OTLP_ENDPOINT).toBe("https://otel.example.com");
+        expect(env.CLOCKTOPUS_OTEL_ENDPOINT).toBe("https://otel.example.com");
+    });
+});
+describe("removeTelemetrySettings", () => {
+    it("removes only what setup added", () => {
+        const installed = applyTelemetrySettings(userSettings(), INSTALL);
+        const { settings, removedEnvKeys, removedHooks } = removeTelemetrySettings(installed);
+        expect(removedHooks).toBe(true);
+        expect(removedEnvKeys).toContain("CLOCKTOPUS_INGEST_TOKEN");
+        expect(settings.model).toBe("opus");
+        expect(settings.env.MY_OWN_VAR).toBe("keep-me");
+        expect(settings.env.CLOCKTOPUS_INGEST_TOKEN).toBeUndefined();
+        const sessionStart = settings.hooks.SessionStart;
+        expect(sessionStart?.flatMap((m) => m.hooks.map((h) => h.command))).toEqual(["echo user-session-start"]);
+        expect(settings.hooks.PreToolUse).toBeDefined();
+    });
+    it("drops the env and hooks keys entirely when nothing else used them", () => {
+        const installed = applyTelemetrySettings({ model: "opus" }, INSTALL);
+        const { settings } = removeTelemetrySettings(installed);
+        expect(settings.env).toBeUndefined();
+        expect(settings.hooks).toBeUndefined();
+        expect(settings.model).toBe("opus");
+    });
+    it("reports nothing removed when telemetry was never installed", () => {
+        const { removedEnvKeys, removedHooks } = removeTelemetrySettings(userSettings());
+        expect(removedEnvKeys).toEqual([]);
+        expect(removedHooks).toBe(false);
+    });
+});
+describe("reading and writing the file", () => {
+    let dir;
+    let path;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), "clocktopus-settings-"));
+        path = join(dir, "settings.json");
+    });
+    afterEach(() => {
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it("refuses to read malformed JSON rather than overwrite it", () => {
+        // A broken settings file is far more likely to be a half-finished edit
+        // than something to clobber.
+        writeFileSync(path, '{ "model": "opus",,, }', "utf8");
+        expect(() => readSettings(path)).toThrow(SettingsParseError);
+    });
+    it("treats a missing file as empty settings", () => {
+        const result = readSettings(path);
+        expect(result.exists).toBe(false);
+        expect(result.settings).toEqual({});
+    });
+    it("backs up the previous file before replacing it", () => {
+        writeFileSync(path, JSON.stringify(userSettings()), "utf8");
+        const { backupPath } = writeSettings(applyTelemetrySettings(readSettings(path).settings, INSTALL), path);
+        expect(backupPath).toBe(`${path}.clocktopus-backup`);
+        expect(JSON.parse(readFileSync(backupPath, "utf8"))).toEqual(userSettings());
+    });
+    it("round-trips what setup installed", () => {
+        writeSettings(applyTelemetrySettings(userSettings(), INSTALL), path);
+        const installed = readInstalledTelemetry(path);
+        expect(installed.env.CLOCKTOPUS_INGEST_TOKEN).toBe("ctop_agt_testtoken");
+        expect(installed.hookCommands.SessionStart).toBe("clocktopus agent hook");
+        expect(installed.hookCommands.SessionEnd).toBe("clocktopus agent hook");
+    });
+    it("reports no telemetry for a settings file that only has the user's own hooks", () => {
+        writeFileSync(path, JSON.stringify(userSettings()), "utf8");
+        const installed = readInstalledTelemetry(path);
+        expect(installed.env).toEqual({});
+        expect(installed.hookCommands.SessionStart).toBeUndefined();
+    });
+});