onepatch 0.2.0 → 0.3.0

package/README.md

@@ -31,6 +31,10 @@ onepatch whoami
 
 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.
 
+## 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.3.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,7 @@ import { decodeJwtClaims, getValidAccessToken } from "./auth";
 import { OnepatchClient } from "./client";
 import { fetchBootstrap, resolveApiUrl } from "./config";
 import { deleteCredentials, loadCredentials, saveCredentials } from "./credentials";
+import { currentVersion, maybeAutoUpdate, runUpdate } from "./update";
 import { pollForDeviceToken, startDeviceAuthorization } from "./workos";
 
 const USAGE = `onepatch — OnePatch from the terminal
@@ -29,13 +30,16 @@ Usage:
   onepatch incidents read <num> [--raw]   Read one incident by number
 
   onepatch tools                      List the server's MCP tools
+  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,15 +132,28 @@ 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 },
 		},
 	});
 
+	if (flags.version) {
+		console.log(currentVersion());
+		return;
+	}
+
 	const [noun, verb, ...rest] = positionals;
 	if (flags.help || !noun) {
 		console.log(USAGE);
 		return;
 	}
 
+	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);

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