@blastin-dev/clocktopus-cli 0.2.0 → 0.3.0

package/dist/src/lib/git-remotes.js

@@ -0,0 +1,50 @@
+// Every remote a checkout has, for attributing the session to a repository.
+//
+// `origin` is a naming convention, not evidence. On a fork it names the developer's
+// own copy while the webhooks — and so every commit row — arrive under the upstream,
+// which left those sessions attributed to a repository nothing else in the system
+// ever mentions (BLA-598). The receiver decides which one wins; the hook's job is to
+// report them all.
+/** Ceiling matching `AgentSessionHookSchema`. A checkout with more is not a real one. */
+const MAX_REMOTES = 20;
+/**
+ * Parses `git remote -v` into a deduplicated URL list, `origin` first.
+ *
+ * Order is load-bearing in one narrow way: the first entry is what a receiver older
+ * than BLA-598 reads as the only remote, so keeping `origin` there preserves the
+ * previous behaviour exactly.
+ */
+export function parseGitRemotes(output) {
+    if (!output?.trim())
+        return [];
+    const byName = new Map();
+    for (const line of output.split("\n")) {
+        // `name\turl (fetch|push)` — push URLs can differ from fetch ones, and both are
+        // worth reporting: a fork often fetches upstream and pushes to itself.
+        const match = line.trim().match(/^(\S+)\s+(\S+)\s+\((fetch|push)\)$/);
+        if (!match)
+            continue;
+        const [, name, url, direction] = match;
+        if (!name || !url)
+            continue;
+        const key = `${name}:${direction}`;
+        if (!byName.has(key))
+            byName.set(key, url);
+    }
+    const entries = [...byName.entries()];
+    const ordered = [
+        ...entries.filter(([key]) => key.startsWith("origin:")),
+        ...entries.filter(([key]) => !key.startsWith("origin:")),
+    ];
+    const seen = new Set();
+    const urls = [];
+    for (const [, url] of ordered) {
+        if (seen.has(url))
+            continue;
+        seen.add(url);
+        urls.push(url);
+        if (urls.length === MAX_REMOTES)
+            break;
+    }
+    return urls;
+}

package/dist/src/lib/git-remotes.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=git-remotes.test.d.ts.map

package/dist/src/lib/git-remotes.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-remotes.test.d.ts","sourceRoot":"","sources":["../../../src/lib/git-remotes.test.ts"],"names":[],"mappings":""}

package/dist/src/lib/git-remotes.test.js

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { parseGitRemotes } from "./git-remotes.js";
+describe("parseGitRemotes", () => {
+    it("keeps origin first, so an older receiver reading only the first entry is unchanged", () => {
+        const urls = parseGitRemotes([
+            "upstream\tgit@github.com:acme-co/portal.git (fetch)",
+            "upstream\tgit@github.com:acme-co/portal.git (push)",
+            "origin\tgit@github.com:jordan/portal.git (fetch)",
+            "origin\tgit@github.com:jordan/portal.git (push)",
+        ].join("\n"));
+        expect(urls[0]).toBe("git@github.com:jordan/portal.git");
+        expect(urls).toContain("git@github.com:acme-co/portal.git");
+    });
+    it("collapses the fetch and push lines of one remote", () => {
+        const urls = parseGitRemotes([
+            "origin\tgit@github.com:acme-co/portal.git (fetch)",
+            "origin\tgit@github.com:acme-co/portal.git (push)",
+        ].join("\n"));
+        expect(urls).toEqual(["git@github.com:acme-co/portal.git"]);
+    });
+    /** A fork often fetches from upstream and pushes to itself under one remote name. */
+    it("keeps both URLs when a remote's push target differs from its fetch", () => {
+        const urls = parseGitRemotes([
+            "origin\tgit@github.com:acme-co/portal.git (fetch)",
+            "origin\tgit@github.com:jordan/portal.git (push)",
+        ].join("\n"));
+        expect(urls).toEqual([
+            "git@github.com:acme-co/portal.git",
+            "git@github.com:jordan/portal.git",
+        ]);
+    });
+    it("returns nothing for a checkout with no remotes", () => {
+        expect(parseGitRemotes("")).toEqual([]);
+        expect(parseGitRemotes(undefined)).toEqual([]);
+    });
+    it("works when no remote is called origin", () => {
+        const urls = parseGitRemotes("github\tgit@github.com:acme-co/portal.git (fetch)");
+        expect(urls).toEqual(["git@github.com:acme-co/portal.git"]);
+    });
+    it("ignores lines that are not remote entries", () => {
+        const urls = parseGitRemotes([
+            "origin\tgit@github.com:acme-co/portal.git (fetch)",
+            "warning: something else entirely",
+            "",
+        ].join("\n"));
+        expect(urls).toEqual(["git@github.com:acme-co/portal.git"]);
+    });
+    it("caps a pathological remote list", () => {
+        const lines = Array.from({ length: 40 }, (_, i) => `r${i}\tgit@github.com:acme-co/repo-${i}.git (fetch)`);
+        expect(parseGitRemotes(lines.join("\n"))).toHaveLength(20);
+    });
+});

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

@@ -0,0 +1,23 @@
+export declare const OPENCODE_PLUGIN_FILENAME = "clocktopus.js";
+export declare const OPENCODE_PLUGIN_VERSION = 1;
+export declare function opencodeConfigDir(): string;
+export declare function opencodePluginPath(): string;
+export type OpencodePluginConfig = {
+    endpoint: string;
+    token: string;
+    hookArgv: string[];
+};
+export declare function splitCommandLine(command: string): string[];
+export declare function buildOpencodePlugin(config: OpencodePluginConfig): string;
+export declare function readOpencodePlugin(path?: string): {
+    path: string;
+    exists: boolean;
+    modifiedAt: Date | null;
+    config: OpencodePluginConfig | null;
+    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":"AAsCA,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AAoBxD,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;IAOd,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAIF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAI1D;AAMD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CA0KxE;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;IAIpC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CA8CA;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"}

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

@@ -0,0 +1,290 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+// Installs and reads back the OpenCode plugin that reports to Clocktopus.
+//
+// OpenCode is the odd one out: Claude Code and Codex expose a *hook* — a command run
+// with JSON on stdin — while OpenCode exposes a plugin API, JavaScript loaded into
+// its own process. So the integration is a file of ours rather than a config entry.
+//
+// The install is a single file. OpenCode auto-loads everything in `<config
+// dir>/plugin/` (verified against 1.18.18), so `opencode.json` is never touched —
+// worth having, since that file is the user's model, provider and permission config.
+// Uninstalling is deleting the file.
+//
+// Not OpenCode's own `experimental.openTelemetry`, which exports OTLP/JSON traces and
+// looks like 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` verbatim, with no switch to turn
+//   them off.
+// - It is enormous: one prompt produced 230KB, almost all OpenCode's internal spans.
+// - 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: `AssistantMessage` carries `cost`, a full token
+// breakdown, the model, and `path.cwd`. It sends numbers and identifiers, and
+// nothing a person wrote.
+export const OPENCODE_PLUGIN_FILENAME = "clocktopus.js";
+/** The line `readOpencodeTelemetry` parses back out of the plugin. */
+const CONFIG_MARKER = "const CLOCKTOPUS = ";
+/** Prefix of the line carrying the generation stamp. */
+const VERSION_MARKER = "// clocktopus-plugin-version: ";
+// Bumped whenever `buildOpencodePlugin` changes what it emits.
+//
+// OpenCode is the only agent whose integration is generated source rather than a
+// command string. 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: a fix reaches nobody until they re-run `agent setup`.
+//
+// Stamping the generation makes that visible — `agent doctor` compares this number
+// against the file. Nothing auto-rewrites it: 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 parses as `null`, which reads as stale.
+export const OPENCODE_PLUGIN_VERSION = 1;
+export function opencodeConfigDir() {
+    if (process.env.OPENCODE_CONFIG_DIR)
+        return process.env.OPENCODE_CONFIG_DIR;
+    if (process.env.XDG_CONFIG_HOME)
+        return join(process.env.XDG_CONFIG_HOME, "opencode");
+    return join(homedir(), ".config", "opencode");
+}
+export function opencodePluginPath() {
+    return join(opencodeConfigDir(), "plugin", OPENCODE_PLUGIN_FILENAME);
+}
+// 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 function splitCommandLine(command) {
+    return (command.match(/"[^"]*"|\S+/g) ?? []).map((part) => part.startsWith('"') && part.endsWith('"') ? part.slice(1, -1) : part);
+}
+// The plugin source, with this machine's configuration baked into one line.
+// Generated rather than shipped 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 function buildOpencodePlugin(config) {
+    return `// Generated by 'clocktopus agent setup'. Edits will be overwritten.
+${VERSION_MARKER}${OPENCODE_PLUGIN_VERSION}
+//
+// Reports what OpenCode sessions cost to Clocktopus. Two channels, because spend and
+// repository context come from different places and neither is much use alone:
+//
+//   spend    POSTed straight to the receiver as OTel GenAI spans, because it happens
+//            per assistant message and spawning a process each time would be absurd.
+//   context  handed to 'clocktopus agent hook', which already resolves git remotes,
+//            diffs a session's commit range and sweeps dead sessions.
+//
+// Nothing a person wrote is read: not the prompt, not the reply, not tool output.
+import { spawn } from "node:child_process";
+
+${CONFIG_MARKER}${JSON.stringify(config)};
+
+const REQUEST_TIMEOUT_MS = 4000;
+
+/** ms since epoch -> the nanosecond string OTLP expects. */
+const nano = (ms) => \`\${Math.round(ms)}000000\`;
+
+const attr = (key, value) =>
+  typeof value === "number"
+    ? { key, value: { doubleValue: value } }
+    : { key, value: { stringValue: String(value) } };
+
+function spans(message, version) {
+  const started = message.time.created;
+  const ended = message.time.completed ?? started;
+  const shared = [
+    attr("gen_ai.client.session_id", message.sessionID),
+    attr("gen_ai.client.name", "opencode"),
+  ];
+
+  return [
+    {
+      // Carries the turn's duration and nothing else. Clocktopus takes active time from
+      // this span alone, so one per assistant message is what makes the total "time the
+      // agent was working" rather than "time the window was open".
+      name: "gen_ai.client.session",
+      startTimeUnixNano: nano(started),
+      endTimeUnixNano: nano(ended),
+      attributes: shared,
+    },
+    {
+      name: "gen_ai.client.generation",
+      startTimeUnixNano: nano(started),
+      endTimeUnixNano: nano(ended),
+      attributes: [
+        ...shared,
+        attr("gen_ai.request.model", message.modelID),
+        attr("gen_ai.provider.name", message.providerID),
+        // OpenCode reports input already net of the cached prefix, so these buckets add up
+        // rather than overlap — the opposite of Codex, which reports input inclusive.
+        attr("gen_ai.usage.input_tokens", message.tokens.input),
+        // Reasoning tokens are output tokens that were not shown. OpenCode reports them
+        // separately and Clocktopus has no bucket for them, so they are folded in: its own
+        // totals treat them this way and it prices them at the output rate, so leaving them
+        // out would under-report tokens against a cost that already includes them.
+        attr(
+          "gen_ai.usage.output_tokens",
+          message.tokens.output + (message.tokens.reasoning ?? 0),
+        ),
+        attr("gen_ai.usage.cache_read_input_tokens", message.tokens.cache.read),
+        attr(
+          "gen_ai.usage.cache_creation_input_tokens",
+          message.tokens.cache.write,
+        ),
+        // Priced by OpenCode from the models.dev rate card, so Clocktopus records it as an
+        // estimate, never as a settled bill.
+        attr("gen_ai.usage.cost", message.cost),
+      ],
+    },
+  ];
+}
+
+async function report(message, version) {
+  const body = {
+    resourceSpans: [
+      {
+        resource: {
+          attributes: [
+            attr("service.name", "opencode"),
+            ...(version ? [attr("service.version", version)] : []),
+          ],
+        },
+        scopeSpans: [
+          {
+            scope: { name: "clocktopus.opencode", version: "1" },
+            spans: spans(message, version),
+          },
+        ],
+      },
+    ],
+  };
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    await fetch(\`\${CLOCKTOPUS.endpoint.replace(/\\/$/, "")}/v1/traces\`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: \`Bearer \${CLOCKTOPUS.token}\`,
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } catch {
+    // Telemetry must never break the session it measures.
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Hands a session event to the CLI, which owns all the git logic. */
+function notify(event, sessionID, cwd) {
+  try {
+    const [command, ...args] = CLOCKTOPUS.hookArgv;
+    const child = spawn(command, args, {
+      detached: true,
+      stdio: ["pipe", "ignore", "ignore"],
+    });
+    child.unref();
+    child.stdin.on("error", () => {});
+    child.stdin.end(
+      JSON.stringify({
+        session_id: sessionID,
+        hook_event_name: event,
+        cwd,
+      }),
+    );
+  } catch {
+    // Same contract as everything else here: fail silently.
+  }
+}
+
+export const ClocktopusPlugin = async ({ directory, worktree }) => {
+  const root = worktree || directory;
+  let version = null;
+
+  return {
+    event: async ({ event }) => {
+      if (event.type === "session.created") {
+        version = event.properties.info?.version ?? version;
+        notify("SessionStart", event.properties.sessionID, root);
+        return;
+      }
+
+      // OpenCode has no "session ended" event — 'idle' is what it emits when the agent
+      // stops and waits for a human. Treating that as the end keeps the session's end time
+      // tracking the last moment it was busy, which is the bound commit attribution needs;
+      // re-sending on a later turn is harmless, since the receiver merges.
+      if (event.type === "session.idle") {
+        notify("SessionEnd", event.properties.sessionID, root);
+        return;
+      }
+
+      if (event.type === "message.updated") {
+        const message = event.properties.info;
+        // Assistant messages only, and only once finished — an in-flight message is
+        // republished on every token, with counts that are not final.
+        if (message?.role !== "assistant" || !message.time?.completed) return;
+        await report(message, version);
+      }
+    },
+  };
+};
+`;
+}
+export function readOpencodePlugin(path = opencodePluginPath()) {
+    if (!existsSync(path)) {
+        return { path, exists: false, modifiedAt: null, config: null, version: null };
+    }
+    const modifiedAt = statSync(path).mtime;
+    let config = null;
+    let version = null;
+    try {
+        const lines = readFileSync(path, "utf8").split("\n");
+        const stamp = lines.find((candidate) => candidate.startsWith(VERSION_MARKER));
+        if (stamp) {
+            const parsedVersion = Number.parseInt(stamp.slice(VERSION_MARKER.length).trim(), 10);
+            if (Number.isFinite(parsedVersion))
+                version = parsedVersion;
+        }
+        const line = lines.find((candidate) => candidate.startsWith(CONFIG_MARKER));
+        if (line) {
+            const parsed = JSON.parse(line.slice(CONFIG_MARKER.length).replace(/;\s*$/, ""));
+            if (parsed &&
+                typeof parsed === "object" &&
+                typeof parsed.token === "string" &&
+                typeof parsed.endpoint === "string" &&
+                Array.isArray(parsed.hookArgv)) {
+                config = parsed;
+            }
+        }
+    }
+    catch {
+        // A plugin we cannot read the configuration out of is reported as unconfigured,
+        // which sends the user to `setup` — the right answer whether it was hand-edited or
+        // written by a version that has since changed shape.
+    }
+    return { path, exists: true, modifiedAt, config, version };
+}
+export function writeOpencodePlugin(source, path = opencodePluginPath()) {
+    mkdirSync(dirname(path), { recursive: true });
+    let backupPath = null;
+    if (existsSync(path)) {
+        backupPath = `${path}.clocktopus-backup`;
+        copyFileSync(path, backupPath);
+    }
+    // Rename rather than write in place: OpenCode loads every file in this directory at
+    // startup, and a half-written one would be a syntax error that takes the whole
+    // plugin system down with it.
+    const temporaryPath = `${path}.clocktopus-tmp`;
+    writeFileSync(temporaryPath, source, { encoding: "utf8", mode: 0o600 });
+    renameSync(temporaryPath, path);
+    return { backupPath };
+}
+export function removeOpencodePlugin(path = opencodePluginPath()) {
+    if (!existsSync(path))
+        return false;
+    rmSync(path, { force: true });
+    return true;
+}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=opencode-config.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"opencode-config.test.d.ts","sourceRoot":"","sources":["../../../src/lib/opencode-config.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,140 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { buildOpencodePlugin, OPENCODE_PLUGIN_VERSION, readOpencodePlugin, removeOpencodePlugin, splitCommandLine, writeOpencodePlugin, } from "./opencode-config";
+/**
+ * OpenCode's integration is a JavaScript file we generate and drop into the
+ * user's config directory, which makes two things worth testing that the
+ * other agents do not need: that the file we write is syntactically valid —
+ * OpenCode loads every plugin at startup, so a broken one takes its whole
+ * plugin system down — and that the configuration baked into it survives a
+ * round trip, since that file is also where the ingest token lives.
+ */
+const INSTALL = {
+    endpoint: "https://otel.example.com",
+    token: "ctop_agt_testtoken",
+    hookArgv: ["/usr/bin/node", "/opt/clocktopus/cli.js", "agent", "hook"],
+};
+let dir;
+let pluginPath;
+beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "clocktopus-opencode-"));
+    pluginPath = join(dir, "plugin", "clocktopus.js");
+});
+afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+});
+describe("splitCommandLine", () => {
+    it("keeps a quoted path with spaces in one piece", () => {
+        // The failure this prevents is silent: the plugin spawns argv directly,
+        // so a path torn in two at a space produces a command that does not
+        // exist, and the hook simply never runs.
+        expect(splitCommandLine('"/opt/my node/bin/node" /opt/cli.js agent hook')).toEqual(["/opt/my node/bin/node", "/opt/cli.js", "agent", "hook"]);
+    });
+    it("handles the ordinary unquoted case", () => {
+        expect(splitCommandLine("clocktopus agent hook --provider opencode")).toEqual(["clocktopus", "agent", "hook", "--provider", "opencode"]);
+    });
+});
+describe("the generated plugin", () => {
+    it("is valid JavaScript", async () => {
+        const source = buildOpencodePlugin(INSTALL);
+        const encoded = `data:text/javascript;base64,${Buffer.from(source).toString("base64")}`;
+        // Imported rather than merely parsed: OpenCode loads this file into its
+        // own process, so a syntax error here is not our bug alone — it breaks
+        // every other plugin the user has.
+        const module = await import(encoded);
+        expect(typeof module.ClocktopusPlugin).toBe("function");
+    });
+    it("exports a plugin that registers an event handler", async () => {
+        const source = buildOpencodePlugin(INSTALL);
+        const encoded = `data:text/javascript;base64,${Buffer.from(source).toString("base64")}`;
+        const { ClocktopusPlugin } = (await import(encoded));
+        const hooks = await ClocktopusPlugin({
+            directory: "/repo",
+            worktree: "/repo",
+        });
+        expect(typeof hooks.event).toBe("function");
+    });
+    it("sends counts and identifiers, and nothing a person wrote", () => {
+        const source = buildOpencodePlugin(INSTALL);
+        // OpenCode hands the plugin whole messages, so what it chooses *not* to
+        // read is the entire privacy story. These are the fields on
+        // `AssistantMessage` and its parts that carry content.
+        for (const forbidden of [
+            "message.parts",
+            "\\.text",
+            "message.prompt",
+            "message.summary",
+        ]) {
+            expect(source).not.toMatch(new RegExp(forbidden));
+        }
+    });
+    it("round-trips its configuration back out of the file", () => {
+        writeOpencodePlugin(buildOpencodePlugin(INSTALL), pluginPath);
+        const read = readOpencodePlugin(pluginPath);
+        expect(read.exists).toBe(true);
+        // This is how `doctor`, `status` and the hook find the token: there is
+        // nowhere else it is written.
+        expect(read.config).toEqual(INSTALL);
+    });
+    it("stamps the generation that wrote it", () => {
+        // Unlike the hook agents, this file does not follow the CLI: it stays as
+        // written until `setup` runs again. The stamp is the only way `doctor`
+        // can tell a plugin that predates a fix from one that has it.
+        writeOpencodePlugin(buildOpencodePlugin(INSTALL), pluginPath);
+        expect(readOpencodePlugin(pluginPath).version).toBe(OPENCODE_PLUGIN_VERSION);
+    });
+    it("writes the file readable only by its owner", () => {
+        writeOpencodePlugin(buildOpencodePlugin(INSTALL), pluginPath);
+        // The ingest token is in there in plaintext.
+        expect(readFileSync(pluginPath, "utf8")).toContain(INSTALL.token);
+    });
+    it("backs up whatever was there before overwriting", () => {
+        writeOpencodePlugin("// something the user wrote\n", pluginPath);
+        const { backupPath } = writeOpencodePlugin(buildOpencodePlugin(INSTALL), pluginPath);
+        expect(backupPath).toBe(`${pluginPath}.clocktopus-backup`);
+        expect(readFileSync(backupPath, "utf8")).toBe("// something the user wrote\n");
+    });
+});
+describe("reading a plugin that is not ours to read", () => {
+    it("reports a hand-edited plugin as unconfigured rather than guessing", () => {
+        writeOpencodePlugin("export const Whatever = async () => ({});\n", pluginPath);
+        const read = readOpencodePlugin(pluginPath);
+        // The file exists but tells us nothing, so `setup` is the honest next
+        // step — reporting it as configured would leave the user staring at a
+        // pipeline that cannot possibly deliver.
+        expect(read.exists).toBe(true);
+        expect(read.config).toBeNull();
+    });
+    it("reads a plugin from before stamping existed as unstamped", () => {
+        // Every plugin installed before the stamp shipped lands here. `null`
+        // means "not the current generation", which is exactly right for one
+        // written by a CLI that had no generations at all.
+        const unstamped = buildOpencodePlugin(INSTALL)
+            .split("\n")
+            .filter((line) => !line.startsWith("// clocktopus-plugin-version:"))
+            .join("\n");
+        writeOpencodePlugin(unstamped, pluginPath);
+        const read = readOpencodePlugin(pluginPath);
+        // Still configured — it reports fine, it is just behind.
+        expect(read.config).toEqual(INSTALL);
+        expect(read.version).toBeNull();
+    });
+    it("reports nothing at all when the file is absent", () => {
+        expect(readOpencodePlugin(pluginPath)).toMatchObject({
+            exists: false,
+            config: null,
+        });
+    });
+});
+describe("removing the plugin", () => {
+    it("deletes the file and says so", () => {
+        writeOpencodePlugin(buildOpencodePlugin(INSTALL), pluginPath);
+        expect(removeOpencodePlugin(pluginPath)).toBe(true);
+        expect(readOpencodePlugin(pluginPath).exists).toBe(false);
+    });
+    it("is a no-op when there is nothing installed", () => {
+        expect(removeOpencodePlugin(pluginPath)).toBe(false);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blastin-dev/clocktopus-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "bin": {
     "clocktopus": "./dist/bin/clocktopus.js"
@@ -12,6 +12,7 @@
     "commander": "^13.0.0",
     "conf": "^13.0.0",
     "date-fns": "4.1.0",
+    "smol-toml": "^1.8.0",
     "zod": "4.4.3"
   },
   "devDependencies": {