@kimchi-dev/kimchictl 0.0.2

package/src/updates/check.ts

@@ -0,0 +1,117 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { fetchWithTimeout } from "../api/http.js"
+import { resolveSshPaths } from "../ssh/config.js"
+import { VERSION } from "../version.js"
+
+/**
+ * Daily background update check against the GitHub Releases API.
+ *
+ * The check must never block or fail a real command: every failure mode
+ * resolves to "no notification". Results cache in
+ * ~/.config/kimchi/kimchictl/update-check.json for 24h.
+ */
+
+const LATEST_RELEASE_URL = "https://api.github.com/repos/getkimchi/kimchictl/releases/latest"
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000
+const FETCH_TIMEOUT_MS = 2500
+
+interface UpdateCache {
+	latestVersion: string
+	checkedAt: string
+}
+
+/** Semantic-ish comparison: 0.10.0 > 0.9.9. Only digits matter; pre-releases compare numerically too. */
+export function isNewer(latest: string, current: string): boolean {
+	const parse = (v: string) =>
+		v
+			.replace(/^v/, "")
+			.split(".")
+			.map((part) => Number.parseInt(part, 10) || 0)
+	const a = parse(latest)
+	const b = parse(current)
+	for (let i = 0; i < 3; i++) {
+		const diff = (a[i] ?? 0) - (b[i] ?? 0)
+		if (diff !== 0) return diff > 0
+	}
+	return false
+}
+
+export interface UpdateCheckResult {
+	latest: string
+	current: string
+}
+
+async function readCache(path: string): Promise<UpdateCache | undefined> {
+	try {
+		const raw = JSON.parse(await readFile(path, "utf-8")) as Partial<UpdateCache>
+		if (typeof raw.latestVersion === "string" && typeof raw.checkedAt === "string") {
+			return { latestVersion: raw.latestVersion, checkedAt: raw.checkedAt }
+		}
+		return undefined
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") return undefined
+		return undefined // corrupt cache → treat as stale (refetched below)
+	}
+}
+
+async function writeCache(path: string, cache: UpdateCache): Promise<void> {
+	await mkdir(dirname(path), { recursive: true, mode: 0o700 })
+	await writeFile(path, `${JSON.stringify(cache, null, 2)}\n`, { mode: 0o600 })
+	await chmod(path, 0o600)
+}
+
+export interface CheckForUpdateOptions {
+	env?: NodeJS.ProcessEnv
+	fetch?: typeof globalThis.fetch
+	now?: () => Date
+	/** Version to compare against — tests inject; defaults to the baked-in VERSION. */
+	currentVersion?: string
+}
+
+/** Returns {latest, current} when a newer release exists, otherwise undefined. Never throws. */
+export async function checkForUpdate(options: CheckForUpdateOptions = {}): Promise<UpdateCheckResult | undefined> {
+	try {
+		const current = options.currentVersion ?? VERSION
+		// Source checkouts and dev builds are not versioned against releases.
+		if (current.endsWith("-dev")) return undefined
+
+		const env = options.env ?? process.env
+		if (env.KIMCHICTL_NO_UPDATE_CHECK) return undefined
+
+		const now = options.now ?? (() => new Date())
+		const cachePath = join(resolveSshPaths(env).home, "update-check.json")
+
+		const cached = await readCache(cachePath)
+		if (cached && now().getTime() - new Date(cached.checkedAt).getTime() < CHECK_INTERVAL_MS) {
+			return isNewer(cached.latestVersion, current) ? { latest: cached.latestVersion, current } : undefined
+		}
+
+		const fetchImpl = options.fetch ?? globalThis.fetch
+		const resp = await fetchWithTimeout(
+			LATEST_RELEASE_URL,
+			{ headers: { "User-Agent": `kimchictl/${current}` } },
+			fetchImpl,
+			FETCH_TIMEOUT_MS,
+		)
+		if (!resp.ok) return undefined
+		const data = (await resp.json()) as { tag_name?: string }
+		if (typeof data.tag_name !== "string") return undefined
+
+		const latest = data.tag_name.replace(/^v/, "")
+		await writeCache(cachePath, { latestVersion: latest, checkedAt: now().toISOString() }).catch(() => {
+			// Cache writes are best-effort only.
+		})
+		return isNewer(latest, current) ? { latest, current } : undefined
+	} catch {
+		return undefined
+	}
+}
+
+/** Post the update hint to stderr. Extracted so cli.ts stays a one-liner. */
+export async function maybeNotifyUpdate(options: CheckForUpdateOptions = {}): Promise<void> {
+	const result = await checkForUpdate(options)
+	if (result) {
+		console.error(`⬆ kimchictl ${result.latest} available (current ${result.current}) — update: kimchictl update`)
+	}
+}

package/src/updates/self.test.ts

@@ -0,0 +1,117 @@
+import { createHash } from "node:crypto"
+import { writeFile } from "node:fs/promises"
+import { afterEach, describe, expect, it } from "vitest"
+import { cleanupTempDirs, makeTempDir } from "../test-support.js"
+import { detectInstallMethod, platformAssetName, selfUpdateToVersion } from "./self.js"
+
+afterEach(() => cleanupTempDirs())
+
+describe("detectInstallMethod", () => {
+	it("recognizes Homebrew, runtimes, and plain binaries", () => {
+		expect(detectInstallMethod(() => "/opt/homebrew/Cellar/kimchictl/0.2.0/bin/kimchictl")).toBe("homebrew")
+		expect(detectInstallMethod(() => "/usr/local/bin/node")).toBe("runtime")
+		expect(detectInstallMethod(() => "/opt/homebrew/bin/bun")).toBe("runtime")
+		expect(detectInstallMethod(() => "/usr/local/bin/kimchictl")).toBe("binary")
+		expect(detectInstallMethod(() => "/home/u/.local/bin/kimchictl")).toBe("binary")
+	})
+})
+
+describe("platformAssetName", () => {
+	it("maps node platform/arch to release asset names", () => {
+		expect(platformAssetName("darwin", "arm64")).toBe("kimchictl-darwin-arm64")
+		expect(platformAssetName("linux", "x64")).toBe("kimchictl-linux-x64")
+		expect(() => platformAssetName("win32" as NodeJS.Platform, "x64")).toThrow("unsupported platform")
+	})
+})
+
+describe("selfUpdateToVersion", () => {
+	function scenario(options?: { withChecksums?: boolean; tamper?: boolean }) {
+		const tmp = makeTempDir()
+		const binary = Buffer.from("#!/bin/fake kimchictl binary\n")
+		const downloads = new Map<string, Buffer>()
+		// Checksum of the PRISTINE bytes; tamper must corrupt the served binary only.
+		if (options?.withChecksums !== false) {
+			downloads.set(
+				"checksums.txt",
+				Buffer.from(
+					`${createHash("sha256").update(binary).digest("hex")}  kimchictl-${process.platform === "darwin" ? "darwin" : "linux"}-${process.arch === "arm64" ? "arm64" : "x64"}\n`,
+				),
+			)
+		}
+		if (options?.tamper) binary[0] = 0x21
+		downloads.set("kimchictl-darwin-arm64", binary)
+		downloads.set("kimchictl-linux-arm64", binary)
+		downloads.set("kimchictl-darwin-x64", binary)
+		downloads.set("kimchictl-linux-x64", binary)
+
+		const written = new Map<string, Buffer>()
+		const renamed: string[][] = []
+		return {
+			tmp,
+			binary,
+			// Real download writes to dest — selfUpdateToVersion re-reads the staged
+			// file from disk when checksum-verifying.
+			download: async (url: string, dest: string) => {
+				const name = url.split("/").pop() ?? ""
+				const bytes = downloads.get(name)
+				if (!bytes) throw new Error(`404 ${name}`)
+				written.set(dest, bytes)
+				await writeFile(dest, bytes)
+			},
+			renamed,
+			renameFn: async (from: string, to: string) => {
+				renamed.push([from, to])
+			},
+			chmodFn: async () => {},
+		}
+	}
+
+	it("downloads the platform asset, verifies the checksum, and renames over the target", async () => {
+		const s = scenario()
+
+		await selfUpdateToVersion({
+			targetPath: "/usr/local/bin/kimchictl",
+			version: "0.3.0",
+			download: s.download,
+			renameFn: s.renameFn,
+			chmodFn: s.chmodFn,
+			tmpRoot: s.tmp,
+		})
+
+		const stagedContent = [...s.renamed][0]
+		expect(stagedContent?.[1]).toBe("/usr/local/bin/kimchictl")
+		expect(stagedContent?.[0]).toContain("kimchictl-update-")
+	})
+
+	it("aborts on checksum mismatch", async () => {
+		const s = scenario({ tamper: true })
+
+		await expect(
+			selfUpdateToVersion({
+				targetPath: "/usr/local/bin/kimchictl",
+				version: "0.3.0",
+				download: s.download,
+				renameFn: s.renameFn,
+				chmodFn: s.chmodFn,
+				tmpRoot: s.tmp,
+			}),
+		).rejects.toThrow(/checksum mismatch/)
+
+		expect(s.renamed.length).toBe(0)
+	})
+
+	it("proceeds without verification when checksums.txt is absent (older releases)", async () => {
+		const s = scenario({ withChecksums: false })
+
+		await selfUpdateToVersion({
+			targetPath: "/usr/local/bin/kimchictl",
+			version: "0.3.0",
+			download: s.download,
+			renameFn: s.renameFn,
+			chmodFn: s.chmodFn,
+			tmpRoot: s.tmp,
+		})
+
+		expect(s.renamed.length).toBe(1)
+	})
+})

package/src/updates/self.ts

@@ -0,0 +1,131 @@
+import { createHash } from "node:crypto"
+import { chmod, mkdtemp, readFile, rename, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { basename, join } from "node:path"
+import { fetchWithTimeout } from "../api/http.js"
+import { VERSION } from "../version.js"
+
+/**
+ * Self-update plumbing: detect how kimchictl was installed and, for binary
+ * installs, swap the executable in place from the latest GitHub release.
+ * Homebrew/npm/RTE (runtime) installs delegate to their own updaters.
+ */
+
+export type InstallMethod = "binary" | "homebrew" | "runtime"
+
+/** realpath seam: tests feed synthetic paths. */
+export function detectInstallMethod(realpath: () => string): InstallMethod {
+	const target = realpath()
+	if (/\/(Cellar|linuxbrew)\/[^/]*kimchictl?\//.test(target) || /homebrew.*kimchictl/i.test(target)) {
+		return "homebrew"
+	}
+	const base = basename(target)
+	if (base === "node" || base === "bun" || base === "node.exe") {
+		return "runtime"
+	}
+	return "binary"
+}
+
+/** realpath of the running executable, best-effort. */
+export function defaultInstallMethod(execPath = process.execPath): InstallMethod {
+	// bun-compiled binaries ARE the install (execPath is the binary); node/bun
+	// runtime hosts are npm/dev installs.
+	const base = basename(execPath)
+	if (base === "node" || base === "bun" || base === "node.exe") return "runtime"
+	return detectInstallMethod(() => execPath)
+}
+
+/** Release asset name for this platform, e.g. kimchictl-darwin-arm64. */
+export function platformAssetName(platform: NodeJS.Platform = process.platform, arch: string = process.arch): string {
+	const os = platform === "darwin" ? "darwin" : platform === "linux" ? "linux" : undefined
+	const cpu = arch === "arm64" ? "arm64" : arch === "x64" ? "x64" : undefined
+	if (!os || !cpu) {
+		throw new Error(`unsupported platform for self-update: ${platform}/${arch}`)
+	}
+	return `kimchictl-${os}-${cpu}`
+}
+
+export class SelfUpdateError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = "SelfUpdateError"
+	}
+}
+
+/** Distinct from a checksums-download failure: a verified mismatch always aborts. */
+export class ChecksumMismatchError extends SelfUpdateError {
+	constructor(message: string) {
+		super(message)
+		this.name = "ChecksumMismatchError"
+	}
+}
+
+export interface SelfUpdateOptions {
+	targetPath: string
+	version: string // e.g. "0.2.0" — bare tag (release.yml tags are bare)
+	fetch?: typeof globalThis.fetch
+	download?: (url: string, destPath: string) => Promise<void>
+	chmodFn?: (path: string, mode: number) => Promise<void>
+	renameFn?: (from: string, to: string) => Promise<void>
+	tmpRoot?: string
+}
+
+async function defaultDownload(url: string, destPath: string): Promise<void> {
+	const resp = await fetchWithTimeout(url, {}, globalThis.fetch, 60_000)
+	if (!resp.ok) {
+		throw new SelfUpdateError(`download failed: HTTP ${resp.status} for ${url}`)
+	}
+	await writeFile(destPath, new Uint8Array(await resp.arrayBuffer()))
+}
+
+/**
+ * Download the release asset for the current platform, checksum-verify it
+ * against release checksums.txt, then atomically rename it over targetPath.
+ */
+export async function selfUpdateToVersion(options: SelfUpdateOptions): Promise<void> {
+	const base = `https://github.com/getkimchi/kimchictl/releases/download/${options.version}`
+	const asset = platformAssetName()
+	const download = options.download ?? defaultDownload
+	const chmodFn = options.chmodFn ?? chmod
+	const renameFn = options.renameFn ?? rename
+
+	const tmpDir = await mkdtemp(join(options.tmpRoot ?? tmpdir(), "kimchictl-update-"))
+	const staged = join(tmpDir, "kimchictl")
+
+	await download(`${base}/${asset}`, staged)
+
+	// Verify against the release checksums.txt when it exists.
+	const checksumsPath = join(tmpDir, "checksums.txt")
+	try {
+		await download(`${base}/checksums.txt`, checksumsPath)
+		const checksums = await readFile(checksumsPath, "utf-8")
+		const expected = checksums
+			.split("\n")
+			.map((line) => line.trim())
+			.find((line) => line.endsWith(` ${asset}`))
+			?.split(/\s+/)[0]
+		if (expected) {
+			const actual = createHash("sha256")
+				.update(await readFile(staged))
+				.digest("hex")
+			if (actual !== expected) {
+				throw new ChecksumMismatchError(
+					`checksum mismatch for ${asset} — aborting update (expected ${expected}, got ${actual})`,
+				)
+			}
+		}
+	} catch (err) {
+		if (err instanceof ChecksumMismatchError) throw err
+		// Fetching checksums.txt itself failed (older releases may lack it) — proceed without verification.
+	}
+
+	await chmodFn(staged, 0o755)
+	await renameFn(staged, options.targetPath)
+}
+
+/** Guard for the update command — plain error for guard.ts, no new error family. */
+export function assertNotDevBuild(): void {
+	if (VERSION.endsWith("-dev")) {
+		throw new SelfUpdateError("self-update is not available from a dev build (VERSION is 0.0.0-dev)")
+	}
+}

package/src/version.ts

@@ -0,0 +1,6 @@
+/**
+ * Package version. The release pipeline (release.yml) stamps the git-tag
+ * version over this constant at build time; the committed value stays a
+ * sentinel so source checkouts are recognizable.
+ */
+export const VERSION = "0.0.2"