@blastin-dev/clocktopus-cli 0.1.4 → 0.2.0

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();
+    });
+});

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

@@ -1,8 +1,25 @@
 export declare const ENVIRONMENTS: {
     readonly prod: "https://clocktopus.app";
+    readonly staging: "https://staging.clocktopus.app";
     readonly dev: "http://localhost:3000";
 };
 export type Environment = keyof typeof ENVIRONMENTS;
+/**
+ * Bookkeeping for the agent telemetry setup.
+ *
+ * Deliberately does **not** hold the ingest token. The token has to live in
+ * `~/.claude/settings.json` for Claude Code's exporter to read it, and a
+ * second copy here would be a second thing to leak and a second thing to
+ * fall out of date. What is kept is only what setup cannot recover later:
+ * the row id needed to revoke, and the prefix needed to display.
+ */
+type AgentConfig = {
+    tokenId?: string;
+    tokenPrefix?: string;
+    endpoint?: string;
+    /** ISO timestamp — `agent doctor` compares it against settings.json. */
+    configuredAt?: string;
+};
 export declare function setRuntimeEnvironment(env: Environment): void;
 export declare function getEnvironment(): Environment;
 export declare function getApiUrl(): string;
@@ -10,4 +27,10 @@ export declare function getToken(): string | undefined;
 export declare function setToken(token: string): void;
 export declare function clearToken(): void;
 export declare function isLoggedIn(): boolean;
+export declare function getAgentConfig(): AgentConfig;
+export declare function setAgentConfig(next: AgentConfig): void;
+export declare function clearAgentConfig(): void;
+/** Where the config lives, so `agent doctor` can point at a real file. */
+export declare function getConfigPath(): string;
+export {};
 //# sourceMappingURL=config.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/lib/config.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,YAAY,CAAC;AAapD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAE5D;AAED,wBAAgB,cAAc,IAAI,WAAW,CAO5C;AAED,wBAAgB,SAAS,IAAI,MAAM,CASlC;AAED,wBAAgB,QAAQ,IAAI,MAAM,GAAG,SAAS,CAE7C;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE5C;AAED,wBAAgB,UAAU,IAAI,IAAI,CAEjC;AAED,wBAAgB,UAAU,IAAI,OAAO,CAEpC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/lib/config.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY;;;;CAIf,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,YAAY,CAAC;AAEpD;;;;;;;;GAQG;AACH,KAAK,WAAW,GAAG;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAcF,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAE5D;AAED,wBAAgB,cAAc,IAAI,WAAW,CAO5C;AAED,wBAAgB,SAAS,IAAI,MAAM,CASlC;AAED,wBAAgB,QAAQ,IAAI,MAAM,GAAG,SAAS,CAE7C;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE5C;AAED,wBAAgB,UAAU,IAAI,IAAI,CAEjC;AAED,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED,wBAAgB,cAAc,IAAI,WAAW,CAE5C;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAEtD;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/dist/src/lib/config.js

@@ -1,6 +1,7 @@
 import Conf from "conf";
 export const ENVIRONMENTS = {
     prod: "https://clocktopus.app",
+    staging: "https://staging.clocktopus.app",
     dev: "http://localhost:3000",
 };
 const config = new Conf({
@@ -40,3 +41,16 @@ export function clearToken() {
 export function isLoggedIn() {
     return !!getToken();
 }
+export function getAgentConfig() {
+    return config.get("agent") ?? {};
+}
+export function setAgentConfig(next) {
+    config.set("agent", { ...getAgentConfig(), ...next });
+}
+export function clearAgentConfig() {
+    config.delete("agent");
+}
+/** Where the config lives, so `agent doctor` can point at a real file. */
+export function getConfigPath() {
+    return config.path;
+}

package/dist/src/lib/format.d.ts

@@ -0,0 +1,6 @@
+/** "3 minutes ago" / "never". Null-safe because most of these fields are. */
+export declare function formatAgo(value: string | null | undefined): string;
+export declare function microUsdToDisplay(microUsd: number): string;
+/** Pads a label so the value column lines up in the status blocks. */
+export declare function labelled(label: string, value: string, width?: number): string;
+//# sourceMappingURL=format.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/lib/format.ts"],"names":[],"mappings":"AAEA,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAOlE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,sEAAsE;AACtE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,MAAM,CAEzE"}

package/dist/src/lib/format.js

@@ -0,0 +1,19 @@
+import { formatDistanceToNowStrict, parseISO } from "date-fns";
+/** "3 minutes ago" / "never". Null-safe because most of these fields are. */
+export function formatAgo(value) {
+    if (!value)
+        return "never";
+    try {
+        return formatDistanceToNowStrict(parseISO(value), { addSuffix: true });
+    }
+    catch {
+        return value;
+    }
+}
+export function microUsdToDisplay(microUsd) {
+    return `$${(microUsd / 1_000_000).toFixed(2)}`;
+}
+/** Pads a label so the value column lines up in the status blocks. */
+export function labelled(label, value, width = 14) {
+    return `  ${label.padEnd(width)}${value}`;
+}

package/dist/src/lib/git.d.ts

@@ -0,0 +1,3 @@
+export declare function getRepositoryRemote(cwd?: string): string | null;
+export declare function isGitRepository(cwd?: string): boolean;
+//# sourceMappingURL=git.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../../src/lib/git.ts"],"names":[],"mappings":"AA0BA,wBAAgB,mBAAmB,CAAC,GAAG,SAAgB,GAAG,MAAM,GAAG,IAAI,CAEtE;AAED,wBAAgB,eAAe,CAAC,GAAG,SAAgB,GAAG,OAAO,CAE5D"}

package/dist/src/lib/git.js

@@ -0,0 +1,30 @@
+import { execFileSync } from "node:child_process";
+/**
+ * Just enough git to work out which repository the user is standing in.
+ *
+ * The CLI deliberately does not parse the remote — `apps/cli` is published
+ * standalone and cannot import `@repo/core`, so a parser here would be a
+ * second implementation destined to drift from the receiver's. The raw
+ * remote goes to the server, which owns the one definition of a supported
+ * remote.
+ */
+function git(cwd, args) {
+    try {
+        const output = execFileSync("git", args, {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2000,
+        }).trim();
+        return output || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function getRepositoryRemote(cwd = process.cwd()) {
+    return git(cwd, ["remote", "get-url", "origin"]) ?? null;
+}
+export function isGitRepository(cwd = process.cwd()) {
+    return git(cwd, ["rev-parse", "--is-inside-work-tree"]) === "true";
+}

package/dist/src/lib/repo-guidance.d.ts

@@ -0,0 +1,40 @@
+import type { RepoStatusResponse } from "./validators.js";
+/**
+ * The half of the setup that is not on this machine.
+ *
+ * Configuring the exporter and the hook makes agent sessions *arrive*. It
+ * does not make them *mean* anything, and the two ways that fails are
+ * unrelated to each other and to everything `agent setup` writes locally:
+ *
+ * - The repository is not attached to a project, so spend lands in the
+ *   unattributed row. Purely a Clocktopus-side mapping; no webhook affects
+ *   it either way.
+ * - The push webhook is not delivering, so there are no human time entries
+ *   to compare the spend against. Note this does *not* stop agent→commit
+ *   links: the SessionEnd hook resolves the commit range locally and posts
+ *   it. What is missing is the other side of the comparison, and a cost
+ *   without the hours it bought is not a smaller answer — it is not one.
+ *
+ * Reported as two separate verdicts, because they send you to two
+ * different places, and a single "not set up" would send you to neither.
+ */
+export type RepoCheck = {
+    label: string;
+    ok: boolean | "warn";
+    detail: string;
+    fix?: string;
+};
+/**
+ * Fetches readiness for the repository the CLI is standing in.
+ *
+ * Returns null when there is nothing to ask about — outside a git tree, or
+ * when the server is unreachable. A failure here must never fail `setup`:
+ * the local configuration it just wrote is valid regardless.
+ */
+export declare function fetchRepoStatus(cwd?: string): Promise<RepoStatusResponse | null>;
+export declare function attributionCheck(status: RepoStatusResponse): RepoCheck;
+export declare function commitLaneCheck(status: RepoStatusResponse): RepoCheck;
+export declare function repoChecks(status: RepoStatusResponse): RepoCheck[];
+/** The block `agent setup` prints after writing the local configuration. */
+export declare function renderRepoBlock(status: RepoStatusResponse): string[];
+//# sourceMappingURL=repo-guidance.d.ts.map

package/dist/src/lib/repo-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-guidance.d.ts","sourceRoot":"","sources":["../../../src/lib/repo-guidance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAO1D;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,OAAO,GAAG,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,GAAG,SAAgB,GAClB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAapC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,CAqDtE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,CAqCrE;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,EAAE,CAElE;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAepE"}