@blastin-dev/clocktopus-cli 0.2.0 → 0.2.1

package/dist/src/lib/codex-config.test.js

@@ -0,0 +1,359 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { applyCodexHooks, applyCodexOtel, buildCodexOtel, CodexConfigParseError, readCodexConfig, readCodexHooks, readCodexHookTrust, readCodexTelemetry, removeCodexHooks, removeCodexOtel, spliceOtelSection, writeCodexConfig, writeCodexHooks, } from "./codex-config";
+/**
+ * These tests exist because this module edits two files we do not own.
+ * `~/.codex/config.toml` holds the user's model, sandbox policy, MCP
+ * servers and project trust decisions — hand-written and usually commented
+ * — and `hooks.json` may already hold hooks that have nothing to do with
+ * us. A merge bug here destroys work unrelated to Clocktopus.
+ */
+const INSTALL = {
+    token: "ctop_agt_testtoken",
+    endpoint: "https://otel.example.com",
+    hookCommand: "clocktopus agent hook --provider codex_cli",
+};
+/** A config.toml with the user's own settings, comments and layout. */
+const USER_CONFIG = `# my codex setup
+model = "gpt-5.6-sol"
+approval_policy = "on-request"
+
+[sandbox_workspace_write]
+network_access = true    # needed for npm
+
+[mcp_servers.linear]
+command = "npx"
+args = ["-y", "linear-mcp"]
+`;
+let dir;
+let configPath;
+let hooksPath;
+beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "clocktopus-codex-"));
+    configPath = join(dir, "config.toml");
+    hooksPath = join(dir, "hooks.json");
+});
+afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+});
+describe("buildCodexOtel", () => {
+    it("puts the receiver path on the endpoint, because Codex does not add one", () => {
+        const otel = buildCodexOtel(INSTALL);
+        const http = otel.exporter["otlp-http"];
+        // Codex POSTs to the configured URL verbatim — unlike the OTel SDK, it
+        // does not append `/v1/logs`. Omitting the path here would send every
+        // export to the receiver's root and 404 silently.
+        expect(http.endpoint).toBe("https://otel.example.com/v1/logs");
+        expect(http.protocol).toBe("json");
+        expect(http.headers.Authorization).toBe("Bearer ctop_agt_testtoken");
+    });
+    it("does not double the path when the endpoint already ends in a slash", () => {
+        const otel = buildCodexOtel({
+            ...INSTALL,
+            endpoint: "https://otel.example.com/",
+        });
+        const http = otel.exporter["otlp-http"];
+        expect(http.endpoint).toBe("https://otel.example.com/v1/logs");
+    });
+    it("turns prompt logging off explicitly rather than trusting the default", () => {
+        expect(buildCodexOtel(INSTALL).log_user_prompt).toBe(false);
+    });
+});
+describe("splicing [otel] into a hand-written config.toml", () => {
+    it("adds the section without disturbing comments or layout", () => {
+        const next = spliceOtelSection(USER_CONFIG, buildCodexOtel(INSTALL));
+        // Every line the user wrote survives, byte for byte. A round trip
+        // through a TOML serialiser would silently drop all three comments.
+        expect(next).toContain("# my codex setup");
+        expect(next).toContain("network_access = true    # needed for npm");
+        expect(next).toContain('args = ["-y", "linear-mcp"]');
+        const parsed = parseToml(next);
+        expect(parsed.model).toBe("gpt-5.6-sol");
+        expect(parsed.mcp_servers).toEqual({
+            linear: { command: "npx", args: ["-y", "linear-mcp"] },
+        });
+        expect(parsed.otel.log_user_prompt).toBe(false);
+    });
+    it("replaces an existing [otel] section instead of appending a second", () => {
+        const withOtel = spliceOtelSection(USER_CONFIG, buildCodexOtel(INSTALL));
+        const twice = spliceOtelSection(withOtel, buildCodexOtel({ ...INSTALL, token: "ctop_agt_second" }));
+        // TOML rejects a duplicated table outright, so an append bug here would
+        // stop Codex booting at all.
+        expect(twice.match(/^\[otel\]/gm)).toHaveLength(1);
+        expect(twice).toContain("ctop_agt_second");
+        expect(twice).not.toContain("ctop_agt_testtoken");
+        expect(() => parseToml(twice)).not.toThrow();
+    });
+    it("keeps the user's own [otel] keys when merging ours in", () => {
+        const config = `${USER_CONFIG}
+[otel]
+environment = "staging"
+`;
+        const parsed = parseToml(config);
+        const next = applyCodexOtel({ text: config, config: parsed }, INSTALL);
+        const result = parseToml(next);
+        expect(result.otel.environment).toBe("staging");
+        expect(result.otel.log_user_prompt).toBe(false);
+    });
+    it("removes only our keys, leaving the rest of [otel] behind", () => {
+        const config = `${USER_CONFIG}
+[otel]
+environment = "staging"
+`;
+        const withOurs = applyCodexOtel({ text: config, config: parseToml(config) }, INSTALL);
+        const { nextText, removedKeys } = removeCodexOtel({
+            text: withOurs,
+            config: parseToml(withOurs),
+        });
+        expect(removedKeys.sort()).toEqual(["exporter", "log_user_prompt"]);
+        const parsed = parseToml(nextText);
+        expect(parsed.otel).toEqual({ environment: "staging" });
+        expect(parsed.model).toBe("gpt-5.6-sol");
+    });
+    it("drops [otel] entirely when nothing of the user's is left in it", () => {
+        const withOurs = spliceOtelSection(USER_CONFIG, buildCodexOtel(INSTALL));
+        const { nextText } = removeCodexOtel({
+            text: withOurs,
+            config: parseToml(withOurs),
+        });
+        expect(nextText).not.toContain("[otel]");
+        expect(parseToml(nextText)).toEqual(parseToml(USER_CONFIG));
+    });
+    it("survives an add/remove cycle without accumulating blank lines", () => {
+        let text = USER_CONFIG;
+        for (let i = 0; i < 3; i++) {
+            text = spliceOtelSection(text, buildCodexOtel(INSTALL));
+            text = removeCodexOtel({
+                text,
+                config: parseToml(text),
+            }).nextText;
+        }
+        expect(text).toBe(USER_CONFIG);
+    });
+    it("creates the section from nothing when the file does not exist yet", () => {
+        const next = spliceOtelSection("", buildCodexOtel(INSTALL));
+        expect(parseToml(next).otel).toBeDefined();
+    });
+});
+describe("writeCodexConfig — the guard on the splice", () => {
+    it("writes the edit and backs up what was there", () => {
+        writeFileSync(configPath, USER_CONFIG);
+        const current = readCodexConfig(configPath);
+        const { backupPath } = writeCodexConfig({
+            path: configPath,
+            previousText: current.text,
+            previousConfig: current.config,
+            nextText: applyCodexOtel(current, INSTALL),
+        });
+        expect(backupPath).toBe(`${configPath}.clocktopus-backup`);
+        expect(readFileSync(backupPath, "utf8")).toBe(USER_CONFIG);
+        expect(readCodexTelemetry(configPath).token).toBe(INSTALL.token);
+    });
+    it("refuses to write an edit that would change anything outside [otel]", () => {
+        writeFileSync(configPath, USER_CONFIG);
+        const current = readCodexConfig(configPath);
+        // Stands in for a splice that misread the file's layout. Rather than
+        // trusting the region scanner, the write verifies its own result — so a
+        // document it cannot handle costs the user nothing.
+        expect(() => writeCodexConfig({
+            path: configPath,
+            previousText: current.text,
+            previousConfig: current.config,
+            nextText: 'model = "gpt-5.6-sol"\n',
+        })).toThrow(/would have changed/);
+        expect(readFileSync(configPath, "utf8")).toBe(USER_CONFIG);
+    });
+    it("refuses to write anything that is not valid TOML", () => {
+        writeFileSync(configPath, USER_CONFIG);
+        const current = readCodexConfig(configPath);
+        expect(() => writeCodexConfig({
+            path: configPath,
+            previousText: current.text,
+            previousConfig: current.config,
+            nextText: "[[[nope",
+        })).toThrow(/did not produce valid TOML/);
+        expect(readFileSync(configPath, "utf8")).toBe(USER_CONFIG);
+    });
+    it("raises rather than overwriting a config.toml it cannot parse", () => {
+        // Far more likely a half-finished edit than something to clobber.
+        writeFileSync(configPath, "model = = =");
+        expect(() => readCodexConfig(configPath)).toThrow(CodexConfigParseError);
+    });
+});
+describe("readCodexTelemetry", () => {
+    it("strips the receiver path back off so the hook gets a base URL", () => {
+        writeFileSync(configPath, spliceOtelSection(USER_CONFIG, buildCodexOtel(INSTALL)));
+        const telemetry = readCodexTelemetry(configPath);
+        // The hook posts to `<endpoint>/v1/agent-session` and doctor to
+        // `<endpoint>/v1/verify`; leaving `/v1/logs` on would make both 404.
+        expect(telemetry.endpoint).toBe("https://otel.example.com");
+        expect(telemetry.token).toBe(INSTALL.token);
+        expect(telemetry.protocol).toBe("json");
+    });
+    it("reports nothing configured rather than throwing on a missing file", () => {
+        expect(readCodexTelemetry(configPath)).toMatchObject({
+            exists: false,
+            token: null,
+            endpoint: null,
+        });
+    });
+});
+describe("hooks.json", () => {
+    /** Reads one event's matcher groups back out with the shape Codex expects. */
+    const groups = (file, event) => file.hooks[event] ?? [];
+    const userHooks = () => ({
+        description: "my hooks",
+        hooks: {
+            SessionStart: [
+                { hooks: [{ type: "command", command: "echo user-session-start" }] },
+            ],
+            PreToolUse: [
+                { matcher: "shell", hooks: [{ type: "command", command: "echo pre" }] },
+            ],
+        },
+    });
+    it("appends our hook without removing the user's", () => {
+        const next = applyCodexHooks(userHooks(), INSTALL);
+        const start = groups(next, "SessionStart");
+        expect(start).toHaveLength(2);
+        expect(start[0].hooks[0].command).toBe("echo user-session-start");
+        expect(start[1].hooks[0].command).toBe(INSTALL.hookCommand);
+        expect(groups(next, "PreToolUse")).toEqual(userHooks().hooks.PreToolUse);
+    });
+    it("gives SessionEnd the 3s budget Codex clamps it to", () => {
+        const next = applyCodexHooks({}, INSTALL);
+        // Codex hard-clamps SessionEnd and prints a warning on every session
+        // start if we ask for more. 10s for SessionStart, which it honours.
+        expect(groups(next, "SessionStart")[0].hooks[0].timeout).toBe(10);
+        expect(groups(next, "SessionEnd")[0].hooks[0].timeout).toBe(3);
+    });
+    it("never writes an `async` key, on either event", () => {
+        // The regression this pins cost a real user their repository
+        // attribution. Codex 0.147 does not skip an async hook quietly-ish and
+        // carry on: it drops SessionStart entirely, so `cwd` — the only source
+        // of repository, branch and starting SHA anywhere in the pipeline —
+        // never arrives, while spend keeps flowing in unattributed. 0.148
+        // honours it on SessionStart but still forces SessionEnd synchronous
+        // and warns once per session.
+        //
+        // `agent hook` backgrounds itself instead, so this key has no upside on
+        // any version.
+        const next = applyCodexHooks({}, INSTALL);
+        for (const event of ["SessionStart", "SessionEnd"]) {
+            const entry = groups(next, event)[0].hooks[0];
+            expect(entry).not.toHaveProperty("async");
+        }
+    });
+    it("replaces our hook on re-run instead of installing a second", () => {
+        const once = applyCodexHooks(userHooks(), INSTALL);
+        const twice = applyCodexHooks(once, {
+            hookCommand: "/usr/local/bin/clocktopus agent hook --provider codex_cli",
+        });
+        // Two of our hooks would POST every SessionStart twice.
+        const start = groups(twice, "SessionStart");
+        expect(start).toHaveLength(2);
+        expect(start[1].hooks[0].command).toContain("/usr/local/bin/clocktopus");
+    });
+    it("removes ours and leaves the user's intact", () => {
+        const installed = applyCodexHooks(userHooks(), INSTALL);
+        const { file, removed } = removeCodexHooks(installed);
+        expect(removed).toBe(true);
+        expect(file).toMatchObject({ hooks: userHooks().hooks });
+    });
+    it("round-trips through disk and finds our command again", () => {
+        writeCodexHooks(applyCodexHooks(userHooks(), INSTALL), hooksPath);
+        const read = readCodexHooks(hooksPath);
+        expect(read.commands.SessionStart).toBe(INSTALL.hookCommand);
+        expect(read.commands.SessionEnd).toBe(INSTALL.hookCommand);
+    });
+    it("raises rather than overwriting a hooks.json it cannot parse", () => {
+        writeFileSync(hooksPath, "{ not json");
+        expect(() => readCodexHooks(hooksPath)).toThrow(CodexConfigParseError);
+    });
+});
+describe("readCodexHookTrust — Codex's per-entry trust records", () => {
+    /**
+     * The key format is taken verbatim from a real `~/.codex/config.toml`
+     * after Codex 0.147 prompted and the answer was persisted. Trust is
+     * recorded per hook *entry* — `<path>:<event>:<group>:<index>` — not per
+     * file, which an earlier version of this function assumed; matching the
+     * bare path found nothing and reported a correctly-approved install as
+     * still pending, forever.
+     */
+    const trustState = (entries) => `[hooks.state]\n${entries
+        .map((key) => `\n[hooks.state."${key}"]\ntrusted_hash = "sha256:c3ffbe52"\nenabled = true\n`)
+        .join("")}`;
+    it("reads a fully approved install", () => {
+        writeFileSync(configPath, trustState([
+            `${hooksPath}:session_start:0:0`,
+            `${hooksPath}:session_end:0:0`,
+        ]));
+        // `hooksPath` is the temp dir's file, so point the reader at it too.
+        process.env.CODEX_HOME = dir;
+        try {
+            expect(readCodexHookTrust(configPath)).toEqual({
+                trusted: ["SessionStart", "SessionEnd"],
+                untrusted: [],
+            });
+        }
+        finally {
+            delete process.env.CODEX_HOME;
+        }
+    });
+    it("spots the half-approved install that loses repository context", () => {
+        // Exactly the state an `async: true` SessionStart left behind on Codex
+        // 0.147: the hook was skipped outright, so it was never offered for
+        // approval, while SessionEnd was. Sessions close but never open.
+        writeFileSync(configPath, trustState([`${hooksPath}:session_end:0:0`]));
+        process.env.CODEX_HOME = dir;
+        try {
+            expect(readCodexHookTrust(configPath)).toEqual({
+                trusted: ["SessionEnd"],
+                untrusted: ["SessionStart"],
+            });
+        }
+        finally {
+            delete process.env.CODEX_HOME;
+        }
+    });
+    it("reads Codex 0.148's hash-only record, which omits `enabled`", () => {
+        // 0.148 persists `hooks.state."<key>".trusted_hash` and nothing else —
+        // its `HookStateToml` has no `enabled` field. Demanding `enabled = true`
+        // reported a just-approved install as still pending, and no amount of
+        // restarting Codex could clear it: it never prompts again once trusted.
+        writeFileSync(configPath, `[hooks.state."${hooksPath}:session_start:0:0"]\ntrusted_hash = "sha256:c3ffbe52"\n` +
+            `\n[hooks.state."${hooksPath}:session_end:0:0"]\ntrusted_hash = "sha256:8b152fa9"\nenabled = true\n`);
+        process.env.CODEX_HOME = dir;
+        try {
+            expect(readCodexHookTrust(configPath)).toEqual({
+                trusted: ["SessionStart", "SessionEnd"],
+                untrusted: [],
+            });
+        }
+        finally {
+            delete process.env.CODEX_HOME;
+        }
+    });
+    it("treats an entry the user explicitly disabled as untrusted", () => {
+        writeFileSync(configPath, `[hooks.state."${hooksPath}:session_start:0:0"]\ntrusted_hash = "sha256:c3ffbe52"\nenabled = false\n`);
+        process.env.CODEX_HOME = dir;
+        try {
+            expect(readCodexHookTrust(configPath).untrusted).toEqual([
+                "SessionStart",
+                "SessionEnd",
+            ]);
+        }
+        finally {
+            delete process.env.CODEX_HOME;
+        }
+    });
+    it("reports everything untrusted when there is no config at all", () => {
+        expect(readCodexHookTrust(join(dir, "missing.toml")).untrusted).toEqual([
+            "SessionStart",
+            "SessionEnd",
+        ]);
+    });
+});

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

@@ -0,0 +1,108 @@
+/**
+ * Installs and reads back the OpenCode plugin that reports to Clocktopus.
+ *
+ * OpenCode is the odd one out. Claude Code and Codex both expose a *hook*
+ * — a command they run with JSON on stdin — so wiring them up is a matter
+ * of editing config. OpenCode instead exposes a plugin API: JavaScript
+ * loaded into its own process, handed a stream of typed events. So the
+ * integration is a file of ours rather than a config entry pointing at the
+ * CLI.
+ *
+ * The install is a single file. OpenCode auto-loads everything in
+ * `<config dir>/plugin/`, verified against 1.18.18, so nothing has to be
+ * added to `opencode.json` — which is worth having: that file is the
+ * user's model, provider and permission configuration, and not touching it
+ * removes a whole class of ways to break their setup. Uninstalling is
+ * deleting the file.
+ *
+ * ## Why a plugin and not OpenCode's own OpenTelemetry
+ *
+ * OpenCode has `experimental.openTelemetry`, which exports OTLP/JSON traces
+ * to `OTEL_EXPORTER_OTLP_ENDPOINT` — on the face of it exactly what we
+ * want, and a one-line install. It was measured and rejected:
+ *
+ * - **It ships the conversation.** The AI SDK spans carry `ai.prompt`,
+ *   `ai.prompt.messages` and `ai.response.text` — the system prompt, every
+ *   user message and the model's replies, verbatim, with no switch to turn
+ *   them off. Codex's log stream leaks tool output; this leaks everything.
+ * - **It is enormous.** One prompt produced 230KB, almost all of it
+ *   OpenCode's internal spans — SQLite queries, file reads, lock
+ *   acquisitions — with the AI spans a rounding error inside it.
+ * - **It carries no cost and no repository**, so it could not do the one
+ *   job the feature exists for.
+ *
+ * The plugin sees a better source than the traces do: `AssistantMessage`
+ * carries `cost`, a full token breakdown, the model, and `path.cwd`. It
+ * sends numbers and identifiers, and nothing a person wrote.
+ */
+export declare const OPENCODE_PLUGIN_FILENAME = "clocktopus.js";
+/**
+ * Bumped whenever `buildOpencodePlugin` changes what it emits.
+ *
+ * OpenCode is the only agent whose integration is *generated source* rather
+ * than a command string in a config file. Claude Code and Codex hold
+ * `clocktopus agent hook …`, which means whatever the installed CLI means,
+ * so upgrading the CLI upgrades them. This plugin does not: the file on
+ * disk stays exactly as the CLI that wrote it left it, and a fix shipped to
+ * the plugin body reaches nobody until they re-run `agent setup`.
+ *
+ * Stamping the generation is what makes that visible — `agent doctor`
+ * compares this number against the file and says so when they differ.
+ * Nothing auto-rewrites the file: it holds a token, and a command that
+ * quietly rewrites credentials is worse than one that tells you to.
+ *
+ * A plugin written before the stamp existed parses as `null`, which reads
+ * as stale — correct, since it predates every version that has one.
+ */
+export declare const OPENCODE_PLUGIN_VERSION = 1;
+export declare function opencodeConfigDir(): string;
+export declare function opencodePluginPath(): string;
+export type OpencodePluginConfig = {
+    endpoint: string;
+    token: string;
+    /**
+     * The hook as argv, not as a command line.
+     *
+     * `resolveHookCommand` returns a shell-quoted string because that is what
+     * `settings.json` and `hooks.json` want — their hosts run it through a
+     * shell. This plugin spawns it directly, so it needs the arguments
+     * already separated: splitting the string on spaces would tear a quoted
+     * path in two the moment anyone installs Node somewhere with a space in
+     * it, and the failure would be silent.
+     */
+    hookArgv: string[];
+};
+/**
+ * Splits a shell-quoted command line into argv.
+ *
+ * Only as clever as `resolveHookCommand` is: double quotes around
+ * whitespace, nothing else. It is fed that function's output, never a
+ * user's shell.
+ */
+export declare function splitCommandLine(command: string): string[];
+/**
+ * The plugin source, with this machine's configuration baked into one line.
+ *
+ * Generated rather than shipped as a file because the token has to be in
+ * it: OpenCode gives a plugin no way to read our environment, so the
+ * credentials live where every other agent's do — in that agent's config,
+ * written 0600.
+ */
+export declare function buildOpencodePlugin(config: OpencodePluginConfig): string;
+export declare function readOpencodePlugin(path?: string): {
+    path: string;
+    exists: boolean;
+    modifiedAt: Date | null;
+    config: OpencodePluginConfig | null;
+    /**
+     * The generation that wrote this file, or null when it carries no stamp —
+     * either a plugin from before stamping existed, or one hand-edited past
+     * recognition. Both mean the same thing to the caller: not current.
+     */
+    version: number | null;
+};
+export declare function writeOpencodePlugin(source: string, path?: string): {
+    backupPath: string | null;
+};
+export declare function removeOpencodePlugin(path?: string): boolean;
+//# sourceMappingURL=opencode-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"opencode-config.d.ts","sourceRoot":"","sources":["../../../src/lib/opencode-config.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AAQxD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,wBAAgB,iBAAiB,IAAI,MAAM,CAK1C;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;OASG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAI1D;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAqLxE;AAED,wBAAgB,kBAAkB,CAAC,IAAI,SAAuB,GAAG;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACpC;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CA+CA;AAED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,IAAI,SAAuB,GAC1B;IAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAiB/B;AAED,wBAAgB,oBAAoB,CAAC,IAAI,SAAuB,GAAG,OAAO,CAIzE"}