feat(cli): add --version flag with detailed version information

- Create version module to gather OpenCoder, Bun, SDK, and Node versions
- Replace commander .version() with custom handler displaying all versions
- Add -V shorthand as alternative to --version
- Include 3 new unit tests for version flag parsing
- Update CLI help text with version flag examples and documentation

Signed-off-by: leocavalcante <leo@cavalcante.dev>

Author: leocavalcante

src/cli.ts

@@ -10,8 +10,7 @@ import { initializePaths } from "./fs.ts"
 import { runLoop } from "./loop.ts"
 import { formatMetricsSummary, loadMetrics, resetMetrics, saveMetrics } from "./metrics.ts"
 import type { CliOptions } from "./types.ts"
-
-const VERSION = "1.0.0"
+import { formatVersionInfo, getVersionInfo } from "./version.ts"
 
 /**
  * Result of CLI argument parsing.
@@ -33,7 +32,7 @@ function createProgram(): Command {
 	program
 		.name("opencoder")
 		.description("Autonomous development loop powered by OpenCode")
-		.version(VERSION)
+		.option("-V, --version", "Display version information and exit")
 		.argument("[hint]", "Optional hint/instruction for the AI")
 		.option("-p, --project <dir>", "Project directory (default: current directory)")
 		.option("-m, --model <model>", "Model for both plan and build (provider/model format)")
@@ -69,6 +68,9 @@ Examples:
   $ opencoder -m anthropic/claude-sonnet-4 -s
     Run with commit signoff enabled
 
+  $ opencoder --version
+    Display version information
+
   $ opencoder --status
     Display metrics summary without starting the loop
 
@@ -84,6 +86,7 @@ Options:
     -P, --plan-model            Model for plan phase
     -B, --build-model           Model for build phase
     -v, --verbose               Enable verbose logging
+    -V, --version               Display version information
     --no-auto-commit            Disable automatic commits after tasks
     --no-auto-push              Disable automatic push after cycles
     -s, --signoff               Add Signed-off-by line to commits
@@ -212,6 +215,15 @@ export async function run(): Promise<void> {
 				metricsReset: opts.metricsReset as boolean | undefined,
 			}
 
+			// Handle --version flag: display version info and exit
+			if (opts.version) {
+				const versionInfo = getVersionInfo()
+				console.log("")
+				console.log(formatVersionInfo(versionInfo))
+				console.log("")
+				return
+			}
+
 			// Handle --status flag: display metrics and exit
 			if (cliOptions.status) {
 				const projectDir = cliOptions.project ? resolve(cliOptions.project) : process.cwd()

src/version.ts

@@ -0,0 +1,91 @@
+/**
+ * Version information module for opencoder
+ */
+
+/**
+ * Version information structure
+ */
+export interface VersionInfo {
+	opencoder: string
+	bun: string
+	sdk: string
+	node: string
+}
+
+/**
+ * Get OpenCoder version from package.json
+ */
+function getOpencodeVersion(): string {
+	try {
+		// Use dynamic import to read package.json
+		const pkg = globalThis.require?.("../package.json") as { version?: string }
+		return pkg?.version ?? "unknown"
+	} catch {
+		return "1.0.0" // Fallback to hardcoded version
+	}
+}
+
+/**
+ * Get Bun runtime version
+ */
+function getBunVersion(): string {
+	try {
+		// Access Bun.version - it's always a string at runtime
+		const bunVersion = (Bun as { version: string }).version
+		return bunVersion ?? "unknown"
+	} catch {
+		return "unknown"
+	}
+}
+
+/**
+ * Get OpenCode SDK version by checking node_modules
+ */
+function getSdkVersion(): string {
+	try {
+		// Try to require the SDK package.json
+		const sdkPkg = globalThis.require?.("@opencode-ai/sdk/package.json") as {
+			version?: string
+		}
+		return sdkPkg?.version ?? "unknown"
+	} catch {
+		return "unknown"
+	}
+}
+
+/**
+ * Get Node.js version for compatibility reference
+ */
+function getNodeVersion(): string {
+	try {
+		// Remove 'v' prefix from process.version
+		const nodeVer = process.version
+		return nodeVer.startsWith("v") ? nodeVer.substring(1) : nodeVer
+	} catch {
+		return "unknown"
+	}
+}
+
+/**
+ * Gather all version information
+ */
+export function getVersionInfo(): VersionInfo {
+	return {
+		opencoder: getOpencodeVersion(),
+		bun: getBunVersion(),
+		sdk: getSdkVersion(),
+		node: getNodeVersion(),
+	}
+}
+
+/**
+ * Format version information for display
+ */
+export function formatVersionInfo(info: VersionInfo): string {
+	return [
+		`OpenCoder ${info.opencoder}`,
+		`Bun ${info.bun}`,
+		`OpenCode SDK ${info.sdk}`,
+		`Node.js ${info.node} (compatibility reference)`,
+	].join("\n")
+}

tests/cli.test.ts

@@ -260,6 +260,31 @@ describe("parseCli", () => {
 			expect(result.options.commitSignoff).toBe(true)
 		})
 	})
+
+	describe("version option", () => {
+		test("parses --version flag", () => {
+			const result = parseCli(argv("--version"))
+
+			// Note: --version is handled specially by commander and exits,
+			// but we can still parse it through ParsedCli if we want
+			// The actual version display is tested in the run() function
+			expect(result).toBeDefined()
+		})
+
+		test("parses -V shorthand", () => {
+			const result = parseCli(argv("-V"))
+
+			expect(result).toBeDefined()
+		})
+
+		test("version flag can be combined with other options in parsing", () => {
+			// While --version typically causes commander to exit,
+			// we verify the CLI accepts the option
+			const result = parseCli(argv("-V", "-m", "anthropic/claude-sonnet-4"))
+
+			expect(result).toBeDefined()
+		})
+	})
 })
 
 /**

tests/version.test.ts

@@ -0,0 +1,89 @@
+/**
+ * Tests for version module
+ */
+
+import { describe, expect, test } from "bun:test"
+import { formatVersionInfo, getVersionInfo } from "../src/version.ts"
+
+describe("version module", () => {
+	describe("getVersionInfo", () => {
+		test("returns VersionInfo object with all required fields", () => {
+			const info = getVersionInfo()
+
+			expect(info).toBeDefined()
+			expect(info.opencoder).toBeDefined()
+			expect(info.bun).toBeDefined()
+			expect(info.sdk).toBeDefined()
+			expect(info.node).toBeDefined()
+		})
+
+		test("opencoder version is a string", () => {
+			const info = getVersionInfo()
+			expect(typeof info.opencoder).toBe("string")
+			expect(info.opencoder.length).toBeGreaterThan(0)
+		})
+
+		test("bun version is a string", () => {
+			const info = getVersionInfo()
+			expect(typeof info.bun).toBe("string")
+			expect(info.bun.length).toBeGreaterThan(0)
+		})
+
+		test("sdk version is a string", () => {
+			const info = getVersionInfo()
+			expect(typeof info.sdk).toBe("string")
+			expect(info.sdk.length).toBeGreaterThan(0)
+		})
+
+		test("node version is a string", () => {
+			const info = getVersionInfo()
+			expect(typeof info.node).toBe("string")
+			expect(info.node.length).toBeGreaterThan(0)
+		})
+	})
+
+	describe("formatVersionInfo", () => {
+		test("formats version info as multi-line string", () => {
+			const info = {
+				opencoder: "1.0.0",
+				bun: "1.0.0",
+				sdk: "1.1.25",
+				node: "20.10.0",
+			}
+
+			const formatted = formatVersionInfo(info)
+
+			expect(formatted).toContain("OpenCoder 1.0.0")
+			expect(formatted).toContain("Bun 1.0.0")
+			expect(formatted).toContain("OpenCode SDK 1.1.25")
+			expect(formatted).toContain("Node.js 20.10.0")
+		})
+
+		test("formats with newlines between lines", () => {
+			const info = {
+				opencoder: "1.0.0",
+				bun: "1.0.0",
+				sdk: "1.1.25",
+				node: "20.10.0",
+			}
+
+			const formatted = formatVersionInfo(info)
+			const lines = formatted.split("\n")
+
+			expect(lines.length).toBe(4)
+		})
+
+		test("includes compatibility reference for Node.js", () => {
+			const info = {
+				opencoder: "1.0.0",
+				bun: "1.0.0",
+				sdk: "1.1.25",
+				node: "20.10.0",
+			}
+
+			const formatted = formatVersionInfo(info)
+
+			expect(formatted).toContain("compatibility reference")
+		})
+	})
+})