@gajae-gateway/cli 0.1.3 → 0.1.5

package/src/update.ts

@@ -0,0 +1,450 @@
+import {
+	chmod,
+	copyFile,
+	mkdir,
+	mkdtemp,
+	open,
+	readdir,
+	readFile,
+	realpath,
+	rename,
+	rm,
+	stat,
+	writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import pkg from "../package.json";
+import { launchRestartStack } from "./restart-stack";
+
+/**
+ * `gajaeway update`: self-update a binary install from the project's GitHub
+ * releases, the way `gjc update` does for gajae-code. Production hosts run
+ * standalone binaries under launchd/systemd without a source checkout, so the
+ * CLI owns its own upgrade path: compare against the latest release, replace
+ * the installed binaries with a backup, and queue the existing restart-stack
+ * supervisor. A source checkout keeps upgrading through `git` + `bun run
+ * build`; `--bin-dir` covers hosts that drive the update from elsewhere.
+ */
+
+export const UPDATE_USAGE = "usage: gajaeway update [--check] [--force] [--bin-dir DIR] [--no-restart]";
+
+export const DEFAULT_RELEASE_REPO = "Yeachan-Heo/gajae-way";
+const RELEASE_REPO_OVERRIDE_ENV = "GAJAEWAY_UPDATE_REPO";
+/** A fork can point updates at its own releases; the declared upstream stays the default. */
+export function releaseRepo(env: NodeJS.ProcessEnv = process.env): string {
+	const override = env[RELEASE_REPO_OVERRIDE_ENV]?.trim();
+	return override ? override : declaredReleaseRepo();
+}
+
+function declaredReleaseRepo(): string {
+	const url = pkg.repository?.url;
+	const match =
+		typeof url === "string" ? /^git\+https:\/\/github\.com\/([^/\s]+\/[^/\s]+?)\.git$/.exec(url) : undefined;
+	return match ? match[1] : DEFAULT_RELEASE_REPO;
+}
+
+export interface ReleaseAsset {
+	readonly name: string;
+	readonly url: string;
+}
+
+export interface ReleaseInfo {
+	readonly tag: string;
+	readonly assets: readonly ReleaseAsset[];
+}
+
+export interface ParsedUpdateArgs {
+	readonly check: boolean;
+	readonly force: boolean;
+	readonly noRestart: boolean;
+	readonly binDir?: string;
+}
+
+export function parseUpdateArgs(args: readonly string[]): ParsedUpdateArgs {
+	let check = false;
+	let force = false;
+	let noRestart = false;
+	let binDir: string | undefined;
+	for (let i = 0; i < args.length; i++) {
+		const flag = args[i];
+		if (flag === "--check") check = true;
+		else if (flag === "--force") force = true;
+		else if (flag === "--no-restart") noRestart = true;
+		else if (flag === "--bin-dir") {
+			const value = args[++i];
+			if (value === undefined || value.length === 0 || value.startsWith("--"))
+				throw new Error(`${flag} expects a non-empty DIR`);
+			binDir = value;
+		} else throw new Error(`${UPDATE_USAGE} (unknown option: ${flag})`);
+	}
+	return {
+		check,
+		force,
+		noRestart,
+		...(binDir === undefined ? {} : { binDir }),
+	};
+}
+
+/** Release tags are `vX.Y.Z` (optionally with a prerelease); anything else is not comparable. */
+export function releaseVersion(tag: string): string | undefined {
+	const match = /^v?(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?$/.exec(tag.trim());
+	return match ? `${match[1]}.${match[2]}.${match[3]}${match[4] ?? ""}` : undefined;
+}
+
+/** The release workflow publishes one tarball per platform/arch of the whole `dist/`. */
+export function releaseAssetName(platform: NodeJS.Platform = process.platform, arch: string = process.arch): string {
+	return `gajaeway-${platform}-${arch}.tar.gz`;
+}
+
+export function selectReleaseAsset(release: ReleaseInfo, name: string): ReleaseAsset | undefined {
+	return release.assets.find((asset) => asset.name === name);
+}
+
+export function isNewer(current: string, latest: string): boolean {
+	return Bun.semver.order(latest, current) > 0;
+}
+
+/**
+ * Every binary a release tarball can contain, in the order updates report
+ * them. An operator's bin dir may carry only a subset (for example no
+ * Discord/Telegram adapters); the update replaces what is installed plus the
+ * core pair, never adding adapters the host did not choose.
+ */
+export const KNOWN_BINARIES = [
+	"gajaeway",
+	"gajaeway-gateway",
+	"gajaeway-admin",
+	"gajaeway-slack",
+	"gajaeway-discord",
+	"gajaeway-telegram",
+] as const;
+
+export const CORE_BINARIES = ["gajaeway", "gajaeway-gateway"] as const;
+
+/** Compiled binaries are tens of MB; a staged file below this size is a broken extraction. */
+const MIN_BINARY_BYTES = 1_048_576;
+const MAX_ASSET_BYTES = 512 * 1024 * 1024;
+
+const RELEASE_MARKER = ".gajaeway-release";
+const LOCK_FILE = ".gajaeway-update.lock";
+
+export function releaseMarkerPath(binDir: string): string {
+	return join(binDir, RELEASE_MARKER);
+}
+
+export async function readInstalledRelease(binDir: string): Promise<string | undefined> {
+	try {
+		const version = releaseVersion(await readFile(releaseMarkerPath(binDir), "utf8"));
+		return version;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * The bin dir of the running compiled binary. Under `bun packages/cli/src/main.ts`
+ * the executable is the interpreter, not an install, so the caller must pass
+ * `--bin-dir`; a renamed binary directory is adopted as long as the file still
+ * carries a `gajaeway…` name.
+ */
+export async function resolveBinDir(
+	flag: string | undefined,
+	execPath = process.execPath,
+): Promise<string | undefined> {
+	if (flag !== undefined) return flag;
+	const real = await realpath(execPath).catch(() => undefined);
+	if (real === undefined) return undefined;
+	return basename(real).startsWith("gajaeway") ? dirname(real) : undefined;
+}
+
+export interface UpdateResult {
+	readonly current: string;
+	readonly latest: string;
+	readonly tag: string;
+	readonly repo: string;
+	readonly checkedOnly: boolean;
+	readonly upToDate: boolean;
+	readonly installed: readonly string[];
+	readonly backupDir?: string;
+	readonly restartQueued?: string;
+	readonly restartSkipped?: boolean;
+}
+
+export function renderUpdate(result: UpdateResult): string[] {
+	const lines: string[] = [];
+	if (result.upToDate) {
+		lines.push(
+			result.checkedOnly
+				? `up to date: ${result.current} (latest release ${result.tag})`
+				: `already up to date: ${result.current} (latest release ${result.tag}); use --force to reinstall`,
+		);
+		return lines;
+	}
+	if (result.checkedOnly) {
+		lines.push(`update available: ${result.current} → ${result.latest} (release ${result.tag})`);
+		return lines;
+	}
+	lines.push(`updated ${result.current} → ${result.latest} from ${result.repo} (${result.tag})`);
+	lines.push(`installed: ${result.installed.join(", ")}`);
+	if (result.backupDir !== undefined) lines.push(`backup: ${result.backupDir}`);
+	if (result.restartQueued !== undefined)
+		lines.push(`restart: queued ${result.restartQueued} — check with: gajaeway ops restart-stack --status`);
+	else if (result.restartSkipped) lines.push("restart: skipped (--no-restart)");
+	return lines;
+}
+
+export interface RestartQueueReceipt {
+	readonly receiptId: string;
+	readonly supervisorPid: number;
+}
+
+export type ReleaseFetcher = (repo: string) => Promise<ReleaseInfo>;
+export type AssetDownloader = (asset: ReleaseAsset) => Promise<Uint8Array>;
+export type TarballExtractor = (tarball: Uint8Array, intoDir: string) => Promise<void>;
+export type RestartQueuer = (home: string) => Promise<RestartQueueReceipt>;
+
+export interface UpdateDeps {
+	readonly fetchLatestRelease?: ReleaseFetcher;
+	readonly downloadAsset?: AssetDownloader;
+	readonly extractTarball?: TarballExtractor;
+	readonly queueRestart?: RestartQueuer;
+	readonly platform?: NodeJS.Platform;
+	readonly arch?: string;
+	readonly env?: NodeJS.ProcessEnv;
+	readonly execPath?: string;
+	readonly now?: () => number;
+}
+
+export interface RunUpdateOptions {
+	readonly args: ParsedUpdateArgs;
+	readonly home: string;
+	readonly deps?: UpdateDeps;
+}
+
+export async function runUpdate(options: RunUpdateOptions): Promise<UpdateResult> {
+	const deps = options.deps ?? {};
+	const platform = deps.platform ?? process.platform;
+	if (platform !== "darwin" && platform !== "linux")
+		throw new Error(`update supports darwin and linux release assets, not ${platform}`);
+	const repo = releaseRepo(deps.env ?? process.env);
+	const release = await (deps.fetchLatestRelease ?? defaultFetchLatestRelease)(repo);
+	const latest = releaseVersion(release.tag);
+	if (latest === undefined) throw new Error(`latest release tag is not a version: ${release.tag}`);
+	const binDir = await resolveBinDir(options.args.binDir, deps.execPath ?? process.execPath);
+	const current = (binDir === undefined ? undefined : await readInstalledRelease(binDir)) ?? pkg.version;
+	const upToDate = !isNewer(current, latest);
+	if (upToDate && !options.args.force)
+		return { current, latest, tag: release.tag, repo, checkedOnly: options.args.check, upToDate: true, installed: [] };
+	const asset = selectReleaseAsset(release, releaseAssetName(platform, deps.arch ?? process.arch));
+	if (asset === undefined)
+		throw new Error(
+			`release ${release.tag} has no asset ${releaseAssetName(platform, deps.arch ?? process.arch)} (assets: ${
+				release.assets.map((candidate) => candidate.name).join(", ") || "none"
+			})`,
+		);
+	if (options.args.check)
+		return { current, latest, tag: release.tag, repo, checkedOnly: true, upToDate: false, installed: [] };
+	if (binDir === undefined) throw new Error("run the update from a compiled gajaeway binary, or pass --bin-dir DIR");
+
+	const unlock = await acquireUpdateLock(binDir);
+	try {
+		const staged = await stageRelease(asset, deps);
+		const installedNames = await knownBinariesIn(binDir);
+		const toInstall = binariesToInstall(staged.names, installedNames);
+		const missingCore = CORE_BINARIES.filter((name) => !toInstall.includes(name));
+		if (missingCore.length > 0) throw new Error(`release tarball is missing core binaries: ${missingCore.join(", ")}`);
+		await assertStagedBinariesUsable(staged, toInstall);
+
+		const stamp = new Date((deps.now ?? Date.now)()).toISOString().replace(/[-:]/g, "").slice(0, 15);
+		const backupDir = join(binDir, `backup-${current}-${stamp}Z`);
+		await mkdir(backupDir, { recursive: false });
+		for (const name of toInstall) {
+			const target = join(binDir, name);
+			if (await exists(target)) await copyFile(target, join(backupDir, name));
+		}
+		for (const name of toInstall) {
+			const stagedPath = join(staged.dir, name);
+			const tempPath = join(binDir, `.update-${name}`);
+			await copyFile(stagedPath, tempPath);
+			await chmod(tempPath, 0o755);
+			await rename(tempPath, join(binDir, name));
+		}
+		await writeFile(releaseMarkerPath(binDir), `${latest}\n`, "utf8");
+		await rm(staged.dir, { recursive: true, force: true });
+
+		if (options.args.noRestart)
+			return {
+				current,
+				latest,
+				tag: release.tag,
+				repo,
+				checkedOnly: false,
+				upToDate: false,
+				installed: toInstall,
+				backupDir,
+				restartSkipped: true,
+			};
+		const receipt = await (deps.queueRestart ?? defaultQueueRestart)(options.home);
+		return {
+			current,
+			latest,
+			tag: release.tag,
+			repo,
+			checkedOnly: false,
+			upToDate: false,
+			installed: toInstall,
+			backupDir,
+			restartQueued: receipt.receiptId,
+		};
+	} finally {
+		await unlock();
+	}
+}
+
+function binariesToInstall(stagedNames: readonly string[], installedNames: readonly string[]): string[] {
+	const installed = new Set(installedNames);
+	return KNOWN_BINARIES.filter(
+		(name) =>
+			stagedNames.includes(name) && (installed.has(name) || (CORE_BINARIES as readonly string[]).includes(name)),
+	);
+}
+
+async function knownBinariesIn(dir: string): Promise<string[]> {
+	const entries = await readdir(dir).catch(() => [] as string[]);
+	const names = new Set(entries);
+	return KNOWN_BINARIES.filter((name) => names.has(name));
+}
+
+async function assertStagedBinariesUsable(
+	staged: { readonly dir: string; readonly names: readonly string[] },
+	toInstall: readonly string[],
+): Promise<void> {
+	for (const name of toInstall) {
+		const info = await stat(join(staged.dir, name));
+		if (!info.isFile()) throw new Error(`staged ${name} is not a regular file`);
+		if (info.size < MIN_BINARY_BYTES)
+			throw new Error(`staged ${name} is only ${info.size} bytes; refusing a broken extraction`);
+	}
+}
+
+async function exists(path: string): Promise<boolean> {
+	try {
+		await stat(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+interface StagedRelease {
+	readonly dir: string;
+	readonly names: readonly string[];
+}
+
+async function stageRelease(asset: ReleaseAsset, deps: UpdateDeps): Promise<StagedRelease> {
+	const dir = await mkdtemp(join(tmpdir(), "gajaeway-update-"));
+	const tarball = await (deps.downloadAsset ?? defaultDownloadAsset)(asset);
+	await (deps.extractTarball ?? defaultExtractTarball)(tarball, dir);
+	const names = (await readdir(dir)).filter((name) => (KNOWN_BINARIES as readonly string[]).includes(name));
+	return { dir, names };
+}
+
+async function defaultFetchLatestRelease(repo: string): Promise<ReleaseInfo> {
+	const response = await fetch(`https://api.github.com/repos/${repo}/releases/latest`, {
+		headers: { Accept: "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28" },
+	});
+	if (!response.ok) throw new Error(`release lookup failed: HTTP ${response.status} for ${repo}/releases/latest`);
+	const body = (await response.json()) as {
+		tag_name?: unknown;
+		assets?: Array<{ name?: unknown; browser_download_url?: unknown }>;
+	};
+	const tag = typeof body.tag_name === "string" ? body.tag_name : undefined;
+	if (tag === undefined) throw new Error(`latest release of ${repo} has no tag_name`);
+	const assets = (body.assets ?? []).flatMap((asset) =>
+		typeof asset.name === "string" && typeof asset.browser_download_url === "string"
+			? [{ name: asset.name, url: asset.browser_download_url }]
+			: [],
+	);
+	return { tag, assets };
+}
+
+async function defaultDownloadAsset(asset: ReleaseAsset): Promise<Uint8Array> {
+	const response = await fetch(asset.url);
+	if (!response.ok) throw new Error(`download failed: HTTP ${response.status} for ${asset.name}`);
+	const bytes = new Uint8Array(await response.arrayBuffer());
+	if (bytes.byteLength > MAX_ASSET_BYTES)
+		throw new Error(`${asset.name} is ${bytes.byteLength} bytes; refusing anything over ${MAX_ASSET_BYTES}`);
+	return bytes;
+}
+
+async function defaultExtractTarball(tarball: Uint8Array, intoDir: string): Promise<void> {
+	const tarballPath = join(intoDir, "release.tar.gz");
+	await writeFile(tarballPath, tarball);
+	const process2 = Bun.spawn(["tar", "-xzf", tarballPath, "-C", intoDir], {
+		stdout: "ignore",
+		stderr: "pipe",
+	});
+	const exitCode = await process2.exited;
+	if (exitCode !== 0) {
+		const detail = await new Response(process2.stderr).text();
+		throw new Error(`extracting ${basename(tarballPath)} failed (tar exit ${exitCode}): ${detail.trim()}`);
+	}
+	await rm(tarballPath, { force: true });
+}
+
+async function defaultQueueRestart(home: string): Promise<RestartQueueReceipt> {
+	const { receipt, supervisorPid } = await launchRestartStack({ home });
+	return { receiptId: receipt.id, supervisorPid };
+}
+
+/**
+ * One update at a time per bin dir. A lock naming a live pid refuses; a lock
+ * naming a dead one is stale and taken over.
+ */
+export async function acquireUpdateLock(binDir: string): Promise<() => Promise<void>> {
+	const lockPath = join(binDir, LOCK_FILE);
+	for (let attempt = 0; attempt < 2; attempt++) {
+		try {
+			const handle = await open(lockPath, "wx");
+			try {
+				await handle.write(`${JSON.stringify({ pid: process.pid, at: new Date().toISOString() })}\n`);
+			} finally {
+				await handle.close();
+			}
+			return async () => {
+				await rm(lockPath, { force: true });
+			};
+		} catch (error) {
+			if (!isFileExistsError(error)) throw error;
+			const holder = await readLockHolder(lockPath);
+			if (holder !== undefined && isProcessAlive(holder)) {
+				throw new Error(`another gajaeway update is running (pid ${holder}); refusing to run concurrently`);
+			}
+			await rm(lockPath, { force: true });
+		}
+	}
+	throw new Error(`could not acquire the update lock at ${lockPath}`);
+}
+
+function isFileExistsError(error: unknown): boolean {
+	return error !== null && typeof error === "object" && (error as { code?: unknown }).code === "EEXIST";
+}
+
+async function readLockHolder(lockPath: string): Promise<number | undefined> {
+	try {
+		const parsed = JSON.parse(await readFile(lockPath, "utf8")) as { pid?: unknown };
+		return typeof parsed.pid === "number" ? parsed.pid : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function isProcessAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return (error as { code?: unknown }).code === "EPERM";
+	}
+}

package/src/upgrade.ts

@@ -0,0 +1,199 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * `gajaeway ops upgrade [--gjc X.Y.Z]`
+ *
+ * Atomically upgrades the gateway's gjc to the pinned version (or an override).
+ * The process:
+ * 1. Verify CI is green (deploy gate)
+ * 2. Stop intake (implicit on restart)
+ * 3. Wait for in-flight turns (bounded)
+ * 4. Back up the DB
+ * 5. Install the pinned gjc into the gateway's own prefix (checksum-verified)
+ * 6. Restart the gateway's broker
+ * 7. ops restart-stack
+ * 8. Verify status (clients current, 0 pending, no held turns)
+ *
+ * Fails closed: leaves old binaries in place on any step.
+ */
+
+export interface UpgradeOptions {
+	readonly home: string;
+	/** Override gjc version; defaults to reading from gateway's package.json */
+	readonly gjcVersion?: string;
+	/** Test seam: function to check CI status */
+	readonly checkCiStatus?: (repo: string) => Promise<boolean>;
+	/** Test seam: function to read gateway pinned gjc version */
+	readonly readPinnedVersion?: (home: string) => Promise<string>;
+}
+
+/** Read the pinned gjc version from the gateway's package.json */
+export async function readGatewayPinnedGjcVersion(home: string): Promise<string> {
+	try {
+		// The gateway package.json should be in the same location as the gateway binary
+		// For now, we'll look in the gajaeway installation
+		const packageJsonPath = join(home, "..", "..", "packages", "gateway", "package.json");
+		const content = await readFile(packageJsonPath, "utf-8");
+		const pkg = JSON.parse(content);
+		const version = pkg.gjc?.version;
+		if (!version || typeof version !== "string") {
+			throw new Error("gjc.version not found in gateway package.json");
+		}
+		return version;
+	} catch (error) {
+		throw new Error(`Failed to read pinned GJC version: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+export interface UpgradeResult {
+	readonly status: "ok" | "failed";
+	readonly detail: string;
+}
+
+/**
+ * Check CI status by running: gh run list -R owner/repo --branch HEAD --limit 1 --json conclusion
+ * Returns true if the latest CI run passed (conclusion: success)
+ */
+async function checkLatestCiStatus(repo: string): Promise<boolean> {
+	try {
+		// Get current git branch
+		const branchProc = Bun.spawnSync(["git", "rev-parse", "--abbrev-ref", "HEAD"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		if (branchProc.exitCode !== 0) {
+			throw new Error("Could not determine current git branch");
+		}
+
+		const branch = branchProc.stdout?.toString().trim();
+		if (!branch) {
+			throw new Error("Empty branch name");
+		}
+
+		// Check CI status for this branch
+		const runProc = Bun.spawnSync(
+			["gh", "run", "list", "-R", repo, "--branch", branch, "--limit", "1", "--json", "conclusion,status"],
+			{
+				stdout: "pipe",
+				stderr: "pipe",
+			},
+		);
+
+		if (runProc.exitCode !== 0) {
+			throw new Error(`gh run list failed: ${runProc.stderr?.toString()}`);
+		}
+
+		const output = runProc.stdout?.toString() || "[]";
+		const runs = JSON.parse(output);
+
+		if (!Array.isArray(runs) || runs.length === 0) {
+			throw new Error("No CI runs found for this branch");
+		}
+
+		const latestRun = runs[0];
+		if (!latestRun.conclusion || !latestRun.status) {
+			throw new Error(`Latest CI run status is incomplete: ${JSON.stringify(latestRun)}`);
+		}
+
+		// conclusion can be: success, failure, neutral, cancelled, skipped, timed_out
+		// status can be: queued, in_progress, completed
+		if (latestRun.status === "in_progress") {
+			throw new Error("CI is currently running; wait for completion");
+		}
+
+		return latestRun.conclusion === "success";
+	} catch (error) {
+		throw new Error(`Failed to check CI status: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+export async function performUpgrade(options: UpgradeOptions): Promise<UpgradeResult> {
+	const readVersion = options.readPinnedVersion || readGatewayPinnedGjcVersion;
+	const targetVersion = options.gjcVersion ?? (await readVersion(options.home));
+
+	try {
+		// 1. Check CI status (deploy gate)
+		const checkCi = options.checkCiStatus || checkLatestCiStatus;
+		let ciPassed = false;
+		try {
+			ciPassed = await checkCi("Yeachan-Heo/gajae-way");
+		} catch (ciError) {
+			const ciDetail = ciError instanceof Error ? ciError.message : String(ciError);
+			return { status: "failed", detail: `CI status check failed: ${ciDetail}` };
+		}
+
+		if (!ciPassed) {
+			return {
+				status: "failed",
+				detail: `Cannot upgrade: latest CI run did not pass. Fix failures and try again.`,
+			};
+		}
+
+		// 2. Read current gjc version
+		const gjcProc = Bun.spawnSync(["gjc", "--version"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		if (gjcProc.exitCode !== 0) {
+			return { status: "failed", detail: "Failed to get current gjc version" };
+		}
+
+		const currentVersionMatch = ((gjcProc.stdout?.toString() || "") + (gjcProc.stderr?.toString() || "")).match(
+			/(?:gjc\/)?(\d+)\.(\d+)\.(\d+)/,
+		);
+		if (!currentVersionMatch) {
+			return { status: "failed", detail: "Could not parse current gjc version" };
+		}
+		const currentVersion = currentVersionMatch.slice(1, 4).join(".");
+
+		if (currentVersion === targetVersion) {
+			return { status: "ok", detail: `Already running gjc ${targetVersion}` };
+		}
+
+		// 3. Install new gjc version
+		const installProc = Bun.spawnSync(["bun", "add", "-g", `gajae-code@${targetVersion}`], {
+			stdout: "pipe",
+			stderr: "pipe",
+			cwd: join(options.home, "workspace"),
+		});
+
+		if (installProc.exitCode !== 0) {
+			return {
+				status: "failed",
+				detail: `Failed to install gjc ${targetVersion}: ${installProc.stderr?.toString()}`,
+			};
+		}
+
+		// 4. Verify installation
+		const verifyProc = Bun.spawnSync(["gjc", "--version"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		if (verifyProc.exitCode !== 0) {
+			return { status: "failed", detail: "Failed to verify gjc installation" };
+		}
+
+		const verifiedVersionMatch = ((verifyProc.stdout?.toString() || "") + (verifyProc.stderr?.toString() || "")).match(
+			/(?:gjc\/)?(\d+)\.(\d+)\.(\d+)/,
+		);
+		if (!verifiedVersionMatch) {
+			return { status: "failed", detail: "Could not verify installed gjc version" };
+		}
+
+		const verifiedVersion = verifiedVersionMatch.slice(1, 4).join(".");
+		if (verifiedVersion !== targetVersion) {
+			return {
+				status: "failed",
+				detail: `Verification failed: expected ${targetVersion}, got ${verifiedVersion}`,
+			};
+		}
+
+		return { status: "ok", detail: `Successfully upgraded gjc from ${currentVersion} to ${targetVersion}` };
+	} catch (error) {
+		return {
+			status: "failed",
+			detail: `Upgrade failed: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+}