@blastin-dev/clocktopus-cli 0.1.4 → 0.2.1

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/codex-config.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Reads and edits Codex CLI's configuration on the user's behalf.
+ *
+ * Codex splits what Claude Code keeps in one file: telemetry goes in
+ * `~/.codex/config.toml` under `[otel]`, hooks go in a separate
+ * `~/.codex/hooks.json`. Both are edited here under the same two rules as
+ * `claude-settings.ts` — never write over something we could not parse, and
+ * only ever touch keys we put there — plus a third that TOML forces on us:
+ *
+ * **Splice, don't re-serialise.** A round trip through a TOML parser throws
+ * away every comment and blank line in the file. `config.toml` is a file
+ * people hand-write and annotate, so only the `[otel]` region is replaced
+ * textually; everything else survives byte for byte. `writeCodexConfig`
+ * re-parses the spliced result and refuses to write if anything outside
+ * `[otel]` moved, which is what makes the textual approach safe.
+ *
+ * ## What Codex does with these, and why it matters here
+ *
+ * - `otel.exporter` is the **log** exporter, and Codex POSTs to the URL
+ *   verbatim — it does not append `/v1/logs` the way the OTel SDK does. The
+ *   path is therefore part of the configured endpoint, and
+ *   `readCodexTelemetry` strips it back off to recover the receiver base.
+ * - Codex will not run a `hooks.json` it has not been shown: the first
+ *   session after this file changes prompts "Hooks need review" and
+ *   persists the answer under `[hooks.state]`. Setup cannot do that for the
+ *   user, so it tells them instead — see `setup.ts`.
+ */
+export declare const CODEX_CONFIG_FILENAME = "config.toml";
+export declare const CODEX_HOOKS_FILENAME = "hooks.json";
+/**
+ * The receiver path Codex's log exporter is pointed at.
+ *
+ * Load-bearing in both directions: written onto the endpoint because Codex
+ * sends to the literal URL, and stripped when reading because the hook and
+ * `/v1/verify` need the base.
+ */
+export declare const CODEX_LOGS_PATH = "/v1/logs";
+/**
+ * Seconds Codex will wait for each hook.
+ *
+ * SessionEnd is 3 rather than 10 because Codex hard-clamps it to 3 and
+ * prints `warning: clamping SessionEnd hook timeout to 3s` on every single
+ * session start otherwise — a permanent warning about a value we chose is
+ * worse than the shorter budget, and the hook's own request timeout is 4s.
+ */
+export declare const CODEX_HOOK_TIMEOUT_SECONDS: {
+    SessionStart: number;
+    SessionEnd: number;
+};
+declare const HOOK_EVENTS: readonly ["SessionStart", "SessionEnd"];
+/** Exported so callers can tell "none approved" from "some approved". */
+export declare const HOOK_EVENT_COUNT: 2;
+type HookEvent = (typeof HOOK_EVENTS)[number];
+type TomlTable = Record<string, unknown>;
+export declare class CodexConfigParseError extends Error {
+    readonly path: string;
+    constructor(path: string, detail: string);
+}
+export declare function codexConfigDir(): string;
+export declare function codexConfigPath(): string;
+export declare function codexHooksPath(): string;
+export declare function readCodexConfig(path?: string): {
+    path: string;
+    exists: boolean;
+    modifiedAt: Date | null;
+    text: string;
+    config: TomlTable;
+};
+export declare function buildCodexOtel(input: {
+    token: string;
+    endpoint: string;
+}): TomlTable;
+/**
+ * Replaces the `[otel]` region of a TOML document, preserving everything else.
+ *
+ * Returns the new text. Region detection is deliberately dumb — table
+ * headers only — and `writeCodexConfig` verifies the result by re-parsing,
+ * so a document this misreads is refused rather than mangled.
+ */
+export declare function spliceOtelSection(text: string, otel: TomlTable | null): string;
+/**
+ * Writes config.toml, keeping a one-deep backup and verifying the splice.
+ *
+ * The verification is the point: it re-parses what is about to be written
+ * and compares every top-level key *except* `otel` against what was there
+ * before. If the textual splice disturbed anything else — an exotic layout
+ * the region scanner misread — the write is refused with the user's file
+ * still intact.
+ */
+export declare function writeCodexConfig(input: {
+    path?: string;
+    previousText: string;
+    previousConfig: TomlTable;
+    nextText: string;
+}): {
+    backupPath: string | null;
+};
+/** What config.toml currently declares, for `status` and `doctor`. */
+export declare function readCodexTelemetry(path?: string): {
+    path: string;
+    exists: boolean;
+    modifiedAt: Date | null;
+    token: string | null;
+    /** The receiver base, with `/v1/logs` stripped back off. */
+    endpoint: string | null;
+    protocol: string | null;
+    logUserPrompt: boolean | null;
+};
+export declare function applyCodexOtel(current: {
+    text: string;
+    config: TomlTable;
+}, input: {
+    token: string;
+    endpoint: string;
+}): string;
+export declare function removeCodexOtel(current: {
+    text: string;
+    config: TomlTable;
+}): {
+    nextText: string;
+    removedKeys: string[];
+};
+export declare function readCodexHooks(path?: string): {
+    path: string;
+    exists: boolean;
+    modifiedAt: Date | null;
+    file: Record<string, unknown>;
+    commands: Partial<Record<HookEvent, string>>;
+};
+export declare function applyCodexHooks(file: Record<string, unknown>, input: {
+    hookCommand: string;
+}): Record<string, unknown>;
+export declare function removeCodexHooks(file: Record<string, unknown>): {
+    file: Record<string, unknown>;
+    removed: boolean;
+};
+export declare function writeCodexHooks(file: Record<string, unknown>, path?: string): {
+    backupPath: string | null;
+};
+/**
+ * Which of our hooks Codex has been shown and told to run.
+ *
+ * Trust is recorded **per hook entry**, not per file:
+ *
+ * ```toml
+ * [hooks.state."/home/you/.codex/hooks.json:session_end:0:0"]
+ * trusted_hash = "sha256:…"
+ * ```
+ *
+ * The key is `<path>:<event>:<group index>:<hook index>`, with the event in
+ * snake_case. Per-entry granularity is why this reports each event rather
+ * than a single boolean: partial trust is a real state, and the one that
+ * matters. A machine whose `SessionEnd` is trusted and whose `SessionStart`
+ * is not records spend with no repository attached to it — which is exactly
+ * what an `async: true` SessionStart used to produce on Codex 0.147, since
+ * the hook was skipped before it could ever be offered for approval.
+ *
+ * The hash is Codex's own and is not recomputed here; changing `hooks.json`
+ * invalidates it and Codex re-prompts, which is the behaviour we want.
+ */
+export declare function readCodexHookTrust(path?: string): {
+    trusted: HookEvent[];
+    untrusted: HookEvent[];
+};
+export {};
+//# sourceMappingURL=codex-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codex-config.d.ts","sourceRoot":"","sources":["../../../src/lib/codex-config.ts"],"names":[],"mappings":"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"}