@blastin-dev/clocktopus-cli 0.1.4 → 0.2.1

package/dist/src/lib/agents.js

@@ -0,0 +1,245 @@
+import { execFileSync } from "node:child_process";
+import { applyTelemetrySettings, readInstalledTelemetry, readSettings, removeTelemetrySettings, SettingsParseError, settingsPath, writeSettings, } from "./claude-settings.js";
+import { applyCodexHooks, applyCodexOtel, CodexConfigParseError, codexConfigPath, codexHooksPath, HOOK_EVENT_COUNT, readCodexConfig, readCodexHooks, readCodexHookTrust, readCodexTelemetry, removeCodexHooks, removeCodexOtel, writeCodexConfig, writeCodexHooks, } from "./codex-config.js";
+import { buildOpencodePlugin, OPENCODE_PLUGIN_VERSION, opencodePluginPath, readOpencodePlugin, removeOpencodePlugin, splitCommandLine, writeOpencodePlugin, } from "./opencode-config.js";
+/** `true` when the parse error is one of ours, whichever agent raised it. */
+export function isConfigParseError(error) {
+    return (error instanceof SettingsParseError ||
+        error instanceof CodexConfigParseError);
+}
+const claudeAdapter = {
+    id: "claude",
+    label: "Claude Code",
+    provider: "claude_code",
+    binary: "claude",
+    hostRunsHooksAsync: true,
+    hostRepeatsSessionEnd: false,
+    paths: () => [settingsPath()],
+    read() {
+        const installed = readInstalledTelemetry();
+        return {
+            token: installed.env.CLOCKTOPUS_INGEST_TOKEN ?? null,
+            endpoint: installed.env.CLOCKTOPUS_OTEL_ENDPOINT ?? null,
+            hookCommands: installed.hookCommands,
+            modifiedAt: installed.modifiedAt,
+            paths: [installed.path],
+        };
+    },
+    apply(input) {
+        const current = readSettings();
+        const next = applyTelemetrySettings(current.settings, input);
+        const { backupPath } = writeSettings(next, current.path);
+        return { backupPaths: backupPath ? [backupPath] : [] };
+    },
+    remove() {
+        const current = readSettings();
+        if (!current.exists)
+            return { removed: [] };
+        const result = removeTelemetrySettings(current.settings);
+        if (result.removedEnvKeys.length === 0 && !result.removedHooks)
+            return { removed: [] };
+        writeSettings(result.settings, current.path);
+        return {
+            removed: [
+                ...result.removedEnvKeys,
+                ...(result.removedHooks ? ["SessionStart/SessionEnd hooks"] : []),
+            ],
+        };
+    },
+    pendingActions: () => [],
+};
+const codexAdapter = {
+    id: "codex",
+    label: "Codex CLI",
+    provider: "codex_cli",
+    binary: "codex",
+    hostRunsHooksAsync: false,
+    hostRepeatsSessionEnd: false,
+    paths: () => [codexConfigPath(), codexHooksPath()],
+    read() {
+        const telemetry = readCodexTelemetry();
+        const hooks = readCodexHooks();
+        return {
+            token: telemetry.token,
+            endpoint: telemetry.endpoint,
+            hookCommands: hooks.commands,
+            modifiedAt: newest([telemetry.modifiedAt, hooks.modifiedAt]),
+            paths: [telemetry.path, hooks.path],
+        };
+    },
+    apply(input) {
+        const backupPaths = [];
+        const config = readCodexConfig();
+        const nextText = applyCodexOtel(config, input);
+        const written = writeCodexConfig({
+            path: config.path,
+            previousText: config.text,
+            previousConfig: config.config,
+            nextText,
+        });
+        if (written.backupPath)
+            backupPaths.push(written.backupPath);
+        const hooks = readCodexHooks();
+        const nextHooks = applyCodexHooks(hooks.file, input);
+        const hooksWritten = writeCodexHooks(nextHooks, hooks.path);
+        if (hooksWritten.backupPath)
+            backupPaths.push(hooksWritten.backupPath);
+        return { backupPaths };
+    },
+    remove() {
+        const removed = [];
+        const config = readCodexConfig();
+        if (config.exists) {
+            const { nextText, removedKeys } = removeCodexOtel(config);
+            if (removedKeys.length > 0) {
+                writeCodexConfig({
+                    path: config.path,
+                    previousText: config.text,
+                    previousConfig: config.config,
+                    nextText,
+                });
+                removed.push(...removedKeys.map((key) => `otel.${key}`));
+            }
+        }
+        const hooks = readCodexHooks();
+        if (hooks.exists) {
+            const result = removeCodexHooks(hooks.file);
+            if (result.removed) {
+                writeCodexHooks(result.file, hooks.path);
+                removed.push("SessionStart/SessionEnd hooks");
+            }
+        }
+        return { removed };
+    },
+    pendingActions() {
+        // Codex refuses to run a hooks.json it has not been shown, and there is
+        // no way to approve it from here — the prompt is part of the TUI. Left
+        // unsaid, this looks exactly like a broken install: telemetry arrives,
+        // repository context never does.
+        if (!readCodexHooks().exists)
+            return [];
+        const { untrusted } = readCodexHookTrust();
+        if (untrusted.length === 0)
+            return [];
+        // Says what is missing, never what is already fine. Trust is keyed on a
+        // hash of the hook entry, so rewriting hooks.json invalidates every
+        // approval it already had — `trusted` can be stale the moment setup
+        // runs, and promising the user that half of it is done would be a lie
+        // as often as not.
+        const missing = untrusted.length === HOOK_EVENT_COUNT
+            ? "its hooks"
+            : `its ${untrusted.join(" and ")} hook`;
+        return [
+            "Start Codex once and answer 'Trust all and continue' when it asks\n" +
+                `  about ${missing}. Until then Codex records your spend but not the\n` +
+                "  repository it was spent on — it will not run an unapproved hook.",
+        ];
+    },
+};
+const opencodeAdapter = {
+    id: "opencode",
+    label: "OpenCode",
+    provider: "opencode",
+    binary: "opencode",
+    // The plugin runs inside OpenCode's own event loop and does not await the
+    // work it starts, so the hook is already off the critical path by the
+    // time it reaches the CLI. Re-spawning would only add a process.
+    hostRunsHooksAsync: true,
+    // `session.idle` is the closest thing OpenCode has to a session end, and
+    // it fires after every turn rather than once.
+    hostRepeatsSessionEnd: true,
+    paths: () => [opencodePluginPath()],
+    read() {
+        const plugin = readOpencodePlugin();
+        return {
+            token: plugin.config?.token ?? null,
+            endpoint: plugin.config?.endpoint ?? null,
+            // Both events come from the one plugin file, so they are installed
+            // together or not at all — unlike the hook agents, where each event is
+            // a separate entry that can go missing on its own.
+            hookCommands: plugin.config
+                ? {
+                    SessionStart: plugin.config.hookArgv.join(" "),
+                    SessionEnd: plugin.config.hookArgv.join(" "),
+                }
+                : {},
+            modifiedAt: plugin.modifiedAt,
+            paths: [plugin.path],
+        };
+    },
+    apply(input) {
+        const { backupPath } = writeOpencodePlugin(buildOpencodePlugin({
+            endpoint: input.endpoint,
+            token: input.token,
+            hookArgv: splitCommandLine(input.hookCommand),
+        }));
+        return { backupPaths: backupPath ? [backupPath] : [] };
+    },
+    remove() {
+        return { removed: removeOpencodePlugin() ? ["the Clocktopus plugin"] : [] };
+    },
+    pendingActions: () => [],
+    staleReason() {
+        const plugin = readOpencodePlugin();
+        if (!plugin.exists || !plugin.config)
+            return null;
+        if (plugin.version === OPENCODE_PLUGIN_VERSION)
+            return null;
+        return (`the installed plugin was generated by an older CLI ` +
+            `(generation ${plugin.version ?? "unstamped"}, current is ` +
+            `${OPENCODE_PLUGIN_VERSION})`);
+    },
+};
+export const AGENTS = [
+    claudeAdapter,
+    codexAdapter,
+    opencodeAdapter,
+];
+/**
+ * What is on this machine, and what is already wired up.
+ *
+ * Detection is by `--version` rather than by config directory: `~/.claude`
+ * and `~/.codex` both outlive an uninstall, so a stale directory would
+ * offer to configure an agent that is no longer there.
+ */
+export function surveyAgents() {
+    return AGENTS.map((agent) => {
+        const version = detectVersion(agent.binary);
+        let configured = false;
+        let unreadable = null;
+        try {
+            configured = agent.read().token !== null;
+        }
+        catch (error) {
+            if (isConfigParseError(error))
+                unreadable = error.message;
+            else
+                throw error;
+        }
+        return {
+            agent,
+            version,
+            installed: version !== null,
+            configured,
+            unreadable,
+        };
+    });
+}
+function detectVersion(binary) {
+    try {
+        const output = execFileSync(binary, ["--version"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5000,
+        });
+        // Both CLIs print a line with the version somewhere in it; the number is
+        // the only part worth showing, and neither format is worth parsing hard.
+        return (/\d+\.\d+\.\d+/.exec(output)?.[0] ?? output.trim().split("\n")[0] ?? null);
+    }
+    catch {
+        return null;
+    }
+}
+function newest(dates) {
+    return dates.reduce((latest, date) => (date && (!latest || date > latest) ? date : latest), null);
+}

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":""}