onepatch 0.3.0 → 0.4.0

package/README.md

@@ -27,10 +27,16 @@ onepatch incidents read <num> [--raw]
 
 onepatch tools     # list the server's MCP tools
 onepatch whoami
+
+onepatch install   # wire this machine's coding agents (Claude Code, Codex, Cursor)
 ```
 
 Pass `-` to read SQL or message text from stdin. `--json` prints raw MCP content blocks. `--api <url>` (or `ONEPATCH_API_URL`) targets a different deployment.
 
+## Coding agents
+
+`onepatch install` detects Claude Code, Codex, and Cursor and wires each one to OnePatch: the OnePatch plugin (a skill that teaches the agent the tools above) plus the remote MCP server, discovered from the deployment's `/.well-known/onepatch-cli`. It is idempotent — re-run it any time to repair or upgrade. Target one agent with `onepatch install <claude|codex|cursor>`, or install by hand from [claude-code-plugin](https://github.com/1patch/claude-code-plugin), [codex-plugin](https://github.com/1patch/codex-plugin), or [cursor-plugin](https://github.com/1patch/cursor-plugin).
+
 ## Updates
 
 The CLI keeps itself current. Once a day, in a detached background process, it asks the npm registry for the latest version; when one exists it reinstalls itself through whichever package manager owns the copy (bun or npm) and prints a one-line notice to stderr. The command you typed is never delayed and never fails because of update machinery. Set `ONEPATCH_NO_UPDATE=1` to disable it, or run `onepatch update` to update on demand. Running from a source checkout never auto-updates.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onepatch",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "OnePatch CLI: query your telemetry, chats, and incidents from a terminal or a coding agent",
   "license": "MIT",
   "homepage": "https://onepatch.dev",

package/src/cli.ts

@@ -6,6 +6,8 @@ import { decodeJwtClaims, getValidAccessToken } from "./auth";
 import { OnepatchClient } from "./client";
 import { fetchBootstrap, resolveApiUrl } from "./config";
 import { deleteCredentials, loadCredentials, saveCredentials } from "./credentials";
+import { runHook } from "./hook";
+import { runInstall } from "./install";
 import { currentVersion, maybeAutoUpdate, runUpdate } from "./update";
 import { pollForDeviceToken, startDeviceAuthorization } from "./workos";
 
@@ -30,6 +32,11 @@ Usage:
   onepatch incidents read <num> [--raw]   Read one incident by number
 
   onepatch tools                      List the server's MCP tools
+  onepatch hook user-prompt-submit    Agent-hook injector (wired by the plugins; reads
+                                      the event on stdin, prints context to inject)
+  onepatch install [claude|codex|cursor]
+                                      Wire this machine's coding agents to OnePatch
+                                      (plugins + MCP server; no argument = all detected)
   onepatch update                     Update the CLI to the latest version now
 
 Global flags:
@@ -136,6 +143,10 @@ async function main(): Promise<void> {
 			// Internal: `onepatch update --check` only refreshes the cached
 			// latest-version state; the background updater spawns it.
 			check: { type: "boolean", default: false },
+			// Internal: `onepatch hook --refresh` repopulates the hook cache; the
+			// foreground hook invocation spawns it detached.
+			refresh: { type: "boolean", default: false },
+			agent: { type: "string" },
 		},
 	});
 
@@ -150,6 +161,10 @@ async function main(): Promise<void> {
 		return;
 	}
 
+	// Hooks fire on every prompt, so they skip even the auto-update file read
+	// and must never write anything but their injection to stdout.
+	if (noun === "hook") return await runHook(resolveApiUrl(flags.api), verb, flags.refresh);
+
 	if (noun === "update") return await runUpdate({ checkOnly: flags.check });
 	// Every other command triggers the zero-cost background update pass.
 	maybeAutoUpdate();
@@ -157,6 +172,7 @@ async function main(): Promise<void> {
 	const api = resolveApiUrl(flags.api);
 
 	if (noun === "login") return await login(api);
+	if (noun === "install") return await runInstall(api, verb);
 	if (noun === "logout") {
 		console.log(deleteCredentials(api) ? `Logged out of ${api}.` : `No credentials for ${api}.`);
 		return;

package/src/hook.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+import { buildContextLine, decideHookAction, HOOK_CACHE_TTL_MS } from "./hook";
+
+// Verbatim shape of the CLI's list_incidents digest.
+const DIGEST = `86 open incidents · newest activity first
+115 closed/folded incidents hidden — scope: "all" lists them
+showing the newest 5 — raise limit for older
+
+INC-193 · unjudged · waiting on time · false alarm · A stale staging deploy failure is still flagged · updated 2026-09-01T15:04Z
+INC-183 · unjudged · waiting on human · Search intermittently degraded · updated 2026-09-01T14:58Z
+INC-192 · P3 · waiting on human · false alarm · Stale boot-time probe · updated 2026-09-01T12:51Z
+incident-3de5a4e4 · no incident document yet (read_chat incident-3de5a4e4) · updated 2026-08-30T05:26Z`;
+
+describe("buildContextLine", () => {
+	test("keeps the count and the two newest INC rows, drops timestamps", () => {
+		const line = buildContextLine(DIGEST);
+		expect(line).toContain("86 open incidents");
+		expect(line).toContain(
+			"INC-193 · unjudged · waiting on time · false alarm · A stale staging deploy failure is still flagged",
+		);
+		expect(line).toContain("INC-183");
+		expect(line).not.toContain("INC-192");
+		expect(line).not.toContain("updated 2026");
+		expect(line).not.toContain("incident-3de5a4e4");
+		expect(line.split("\n")).toHaveLength(1);
+	});
+
+	test("injects nothing when no incidents are open", () => {
+		expect(buildContextLine("0 open incidents · newest activity first\n")).toBe("");
+		expect(buildContextLine("")).toBe("");
+	});
+
+	test("singularizes a lone incident", () => {
+		const line = buildContextLine(
+			"1 open incident · newest\n\nINC-7 · P1 · waiting on agent · x · updated now",
+		);
+		expect(line).toContain("1 open incident —");
+	});
+});
+
+describe("decideHookAction", () => {
+	const now = 1_000_000_000_000;
+
+	test("fresh cache: emit, no refresh", () => {
+		const a = decideHookAction({ fetchedAt: now - 1000, line: "[onepatch] hi" }, now);
+		expect(a).toEqual({ emit: "[onepatch] hi", refresh: false });
+	});
+
+	test("stale cache: emit the stale line AND refresh", () => {
+		const a = decideHookAction({ fetchedAt: now - HOOK_CACHE_TTL_MS - 1, line: "old" }, now);
+		expect(a).toEqual({ emit: "old", refresh: true });
+	});
+
+	test("empty cache: emit nothing, refresh", () => {
+		expect(decideHookAction({}, now)).toEqual({ emit: "", refresh: true });
+	});
+
+	test("refresh already in flight is not re-spawned", () => {
+		const a = decideHookAction({ refreshStartedAt: now - 1000 }, now);
+		expect(a.refresh).toBe(false);
+	});
+
+	test("a stuck refresh stops suppressing after the retry window", () => {
+		const a = decideHookAction({ refreshStartedAt: now - 10 * 60 * 1000 }, now);
+		expect(a.refresh).toBe(true);
+	});
+});

package/src/hook.ts

@@ -0,0 +1,107 @@
+// `onepatch hook user-prompt-submit` — the example agent-hook injector the
+// plugins wire up (UserPromptSubmit in Claude Code and Codex). Whatever this
+// prints to stdout is injected into the agent's context for the turn, so the
+// contract is strict: never block the user's prompt (no foreground network —
+// serve from a cache, refresh detached, like update.ts) and never break it
+// (any failure means print nothing and exit 0).
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { OnepatchClient } from "./client";
+import { configDir, ensureConfigDir, loadCredentials } from "./credentials";
+
+export const HOOK_CACHE_TTL_MS = 5 * 60 * 1000;
+// A refresh normally lands in seconds; this only bounds how long a failed one
+// suppresses retries.
+const REFRESH_RETRY_MS = 2 * 60 * 1000;
+
+export type HookCache = {
+	fetchedAt?: number;
+	refreshStartedAt?: number;
+	// The context line to inject; "" means "healthy, nothing worth injecting".
+	line?: string;
+};
+
+export function hookCachePath(): string {
+	return join(configDir(), "hook-status.json");
+}
+
+export function readHookCache(): HookCache {
+	try {
+		return JSON.parse(readFileSync(hookCachePath(), "utf8")) as HookCache;
+	} catch {
+		return {};
+	}
+}
+
+export function writeHookCache(cache: HookCache): void {
+	ensureConfigDir();
+	writeFileSync(hookCachePath(), `${JSON.stringify(cache)}\n`);
+}
+
+export type HookAction = { emit: string; refresh: boolean };
+
+// Pure decision: what to print and whether to kick a background refresh.
+// A stale line still gets emitted — slightly old incident context beats none,
+// and the refresh makes the next prompt current.
+export function decideHookAction(cache: HookCache, now: number): HookAction {
+	const fresh = cache.fetchedAt !== undefined && now - cache.fetchedAt < HOOK_CACHE_TTL_MS;
+	const refreshInFlight =
+		cache.refreshStartedAt !== undefined && now - cache.refreshStartedAt < REFRESH_RETRY_MS;
+	return { emit: cache.line ?? "", refresh: !fresh && !refreshInFlight };
+}
+
+// Compress the list_incidents digest into one context line. The digest leads
+// with "<N> open incidents · …" and lists one incident per line
+// ("INC-193 · P2 · waiting on human · <title> · updated <ts>"); we keep the
+// count and the two newest rows, minus the updated-at tail.
+export function buildContextLine(incidentsText: string): string {
+	const lines = incidentsText.split("\n").map((l) => l.trim());
+	const rows = lines
+		.filter((l) => /^INC-\d+ · /.test(l))
+		.map((l) => l.replace(/ · updated \S+$/, ""));
+	const count = Number(lines[0]?.match(/^(\d+) open incident/)?.[1] ?? rows.length);
+	if (count === 0 || rows.length === 0) return "";
+	const shown = rows.slice(0, 2).join("; ");
+	return (
+		`[onepatch] ${count} open incident${count === 1 ? "" : "s"} — newest: ${shown}. ` +
+		"Details: the onepatch MCP tools or `onepatch incidents read <num>`."
+	);
+}
+
+async function refreshHookCache(api: string): Promise<void> {
+	const client = new OnepatchClient({ api });
+	try {
+		const text = await client.incidents.list({ scope: "open", limit: 10 });
+		writeHookCache({ fetchedAt: Date.now(), line: buildContextLine(text) });
+	} finally {
+		await client.close();
+	}
+}
+
+export async function runHook(api: string, event: string | undefined, refresh: boolean) {
+	if (refresh) {
+		// Internal mode spawned below; errors just leave the stale cache in place.
+		try {
+			await refreshHookCache(api);
+		} catch {}
+		return;
+	}
+	if (event !== "user-prompt-submit") return; // unknown events inject nothing
+	// Hooks pipe the event payload on stdin; drain it so the agent never sees
+	// a broken pipe, but nothing in it changes what we inject.
+	try {
+		await Bun.stdin.text();
+	} catch {}
+	if (!loadCredentials(api)) return; // not logged in — stay silent
+	const action = decideHookAction(readHookCache(), Date.now());
+	if (action.refresh) {
+		writeHookCache({ ...readHookCache(), refreshStartedAt: Date.now() });
+		Bun.spawn({
+			cmd: [process.execPath, join(import.meta.dir, "cli.ts"), "hook", "--refresh", "--api", api],
+			stdin: "ignore",
+			stdout: "ignore",
+			stderr: "ignore",
+		}).unref();
+	}
+	if (action.emit !== "") console.log(action.emit);
+}

package/src/install.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+import { ensureCodexMcpServer, ensureCursorMcpServer } from "./install";
+
+const URL = "https://app.onepatch.dev/mcp";
+
+describe("ensureCodexMcpServer", () => {
+	test("appends a block to an empty config", () => {
+		const r = ensureCodexMcpServer("", URL);
+		expect(r.changed).toBe(true);
+		expect(r.text).toBe(`[mcp_servers.onepatch]\nurl = "${URL}"\n`);
+	});
+
+	test("separates the block from existing content with a blank line", () => {
+		const r = ensureCodexMcpServer('model = "gpt-5"\n', URL);
+		expect(r.changed).toBe(true);
+		expect(r.text).toBe(`model = "gpt-5"\n\n[mcp_servers.onepatch]\nurl = "${URL}"\n`);
+	});
+
+	test("adds a newline when the file lacks a trailing one", () => {
+		const r = ensureCodexMcpServer('model = "gpt-5"', URL);
+		expect(r.text.startsWith('model = "gpt-5"\n\n[')).toBe(true);
+	});
+
+	test("is idempotent", () => {
+		const once = ensureCodexMcpServer("", URL);
+		const twice = ensureCodexMcpServer(once.text, URL);
+		expect(twice.changed).toBe(false);
+		expect(twice.text).toBe(once.text);
+	});
+
+	test("respects an existing block even with different settings", () => {
+		const existing = '[mcp_servers.onepatch]\nurl = "https://elsewhere.example/mcp"\n';
+		expect(ensureCodexMcpServer(existing, URL).changed).toBe(false);
+	});
+
+	test("does not match other servers or commented blocks", () => {
+		const other = '[mcp_servers.other]\nurl = "x"\n# [mcp_servers.onepatch] disabled\n';
+		expect(ensureCodexMcpServer(other, URL).changed).toBe(true);
+	});
+});
+
+describe("ensureCursorMcpServer", () => {
+	test("creates the document when the file is missing", () => {
+		const r = ensureCursorMcpServer(null, URL);
+		expect(r.changed).toBe(true);
+		expect(JSON.parse(r.text)).toEqual({ mcpServers: { onepatch: { url: URL } } });
+	});
+
+	test("preserves existing servers and unknown top-level keys", () => {
+		const existing = JSON.stringify({ mcpServers: { foo: { command: "foo" } }, other: 1 });
+		const r = ensureCursorMcpServer(existing, URL);
+		expect(r.changed).toBe(true);
+		expect(JSON.parse(r.text)).toEqual({
+			mcpServers: { foo: { command: "foo" }, onepatch: { url: URL } },
+			other: 1,
+		});
+	});
+
+	test("is idempotent, even against a user-customized entry", () => {
+		const existing = JSON.stringify({ mcpServers: { onepatch: { url: "https://custom/mcp" } } });
+		expect(ensureCursorMcpServer(existing, URL).changed).toBe(false);
+	});
+
+	test("refuses to clobber an unparseable file", () => {
+		expect(() => ensureCursorMcpServer("{not json", URL)).toThrow(/not valid JSON/);
+	});
+});

package/src/install.ts

@@ -0,0 +1,150 @@
+// `onepatch install [claude|codex|cursor]` — wire this machine's coding
+// agents to OnePatch. The plugins themselves are thin (skills + MCP pointers,
+// published from plugins/ in this repo); this command only does the local
+// wiring each agent needs, and every step is idempotent so re-running is
+// always repair, never damage.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fetchBootstrap } from "./config";
+
+export const AGENTS = ["claude", "codex", "cursor"] as const;
+export type AgentName = (typeof AGENTS)[number];
+
+const CLAUDE_MARKETPLACE_REPO = "1patch/claude-code-plugin";
+const CODEX_MARKETPLACE_REPO = "1patch/codex-plugin";
+const CURSOR_PLUGIN_URL = "https://github.com/1patch/cursor-plugin";
+
+// --- pure decision helpers (unit-tested) ---
+
+// Append an `[mcp_servers.onepatch]` block to Codex's config.toml unless one
+// already exists. A string scan, not a TOML parser: the only claim we make is
+// "a block with this exact header is present", and rewriting a user's config
+// through a parser risks clobbering formatting and comments.
+export function ensureCodexMcpServer(
+	toml: string,
+	mcpUrl: string,
+): { changed: boolean; text: string } {
+	if (/^\s*\[mcp_servers\.onepatch\]/m.test(toml)) return { changed: false, text: toml };
+	const block = `[mcp_servers.onepatch]\nurl = "${mcpUrl}"\n`;
+	const sep = toml === "" || toml.endsWith("\n\n") ? "" : toml.endsWith("\n") ? "\n" : "\n\n";
+	return { changed: true, text: `${toml}${sep}${block}` };
+}
+
+// Merge the onepatch server into Cursor's mcp.json, preserving everything
+// else. `null` means the file doesn't exist yet.
+export function ensureCursorMcpServer(
+	json: string | null,
+	mcpUrl: string,
+): { changed: boolean; text: string } {
+	let doc: { mcpServers?: Record<string, unknown> };
+	try {
+		doc = json === null ? {} : (JSON.parse(json) as typeof doc);
+	} catch {
+		throw new Error("~/.cursor/mcp.json exists but is not valid JSON; fix it and re-run.");
+	}
+	const servers = doc.mcpServers ?? {};
+	if (servers.onepatch !== undefined) return { changed: false, text: json ?? "" };
+	doc.mcpServers = { ...servers, onepatch: { url: mcpUrl } };
+	return { changed: true, text: `${JSON.stringify(doc, null, 2)}\n` };
+}
+
+export function detectAgents(home: string = homedir()): AgentName[] {
+	const found: AgentName[] = [];
+	if (Bun.which("claude")) found.push("claude");
+	if (Bun.which("codex") || existsSync(join(home, ".codex"))) found.push("codex");
+	if (Bun.which("cursor-agent") || existsSync(join(home, ".cursor"))) found.push("cursor");
+	return found;
+}
+
+// --- IO ---
+
+async function run(cmd: string[]): Promise<boolean> {
+	console.log(`  $ ${cmd.join(" ")}`);
+	const proc = Bun.spawn({ cmd, stdin: "ignore", stdout: "inherit", stderr: "inherit" });
+	return (await proc.exited) === 0;
+}
+
+function upsertFile(path: string, next: string): void {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, next);
+}
+
+async function installClaude(): Promise<void> {
+	if (!Bun.which("claude")) {
+		console.log("claude: CLI not on PATH — install Claude Code first, then re-run.");
+		return;
+	}
+	console.log("claude: installing the OnePatch plugin (marketplace + plugin)…");
+	// The marketplace add fails harmlessly if it's already known; the install
+	// refreshes the marketplace itself, so together these double as upgrade.
+	await run(["claude", "plugin", "marketplace", "add", CLAUDE_MARKETPLACE_REPO]);
+	if (await run(["claude", "plugin", "install", "onepatch@onepatch"])) {
+		console.log("claude: done. Authenticate the onepatch MCP server via /mcp on first use.");
+	} else {
+		console.log(
+			`claude: plugin install failed — run \`claude plugin marketplace add ${CLAUDE_MARKETPLACE_REPO}\` and \`claude plugin install onepatch@onepatch\` by hand to see why.`,
+		);
+	}
+}
+
+async function installCodex(mcpUrl: string, home: string): Promise<void> {
+	const configPath = join(home, ".codex", "config.toml");
+	const current = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+	const result = ensureCodexMcpServer(current, mcpUrl);
+	if (result.changed) {
+		upsertFile(configPath, result.text);
+		console.log(`codex: added [mcp_servers.onepatch] to ${configPath}.`);
+	} else {
+		console.log("codex: MCP server already configured.");
+	}
+	if (Bun.which("codex")) {
+		console.log("codex: installing the OnePatch plugin (skills)…");
+		await run(["codex", "plugin", "marketplace", "add", CODEX_MARKETPLACE_REPO]);
+		await run(["codex", "plugin", "install", "onepatch/onepatch"]);
+	}
+	console.log("codex: sign in with `codex mcp login onepatch` on first use.");
+}
+
+async function installCursor(mcpUrl: string, home: string): Promise<void> {
+	const mcpPath = join(home, ".cursor", "mcp.json");
+	const current = existsSync(mcpPath) ? readFileSync(mcpPath, "utf8") : null;
+	const result = ensureCursorMcpServer(current, mcpUrl);
+	if (result.changed) {
+		upsertFile(mcpPath, result.text);
+		console.log(`cursor: added the onepatch MCP server to ${mcpPath}.`);
+	} else {
+		console.log("cursor: MCP server already configured.");
+	}
+	console.log(
+		`cursor: for the skill + rules, run \`/add-plugin ${CURSOR_PLUGIN_URL}\` in Cursor's agent chat, and log in to onepatch under Settings → MCP.`,
+	);
+}
+
+export async function runInstall(api: string, target?: string): Promise<void> {
+	if (target !== undefined && !AGENTS.includes(target as AgentName)) {
+		throw new Error(`unknown agent "${target}" — expected one of: ${AGENTS.join(", ")}`);
+	}
+	// The MCP URL is discovered, not baked in, so self-hosted deployments get
+	// wired to their own endpoint by passing --api (or ONEPATCH_API_URL).
+	let mcpUrl: string;
+	try {
+		mcpUrl = (await fetchBootstrap(api)).mcpUrl;
+	} catch {
+		mcpUrl = `${api}/mcp`;
+	}
+	const targets = target !== undefined ? [target as AgentName] : detectAgents();
+	if (targets.length === 0) {
+		console.log(
+			"No coding agents found (looked for Claude Code, Codex, Cursor). " +
+				"Pass one explicitly: onepatch install <claude|codex|cursor>.",
+		);
+		return;
+	}
+	const home = homedir();
+	for (const agent of targets) {
+		if (agent === "claude") await installClaude();
+		if (agent === "codex") await installCodex(mcpUrl, home);
+		if (agent === "cursor") await installCursor(mcpUrl, home);
+	}
+}