onepatch 0.2.0 → 0.4.0

package/README.md

@@ -27,10 +27,20 @@ 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.
+
 ## Programmatic use
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onepatch",
-  "version": "0.2.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,9 @@ 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";
 
 const USAGE = `onepatch — OnePatch from the terminal
@@ -29,13 +32,21 @@ 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:
   --api <url>    Deployment base URL (default: $ONEPATCH_API_URL or https://app.onepatch.dev)
   --json         Print raw MCP content blocks as JSON
+  --version      Print the CLI version
   -h, --help     Show this help
 
-Pass "-" for <sql> or <text> to read it from stdin.`;
+Pass "-" for <sql> or <text> to read it from stdin.
+The CLI keeps itself current in the background; ONEPATCH_NO_UPDATE=1 disables that.`;
 
 function fail(message: string): never {
 	console.error(message);
@@ -128,18 +139,40 @@ async function main(): Promise<void> {
 			"waiting-on": { type: "string" },
 			limit: { type: "string" },
 			raw: { type: "boolean", default: false },
+			version: { type: "boolean", default: false },
+			// 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" },
 		},
 	});
 
+	if (flags.version) {
+		console.log(currentVersion());
+		return;
+	}
+
 	const [noun, verb, ...rest] = positionals;
 	if (flags.help || !noun) {
 		console.log(USAGE);
 		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();
+
 	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/credentials.ts

@@ -16,11 +16,21 @@ export type Credentials = {
 
 type CredentialsFile = Record<string, Credentials>;
 
-export function credentialsPath(): string {
-	const dir =
+export function configDir(): string {
+	return (
 		process.env.ONEPATCH_CONFIG_DIR ??
-		join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "onepatch");
-	return join(dir, "credentials.json");
+		join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "onepatch")
+	);
+}
+
+export function ensureConfigDir(): string {
+	const dir = configDir();
+	mkdirSync(dir, { recursive: true, mode: 0o700 });
+	return dir;
+}
+
+export function credentialsPath(): string {
+	return join(configDir(), "credentials.json");
 }
 
 function readFile(): CredentialsFile {
@@ -37,8 +47,7 @@ export function loadCredentials(api: string): Credentials | null {
 
 export function saveCredentials(api: string, creds: Credentials): void {
 	const path = credentialsPath();
-	const dir = join(path, "..");
-	mkdirSync(dir, { recursive: true, mode: 0o700 });
+	ensureConfigDir();
 	const all = readFile();
 	all[api] = creds;
 	writeFileSync(path, `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });

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

package/src/update.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, test } from "bun:test";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+	CHECK_INTERVAL_MS,
+	compareVersions,
+	decideUpdateAction,
+	detectInstallKind,
+	fetchLatestVersion,
+	INSTALL_RETRY_MS,
+	installCommand,
+} from "./update";
+
+describe("compareVersions", () => {
+	test("orders plain versions", () => {
+		expect(compareVersions("0.2.0", "0.3.0")).toBeLessThan(0);
+		expect(compareVersions("0.3.0", "0.2.9")).toBeGreaterThan(0);
+		expect(compareVersions("1.0.0", "0.99.99")).toBeGreaterThan(0);
+		expect(compareVersions("0.2.0", "0.2.0")).toBe(0);
+	});
+
+	test("compares numerically, not lexically", () => {
+		expect(compareVersions("0.10.0", "0.9.0")).toBeGreaterThan(0);
+	});
+
+	test("prerelease sorts below its release", () => {
+		expect(compareVersions("1.0.0-beta.1", "1.0.0")).toBeLessThan(0);
+		expect(compareVersions("1.0.0", "1.0.0-rc.2")).toBeGreaterThan(0);
+	});
+
+	test("tolerates short versions", () => {
+		expect(compareVersions("1.0", "1.0.0")).toBe(0);
+		expect(compareVersions("1", "1.0.1")).toBeLessThan(0);
+	});
+});
+
+describe("decideUpdateAction", () => {
+	const now = 1_700_000_000_000;
+
+	test("empty state asks for a background check", () => {
+		expect(decideUpdateAction({}, "0.2.0", now)).toEqual({ kind: "check" });
+	});
+
+	test("fresh state with no newer version does nothing", () => {
+		expect(decideUpdateAction({ checkedAt: now - 1000, latest: "0.2.0" }, "0.2.0", now)).toEqual({
+			kind: "none",
+		});
+	});
+
+	test("stale state asks for a background check", () => {
+		expect(
+			decideUpdateAction({ checkedAt: now - CHECK_INTERVAL_MS - 1, latest: "0.2.0" }, "0.2.0", now),
+		).toEqual({ kind: "check" });
+	});
+
+	test("known newer version installs", () => {
+		expect(decideUpdateAction({ checkedAt: now, latest: "0.3.0" }, "0.2.0", now)).toEqual({
+			kind: "install",
+			latest: "0.3.0",
+		});
+	});
+
+	test("an in-flight install suppresses re-spawning", () => {
+		expect(
+			decideUpdateAction(
+				{ checkedAt: now, latest: "0.3.0", installStartedAt: now - 1000 },
+				"0.2.0",
+				now,
+			),
+		).toEqual({ kind: "none" });
+	});
+
+	test("a failed install retries after the guard window", () => {
+		expect(
+			decideUpdateAction(
+				{ checkedAt: now, latest: "0.3.0", installStartedAt: now - INSTALL_RETRY_MS - 1 },
+				"0.2.0",
+				now,
+			),
+		).toEqual({ kind: "install", latest: "0.3.0" });
+	});
+
+	test("a cached latest older than current never installs", () => {
+		expect(decideUpdateAction({ checkedAt: now, latest: "0.1.0" }, "0.2.0", now)).toEqual({
+			kind: "none",
+		});
+	});
+});
+
+describe("detectInstallKind", () => {
+	test("bun global install", () => {
+		expect(
+			detectInstallKind(join(homedir(), ".bun", "install", "global", "node_modules", "onepatch")),
+		).toBe("bun");
+	});
+
+	test("npm global install", () => {
+		expect(detectInstallKind("/usr/local/lib/node_modules/onepatch")).toBe("npm");
+	});
+
+	test("source checkout is not updatable", () => {
+		expect(detectInstallKind("/Users/someone/dev/onepatch-cli")).toBeNull();
+	});
+});
+
+describe("installCommand", () => {
+	test("pins the discovered version, not the latest tag", () => {
+		expect(installCommand("bun", "0.3.0")).toEqual(["bun", "add", "-g", "onepatch@0.3.0"]);
+		expect(installCommand("npm", "0.3.0")).toEqual(["npm", "install", "-g", "onepatch@0.3.0"]);
+	});
+});
+
+describe("fetchLatestVersion", () => {
+	test("reads the version from the registry manifest", async () => {
+		const fake = (async () => Response.json({ version: "0.4.2" })) as unknown as typeof fetch;
+		expect(await fetchLatestVersion(fake)).toBe("0.4.2");
+	});
+
+	test("rejects a manifest without a version", async () => {
+		const fake = (async () => Response.json({})) as unknown as typeof fetch;
+		await expect(fetchLatestVersion(fake)).rejects.toThrow("without a version");
+	});
+
+	test("rejects a non-2xx answer", async () => {
+		const fake = (async () => new Response("nope", { status: 503 })) as unknown as typeof fetch;
+		await expect(fetchLatestVersion(fake)).rejects.toThrow("503");
+	});
+});

package/src/update.ts

@@ -0,0 +1,187 @@
+// Self-update. The rule that shapes everything here: the command the user
+// actually typed never waits on update machinery. Each invocation reads one
+// small cached JSON file; a stale cache spawns a detached background process
+// to refresh it from the npm registry, and a cache that already names a newer
+// version spawns a detached reinstall via whichever package manager owns this
+// copy. Either way the foreground command proceeds immediately, and the next
+// invocation runs the new code.
+import { readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, sep } from "node:path";
+import { configDir, ensureConfigDir } from "./credentials";
+
+export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+// A spawned install normally lands in seconds; this only bounds how long a
+// *failed* install suppresses retries (and dogpiles from parallel invocations).
+export const INSTALL_RETRY_MS = 15 * 60 * 1000;
+
+const packageRoot = (() => {
+	// The bin shim is a symlink into the installed package; resolve it so the
+	// path we inspect is where the package physically lives.
+	const raw = join(import.meta.dir, "..");
+	try {
+		return realpathSync(raw);
+	} catch {
+		return raw;
+	}
+})();
+
+export function currentVersion(): string {
+	const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")) as {
+		version?: unknown;
+	};
+	return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+}
+
+// Plain x.y.z compare; a prerelease suffix sorts below its release.
+export function compareVersions(a: string, b: string): number {
+	const parse = (v: string) => {
+		const [main = "", pre] = v.split("-", 2);
+		const nums = main.split(".").map((n) => Number.parseInt(n, 10) || 0);
+		while (nums.length < 3) nums.push(0);
+		return { nums, pre };
+	};
+	const pa = parse(a);
+	const pb = parse(b);
+	for (let i = 0; i < 3; i++) {
+		const d = (pa.nums[i] ?? 0) - (pb.nums[i] ?? 0);
+		if (d !== 0) return d < 0 ? -1 : 1;
+	}
+	if (pa.pre === pb.pre) return 0;
+	if (pa.pre === undefined) return 1;
+	if (pb.pre === undefined) return -1;
+	return pa.pre < pb.pre ? -1 : 1;
+}
+
+export type InstallKind = "bun" | "npm";
+
+// Which package manager owns this copy — decided from where the package
+// physically lives, because that's also the only place the answer is honest.
+// null means a source checkout (dev), where auto-update must stay away.
+export function detectInstallKind(root: string = packageRoot): InstallKind | null {
+	const bunInstall = process.env.BUN_INSTALL ?? join(homedir(), ".bun");
+	if (root.startsWith(bunInstall + sep) || root.split(sep).includes(".bun")) return "bun";
+	if (root.split(sep).includes("node_modules")) return "npm";
+	return null;
+}
+
+export function installCommand(kind: InstallKind, version: string): string[] {
+	return kind === "bun"
+		? ["bun", "add", "-g", `onepatch@${version}`]
+		: ["npm", "install", "-g", `onepatch@${version}`];
+}
+
+export type UpdateState = {
+	checkedAt?: number;
+	latest?: string;
+	installStartedAt?: number;
+};
+
+export function updateStatePath(): string {
+	return join(configDir(), "update-check.json");
+}
+
+export function readUpdateState(): UpdateState {
+	try {
+		return JSON.parse(readFileSync(updateStatePath(), "utf8")) as UpdateState;
+	} catch {
+		return {};
+	}
+}
+
+export function writeUpdateState(state: UpdateState): void {
+	ensureConfigDir();
+	writeFileSync(updateStatePath(), `${JSON.stringify(state)}\n`);
+}
+
+export type UpdateAction =
+	| { kind: "install"; latest: string }
+	| { kind: "check" }
+	| { kind: "none" };
+
+export function decideUpdateAction(state: UpdateState, current: string, now: number): UpdateAction {
+	if (state.latest && compareVersions(state.latest, current) > 0) {
+		if (state.installStartedAt !== undefined && now - state.installStartedAt < INSTALL_RETRY_MS) {
+			return { kind: "none" };
+		}
+		return { kind: "install", latest: state.latest };
+	}
+	if (state.checkedAt === undefined || now - state.checkedAt > CHECK_INTERVAL_MS) {
+		return { kind: "check" };
+	}
+	return { kind: "none" };
+}
+
+export async function fetchLatestVersion(fetchImpl: typeof fetch = fetch): Promise<string> {
+	const res = await fetchImpl("https://registry.npmjs.org/onepatch/latest", {
+		headers: { accept: "application/json" },
+		signal: AbortSignal.timeout(10_000),
+	});
+	if (!res.ok) throw new Error(`npm registry answered ${res.status} for onepatch@latest`);
+	const doc = (await res.json()) as { version?: unknown };
+	if (typeof doc.version !== "string") {
+		throw new Error("npm registry returned a manifest without a version");
+	}
+	return doc.version;
+}
+
+function spawnDetached(cmd: string[]): void {
+	Bun.spawn({ cmd, stdin: "ignore", stdout: "ignore", stderr: "ignore" }).unref();
+}
+
+// Called on every ordinary invocation. Must never throw, never block, never
+// touch the network in-process.
+export function maybeAutoUpdate(): void {
+	try {
+		if (process.env.ONEPATCH_NO_UPDATE) return;
+		const kind = detectInstallKind();
+		if (kind === null) return;
+		const state = readUpdateState();
+		const action = decideUpdateAction(state, currentVersion(), Date.now());
+		if (action.kind === "install") {
+			// Stamp before spawning so parallel invocations don't dogpile.
+			writeUpdateState({ ...state, installStartedAt: Date.now() });
+			spawnDetached(installCommand(kind, action.latest));
+			console.error(
+				`onepatch ${currentVersion()} → ${action.latest} is installing in the background ` +
+					"(ONEPATCH_NO_UPDATE=1 disables this).",
+			);
+		} else if (action.kind === "check") {
+			// Refresh the cache off-process: `onepatch update --check` fetches the
+			// registry and writes the state file, costing this invocation nothing.
+			spawnDetached([process.execPath, join(packageRoot, "src", "cli.ts"), "update", "--check"]);
+		}
+	} catch {
+		// Auto-update is strictly best-effort; the user's command always wins.
+	}
+}
+
+// The explicit `onepatch update` command (and its hidden `--check` cache-refresh
+// mode used by the background spawn above).
+export async function runUpdate(opts: { checkOnly: boolean }): Promise<void> {
+	const latest = await fetchLatestVersion();
+	const prior = readUpdateState();
+	writeUpdateState({ ...prior, checkedAt: Date.now(), latest });
+	if (opts.checkOnly) return;
+
+	const current = currentVersion();
+	if (compareVersions(latest, current) <= 0) {
+		console.log(`onepatch ${current} is up to date.`);
+		return;
+	}
+	const kind = detectInstallKind();
+	if (kind === null) {
+		console.log(
+			`onepatch ${latest} is available (you have ${current}), but this copy isn't a ` +
+				"global install — update your checkout with git instead.",
+		);
+		return;
+	}
+	const cmd = installCommand(kind, latest);
+	console.log(`Updating onepatch ${current} → ${latest} (${cmd.join(" ")})…`);
+	const proc = Bun.spawn({ cmd, stdin: "ignore", stdout: "inherit", stderr: "inherit" });
+	const code = await proc.exited;
+	if (code !== 0) throw new Error(`${cmd[0]} exited with code ${code}`);
+	writeUpdateState({ checkedAt: Date.now(), latest });
+	console.log(`onepatch ${latest} installed.`);
+}