@blastin-dev/clocktopus-cli 0.1.4 → 0.2.0

package/dist/src/index.js

@@ -1,6 +1,11 @@
 import { createRequire } from "node:module";
 import { Command } from "commander";
 import { z } from "zod";
+import { disableCommand } from "./commands/agent/disable.js";
+import { doctorCommand } from "./commands/agent/doctor.js";
+import { hookCommand } from "./commands/agent/hook.js";
+import { setupCommand } from "./commands/agent/setup.js";
+import { statusCommand } from "./commands/agent/status.js";
 import { clockInCommand, clockOutCommand, clockStatusCommand, } from "./commands/clock.js";
 import { loginCommand } from "./commands/login.js";
 import { logoutCommand } from "./commands/logout.js";
@@ -16,12 +21,12 @@ program
     .name("clocktopus")
     .description("CLI for Clocktopus time tracking")
     .version(version)
-    .option("-e, --env <environment>", "Use environment (dev or prod)")
+    .option("-e, --env <environment>", "Use environment (dev, staging or prod)")
     .hook("preAction", (thisCommand) => {
     const opts = thisCommand.opts();
     if (opts.env) {
         if (!(opts.env in ENVIRONMENTS)) {
-            console.error(`Invalid environment: ${opts.env}. Use 'dev' or 'prod'.`);
+            console.error(`Invalid environment: ${opts.env}. Use 'dev', 'staging' or 'prod'.`);
             process.exit(1);
         }
         setRuntimeEnvironment(opts.env);
@@ -60,6 +65,36 @@ clock
     .description("Show clock signals for a specific date")
     .option("-d, --date <date>", "Date in YYYY-MM-DD format (default: today)")
     .action(clockStatusCommand);
+// Agent telemetry — tracks what AI agents cost, alongside human time.
+const agent = program
+    .command("agent")
+    .description("Track AI agent spend from this machine");
+agent
+    .command("setup")
+    .description("Point Claude Code at Clocktopus and install the session hooks")
+    .option("--name <name>", "Label for this machine's ingest token")
+    .option("--force", "Mint a replacement token instead of reusing the existing one")
+    .action((options) => setupCommand(options));
+agent
+    .command("status")
+    .description("Show what the receiver has actually received")
+    .action(statusCommand);
+agent
+    .command("doctor")
+    .description("Check every link in the telemetry chain and report failures")
+    .action(doctorCommand);
+agent
+    .command("disable")
+    .description("Remove this machine's telemetry configuration")
+    .option("--revoke", "Also revoke the ingest token, everywhere")
+    .action((options) => disableCommand(options));
+// Invoked by Claude Code, never by a person: it reads the hook payload from
+// stdin and must not write to stdout. Hidden so it does not read as
+// something to run by hand.
+agent
+    .command("hook", { hidden: true })
+    .description("Internal: Claude Code SessionStart/SessionEnd hook")
+    .action(hookCommand);
 export function run() {
     program.parse();
 }

package/dist/src/lib/agent-config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Where the ingest credentials come from, and what shadows what.
+ *
+ * The order matters and is not arbitrary. Inside a Claude Code session the
+ * process environment is what the exporter and the hook actually read, and
+ * `settings.json` `env` is applied *over* the inherited shell environment —
+ * so a value in settings.json wins over one exported from `.envrc` or a
+ * shell profile, silently. That is the failure this resolver is built to
+ * make visible rather than to paper over: it reports the source alongside
+ * the value so `doctor` can name the file that is winning.
+ */
+export type CredentialSource = "environment" | "settings" | "none";
+export type ResolvedAgentCredentials = {
+    token: string | null;
+    endpoint: string | null;
+    tokenSource: CredentialSource;
+    endpointSource: CredentialSource;
+};
+export declare function resolveAgentCredentials(): ResolvedAgentCredentials;
+/** Masks a token for display: never print more than the stored prefix. */
+export declare function maskToken(token: string): string;
+export declare function findShadowedExports(cwd?: string): Array<{
+    path: string;
+    keys: string[];
+}>;
+/**
+ * The command to write into settings.json for the hook.
+ *
+ * Prefers the bare name, but only after confirming that `clocktopus` on
+ * PATH resolves to *this* executable. Hooks run through a shell whose PATH
+ * may differ from the interactive one, and a bare name that does not
+ * resolve there fails silently — the session runs fine and every bit of
+ * repository context is lost. An absolute path is uglier and survives that;
+ * `doctor` checks it still exists.
+ */
+export declare function resolveHookCommand(): {
+    command: string;
+    usesAbsolutePath: boolean;
+    binaryPath: string | null;
+};
+//# sourceMappingURL=agent-config.d.ts.map

package/dist/src/lib/agent-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-config.d.ts","sourceRoot":"","sources":["../../../src/lib/agent-config.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,UAAU,GAAG,MAAM,CAAC;AAEnE,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,cAAc,EAAE,gBAAgB,CAAC;CAClC,CAAC;AAEF,wBAAgB,uBAAuB,IAAI,wBAAwB,CA2BlE;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAmBD,wBAAgB,mBAAmB,CAAC,GAAG,SAAgB,GAAG,KAAK,CAAC;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC,CA+BD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CA8BA"}

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

@@ -0,0 +1,143 @@
+import { accessSync, constants, existsSync, readFileSync, realpathSync, } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join, resolve } from "node:path";
+import { readInstalledTelemetry } from "./claude-settings.js";
+export function resolveAgentCredentials() {
+    const envToken = process.env.CLOCKTOPUS_INGEST_TOKEN?.trim();
+    const envEndpoint = process.env.CLOCKTOPUS_OTEL_ENDPOINT?.trim();
+    let settingsToken;
+    let settingsEndpoint;
+    try {
+        const installed = readInstalledTelemetry();
+        settingsToken = installed.env.CLOCKTOPUS_INGEST_TOKEN;
+        settingsEndpoint = installed.env.CLOCKTOPUS_OTEL_ENDPOINT;
+    }
+    catch {
+        // A malformed settings.json is reported properly by `setup` and
+        // `doctor`. Credential resolution must not throw — the hook calls it on
+        // every session start.
+    }
+    return {
+        token: envToken || settingsToken || null,
+        endpoint: (envEndpoint || settingsEndpoint || null)?.replace(/\/$/, "") ?? null,
+        tokenSource: envToken ? "environment" : settingsToken ? "settings" : "none",
+        endpointSource: envEndpoint
+            ? "environment"
+            : settingsEndpoint
+                ? "settings"
+                : "none",
+    };
+}
+/** Masks a token for display: never print more than the stored prefix. */
+export function maskToken(token) {
+    return token.length <= 15 ? "…" : `${token.slice(0, 15)}…`;
+}
+/**
+ * Files that commonly export the same variables, and would be shadowed.
+ *
+ * Scanned rather than guessed at, because "your `.envrc` is being ignored"
+ * is only useful advice when it names the file. The repo-local `.envrc` is
+ * included because that is exactly how this project was dogfooded before
+ * the CLI existed.
+ */
+const SHELL_FILES = [
+    ".bashrc",
+    ".bash_profile",
+    ".zshrc",
+    ".zshenv",
+    ".profile",
+    ".config/fish/config.fish",
+];
+export function findShadowedExports(cwd = process.cwd()) {
+    const candidates = [
+        ...SHELL_FILES.map((file) => join(homedir(), file)),
+        join(cwd, ".envrc"),
+    ];
+    const found = [];
+    for (const path of candidates) {
+        let contents;
+        try {
+            if (!existsSync(path))
+                continue;
+            contents = readFileSync(path, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const keys = [
+            "CLOCKTOPUS_INGEST_TOKEN",
+            "CLOCKTOPUS_OTEL_ENDPOINT",
+            "OTEL_EXPORTER_OTLP_ENDPOINT",
+            "OTEL_EXPORTER_OTLP_HEADERS",
+            "CLAUDE_CODE_ENABLE_TELEMETRY",
+        ].filter((key) => new RegExp(`^\\s*(export\\s+)?${key}=`, "m").test(contents));
+        if (keys.length > 0)
+            found.push({ path, keys });
+    }
+    return found;
+}
+/**
+ * The command to write into settings.json for the hook.
+ *
+ * Prefers the bare name, but only after confirming that `clocktopus` on
+ * PATH resolves to *this* executable. Hooks run through a shell whose PATH
+ * may differ from the interactive one, and a bare name that does not
+ * resolve there fails silently — the session runs fine and every bit of
+ * repository context is lost. An absolute path is uglier and survives that;
+ * `doctor` checks it still exists.
+ */
+export function resolveHookCommand() {
+    const script = process.argv[1] ? resolve(process.argv[1]) : null;
+    const quote = (value) => /[\s"']/.test(value) ? `"${value}"` : value;
+    if (script && resolvesOnPath("clocktopus", script)) {
+        return {
+            command: "clocktopus agent hook",
+            usesAbsolutePath: false,
+            binaryPath: script,
+        };
+    }
+    if (script) {
+        // `node <script>` rather than executing the script directly: the file in
+        // a published package keeps its shebang, but a checkout may not have the
+        // executable bit, and the hook must not depend on that.
+        return {
+            command: `${quote(process.execPath)} ${quote(script)} agent hook`,
+            usesAbsolutePath: true,
+            binaryPath: script,
+        };
+    }
+    return {
+        command: "clocktopus agent hook",
+        usesAbsolutePath: false,
+        binaryPath: null,
+    };
+}
+function resolvesOnPath(name, expected) {
+    const searchPath = process.env.PATH;
+    if (!searchPath)
+        return false;
+    let expectedReal;
+    try {
+        expectedReal = realpathSync(expected);
+    }
+    catch {
+        return false;
+    }
+    for (const dir of searchPath.split(delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, name);
+        try {
+            accessSync(candidate, constants.X_OK);
+            if (realpathSync(candidate) === expectedReal)
+                return true;
+            // A different `clocktopus` earlier on PATH would shadow this one, so
+            // stop rather than keep looking for a match further down.
+            return false;
+        }
+        catch {
+            continue;
+        }
+    }
+    return false;
+}

package/dist/src/lib/agent-hook-state.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+declare const LastRunSchema: z.ZodObject<{
+    at: z.ZodString;
+    event: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    tokenPrefix: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    repository: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type HookLastRun = z.infer<typeof LastRunSchema>;
+declare const StartStateSchema: z.ZodObject<{
+    sha: z.ZodString;
+    cwd: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type HookStartState = z.infer<typeof StartStateSchema>;
+export declare function writeStartState(sessionId: string, sha: string, cwd: string): void;
+export declare function readStartState(sessionId: string): HookStartState | undefined;
+export declare function clearStartState(sessionId: string): void;
+export declare function listStartStates(): Array<{
+    sessionId: string;
+    ageMs: number;
+    /**
+     * When the state file was last touched — the newest moment this machine
+     * has evidence the session existed. The sweep sends it as the abandoned
+     * session's `ended_at` so the receiver does not stamp its own clock,
+     * hours later, as the end of a window used to attribute commits.
+     */
+    lastActivityAt: Date;
+}>;
+export declare function recordLastRun(run: HookLastRun): void;
+export declare function readLastRun(): HookLastRun | null;
+export declare function clearHookState(): void;
+export {};
+//# sourceMappingURL=agent-hook-state.d.ts.map

package/dist/src/lib/agent-hook-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-hook-state.d.ts","sourceRoot":"","sources":["../../../src/lib/agent-hook-state.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA6BxB,QAAA,MAAM,aAAa;;;;;;;;;iBAUjB,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAExD,QAAA,MAAM,gBAAgB;;;iBAGpB,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAK9D,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,IAAI,CAWN;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAgB5E;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAMvD;AAED,wBAAgB,eAAe,IAAI,KAAK,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,cAAc,EAAE,IAAI,CAAC;CACtB,CAAC,CAsBD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAOpD;AAED,wBAAgB,WAAW,IAAI,WAAW,GAAG,IAAI,CAShD;AAED,wBAAgB,cAAc,IAAI,IAAI,CAOrC"}

package/dist/src/lib/agent-hook-state.js

@@ -0,0 +1,136 @@
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+/**
+ * On-disk state the SessionStart/SessionEnd hook keeps between its two
+ * invocations, plus the record of what the last invocation achieved.
+ *
+ * Under the cache directory rather than the repository so it never shows up
+ * in `git status`. The path is unchanged from the standalone script this
+ * command replaced (`scripts/agent-telemetry/claude-hook.mjs`, since
+ * deleted) on purpose: a session that started under the old script must
+ * still be able to close under the new one, and a sweep must still find
+ * what the old one abandoned.
+ */
+const CACHE_DIR = join(homedir(), ".cache", "clocktopus");
+const STATE_DIR = join(CACHE_DIR, "agent-sessions");
+/**
+ * The hook's last outcome, written every run.
+ *
+ * This is the only place the pipeline reports on itself from the machine's
+ * own side. The hook must stay silent — it cannot warn, prompt or print —
+ * so instead it leaves a receipt, and `agent status` / `agent doctor` read
+ * it. Without this, a token that started returning 401 mid-week is
+ * invisible locally: the session runs normally and nothing is written
+ * anywhere the user looks.
+ */
+const LAST_RUN_FILE = join(CACHE_DIR, "agent-hook-last.json");
+const LastRunSchema = z.object({
+    at: z.string(),
+    event: z.string().optional(),
+    sessionId: z.string().optional(),
+    endpoint: z.string().optional(),
+    tokenPrefix: z.string().optional(),
+    /** HTTP status from the receiver, or null when the request never landed. */
+    status: z.number().nullable().optional(),
+    error: z.string().nullable().optional(),
+    repository: z.string().nullable().optional(),
+});
+const StartStateSchema = z.object({
+    sha: z.string(),
+    cwd: z.string().optional(),
+});
+const stateFile = (sessionId) => join(STATE_DIR, `${sessionId.replace(/[^\w-]/g, "")}.sha`);
+export function writeStartState(sessionId, sha, cwd) {
+    try {
+        mkdirSync(STATE_DIR, { recursive: true });
+        // `cwd` is stored alongside the SHA because the sweep runs from
+        // whatever repository the *next* session happens to start in.
+        // Resolving an abandoned session's SHA against the wrong checkout would
+        // either fail or, worse, succeed against an unrelated history.
+        writeFileSync(stateFile(sessionId), JSON.stringify({ sha, cwd }), "utf8");
+    }
+    catch {
+        // Losing the start SHA costs the exact commit list, not the session.
+    }
+}
+export function readStartState(sessionId) {
+    try {
+        const raw = readFileSync(stateFile(sessionId), "utf8").trim();
+        if (!raw)
+            return undefined;
+        try {
+            const parsed = StartStateSchema.safeParse(JSON.parse(raw));
+            return parsed.success ? parsed.data : undefined;
+        }
+        catch {
+            // Files written by earlier versions hold a bare SHA. A session that
+            // started under the old format must still close correctly.
+            return { sha: raw };
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+export function clearStartState(sessionId) {
+    try {
+        rmSync(stateFile(sessionId), { force: true });
+    }
+    catch {
+        // Best effort; a stale file is overwritten by the next session anyway.
+    }
+}
+export function listStartStates() {
+    try {
+        const now = Date.now();
+        return readdirSync(STATE_DIR)
+            .filter((name) => name.endsWith(".sha"))
+            .flatMap((name) => {
+            try {
+                const { mtimeMs } = statSync(join(STATE_DIR, name));
+                return [
+                    {
+                        sessionId: name.replace(/\.sha$/, ""),
+                        ageMs: now - mtimeMs,
+                        lastActivityAt: new Date(mtimeMs),
+                    },
+                ];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+export function recordLastRun(run) {
+    try {
+        mkdirSync(CACHE_DIR, { recursive: true });
+        writeFileSync(LAST_RUN_FILE, JSON.stringify(run, null, 2), "utf8");
+    }
+    catch {
+        // A missing receipt degrades diagnostics; it must never fail a session.
+    }
+}
+export function readLastRun() {
+    try {
+        const parsed = LastRunSchema.safeParse(JSON.parse(readFileSync(LAST_RUN_FILE, "utf8")));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function clearHookState() {
+    try {
+        rmSync(STATE_DIR, { recursive: true, force: true });
+        rmSync(LAST_RUN_FILE, { force: true });
+    }
+    catch {
+        // Nothing to clean up, or not ours to clean up.
+    }
+}

package/dist/src/lib/agent-receiver.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+export type ReceiverCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "invalid_token";
+} | {
+    ok: false;
+    reason: "unexpected_status";
+    status: number;
+} | {
+    ok: false;
+    reason: "unreachable";
+    message: string;
+};
+export declare function verifyReceiver(endpoint: string, token: string): Promise<ReceiverCheck>;
+//# sourceMappingURL=agent-receiver.d.ts.map

package/dist/src/lib/agent-receiver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-receiver.d.ts","sourceRoot":"","sources":["../../../src/lib/agent-receiver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GACtC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,CAAC,CA+BxB"}

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