feat(settings): add OpenCode update action (NeuralNomadsAI#585)

## Summary

- add an OpenCode update card to the OpenCode settings section
- show the installed version and a versioned update button only when npm
advertises a newer release
- run the upgrade through the generated OpenCode SDK against a ready
instance using the configured binary
- keep running instances uninterrupted; newly started instances use the
installed version
- localize loading, unavailable-instance, success, and failure states
across all supported locales

## Server behavior

- resolve the selected binary with the existing binary probe
- check opencode-ai/latest with a 10-second timeout and a five-minute
cache
- require a ready workspace using that exact binary before enabling the
upgrade
- invoke client.global.upgrade({ target }) rather than assembling an
OpenCode API request manually
- return stable error codes without exposing server details

## Validation

- pm run typecheck in packages/server
- pm run typecheck in packages/ui
- ode --import tsx --test src/opencode-update/service.test.ts
- pm run build in packages/ui
- pm run build in packages/server
- git diff --check

<img width="1034" height="688" alt="image"
src="https://github.com/user-attachments/assets/a71a01c4-d3e2-46f6-a333-a408c058255c"
/>
<img width="1018" height="360" alt="image"
src="https://github.com/user-attachments/assets/983a87a9-6103-48d7-8bcf-e10c5ce6a105"
/>

Author: pascalandr

packages/server/src/api-types.ts

@@ -356,6 +356,19 @@ export interface BinaryValidationResult {
   error?: string
 }
 
+export interface OpenCodeUpdateStatus {
+  currentVersion: string
+  latestVersion: string | null
+  updateAvailable: boolean | null
+  canUpgrade: boolean
+  checkError?: "update_check_failed"
+}
+
+export interface OpenCodeUpdateResponse {
+  success: boolean
+  version: string
+}
+
 export interface SpeechSegment {
   startMs: number
   endMs: number

packages/server/src/opencode-update/service.test.ts

@@ -0,0 +1,129 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+import { OpenCodeUpdateError, OpenCodeUpdateService, type OpenCodeUpdateServiceDeps } from "./service"
+
+function createDeps(overrides: Partial<OpenCodeUpdateServiceDeps> = {}): OpenCodeUpdateServiceDeps {
+  let currentVersion = "1.0.0"
+  return {
+    resolveBinary: () => ({ path: "opencode", label: "OpenCode" }),
+    probeBinary: () => ({ valid: true, version: currentVersion }),
+    findReadyInstanceId: () => "workspace-1",
+    fetchLatestVersion: async () => "1.1.0",
+    upgradeInstance: async (_instanceId, target) => {
+      currentVersion = target
+      return { success: true, version: target }
+    },
+    ...overrides,
+  }
+}
+
+test("reports an available update and caches the latest version", async () => {
+  let checks = 0
+  const service = new OpenCodeUpdateService(createDeps({
+    fetchLatestVersion: async () => {
+      checks += 1
+      return "1.1.0"
+    },
+  }))
+
+  assert.deepEqual(await service.getStatus(), {
+    currentVersion: "1.0.0",
+    latestVersion: "1.1.0",
+    updateAvailable: true,
+    canUpgrade: true,
+  })
+  await service.getStatus()
+  assert.equal(checks, 1)
+})
+
+test("keeps the update visible when no matching instance is ready", async () => {
+  const service = new OpenCodeUpdateService(createDeps({ findReadyInstanceId: () => undefined }))
+
+  assert.deepEqual(await service.getStatus(), {
+    currentVersion: "1.0.0",
+    latestVersion: "1.1.0",
+    updateAvailable: true,
+    canUpgrade: false,
+  })
+})
+
+test("preserves the installed version when the registry check fails", async () => {
+  const service = new OpenCodeUpdateService(createDeps({
+    fetchLatestVersion: async () => {
+      throw new Error("registry unavailable")
+    },
+  }))
+
+  assert.deepEqual(await service.getStatus(), {
+    currentVersion: "1.0.0",
+    latestVersion: null,
+    updateAvailable: null,
+    canUpgrade: false,
+    checkError: "update_check_failed",
+  })
+})
+
+test("upgrades through the matching OpenCode instance to the advertised version", async () => {
+  const calls: Array<{ instanceId: string; target: string }> = []
+  let currentVersion = "1.0.0"
+  const service = new OpenCodeUpdateService(createDeps({
+    probeBinary: () => ({ valid: true, version: currentVersion }),
+    upgradeInstance: async (instanceId, target) => {
+      calls.push({ instanceId, target })
+      currentVersion = target
+      return { success: true, version: target }
+    },
+  }))
+
+  assert.deepEqual(await service.upgrade(), { success: true, version: "1.1.0" })
+  assert.deepEqual(calls, [{ instanceId: "workspace-1", target: "1.1.0" }])
+})
+
+test("rejects success when the configured binary was not updated", async () => {
+  const service = new OpenCodeUpdateService(createDeps({
+    probeBinary: () => ({ valid: true, version: "1.0.0" }),
+    upgradeInstance: async (_instanceId, target) => ({ success: true, version: target }),
+  }))
+
+  await assert.rejects(
+    () => service.upgrade(),
+    (error: unknown) => error instanceof OpenCodeUpdateError && error.code === "upgrade_verification_failed",
+  )
+})
+
+test("joins concurrent upgrades for the same binary", async () => {
+  let currentVersion = "1.0.0"
+  let upgrades = 0
+  let finishUpgrade: (() => void) | undefined
+  const gate = new Promise<void>((resolve) => {
+    finishUpgrade = resolve
+  })
+  const service = new OpenCodeUpdateService(createDeps({
+    probeBinary: () => ({ valid: true, version: currentVersion }),
+    upgradeInstance: async (_instanceId, target) => {
+      upgrades += 1
+      await gate
+      currentVersion = target
+      return { success: true, version: target }
+    },
+  }))
+
+  const first = service.upgrade()
+  const second = service.upgrade()
+  finishUpgrade?.()
+
+  assert.deepEqual(await Promise.all([first, second]), [
+    { success: true, version: "1.1.0" },
+    { success: true, version: "1.1.0" },
+  ])
+  assert.equal(upgrades, 1)
+})
+
+test("rejects an upgrade when no matching OpenCode instance is running", async () => {
+  const service = new OpenCodeUpdateService(createDeps({ findReadyInstanceId: () => undefined }))
+
+  await assert.rejects(
+    () => service.upgrade(),
+    (error: unknown) => error instanceof OpenCodeUpdateError && error.code === "no_ready_instance",
+  )
+})

packages/server/src/opencode-update/service.ts

@@ -0,0 +1,194 @@
+import { fetch } from "undici"
+import type { OpenCodeUpdateResponse, OpenCodeUpdateStatus } from "../api-types"
+import type { SettingsService } from "../settings/service"
+import { BinaryResolver, type ResolvedBinary } from "../settings/binaries"
+import type { WorkspaceManager } from "../workspaces/manager"
+import { createInstanceClient } from "../workspaces/instance-client"
+import { probeBinaryVersion } from "../workspaces/spawn"
+import { compareVersionStrings, stripTagPrefix } from "../releases/release-monitor"
+
+const OPENCODE_LATEST_URL = "https://registry.npmjs.org/opencode-ai/latest"
+const LATEST_VERSION_CACHE_MS = 5 * 60_000
+const UPGRADE_TIMEOUT_MS = 10 * 60_000
+const inFlightUpgrades = new Map<string, Promise<OpenCodeUpdateResponse>>()
+
+type UpgradeResult = { success: true; version: string } | { success: false; error: string }
+
+export interface OpenCodeUpdateServiceDeps {
+  resolveBinary: () => ResolvedBinary
+  probeBinary: typeof probeBinaryVersion
+  findReadyInstanceId: (binaryPath: string) => string | undefined
+  upgradeInstance: (instanceId: string, target: string) => Promise<UpgradeResult>
+  fetchLatestVersion: () => Promise<string>
+  now?: () => number
+}
+
+export class OpenCodeUpdateError extends Error {
+  constructor(
+    readonly code:
+      | "binary_unavailable"
+      | "no_ready_instance"
+      | "update_check_failed"
+      | "upgrade_failed"
+      | "upgrade_verification_failed",
+    message: string,
+  ) {
+    super(message)
+    this.name = "OpenCodeUpdateError"
+  }
+}
+
+export class OpenCodeUpdateService {
+  private latestVersionCache: { version: string; expiresAt: number } | null = null
+
+  constructor(private readonly deps: OpenCodeUpdateServiceDeps) {}
+
+  async getStatus(): Promise<OpenCodeUpdateStatus> {
+    const binary = this.deps.resolveBinary()
+    const currentVersion = this.readCurrentVersion(binary.path)
+    let latestVersion: string
+    try {
+      latestVersion = await this.readLatestVersion()
+    } catch (error) {
+      if (!(error instanceof OpenCodeUpdateError) || error.code !== "update_check_failed") throw error
+      return {
+        currentVersion,
+        latestVersion: null,
+        updateAvailable: null,
+        canUpgrade: false,
+        checkError: "update_check_failed",
+      }
+    }
+    const updateAvailable = compareVersionStrings(latestVersion, currentVersion) > 0
+    const readyInstanceId = this.deps.findReadyInstanceId(binary.path)
+
+    return {
+      currentVersion,
+      latestVersion,
+      updateAvailable,
+      canUpgrade: updateAvailable && Boolean(readyInstanceId),
+    }
+  }
+
+  upgrade(): Promise<OpenCodeUpdateResponse> {
+    const binary = this.deps.resolveBinary()
+    const existing = inFlightUpgrades.get(binary.path)
+    if (existing) return existing
+
+    const pending = this.performUpgrade(binary).finally(() => {
+      if (inFlightUpgrades.get(binary.path) === pending) inFlightUpgrades.delete(binary.path)
+    })
+    inFlightUpgrades.set(binary.path, pending)
+    return pending
+  }
+
+  private async performUpgrade(binary: ResolvedBinary): Promise<OpenCodeUpdateResponse> {
+    const currentVersion = this.readCurrentVersion(binary.path)
+    const latestVersion = await this.readLatestVersion()
+
+    if (compareVersionStrings(latestVersion, currentVersion) <= 0) {
+      return { success: true, version: currentVersion }
+    }
+
+    const instanceId = this.deps.findReadyInstanceId(binary.path)
+    if (!instanceId) {
+      throw new OpenCodeUpdateError(
+        "no_ready_instance",
+        "No running OpenCode instance uses the configured binary",
+      )
+    }
+
+    try {
+      const result = await this.deps.upgradeInstance(instanceId, latestVersion)
+      if (!result.success) {
+        throw new OpenCodeUpdateError("upgrade_failed", result.error)
+      }
+      const installedVersion = this.readCurrentVersion(binary.path)
+      if (compareVersionStrings(installedVersion, latestVersion) !== 0) {
+        throw new OpenCodeUpdateError(
+          "upgrade_verification_failed",
+          `OpenCode reported ${result.version}, but the configured binary is still ${installedVersion}`,
+        )
+      }
+      return { success: true, version: installedVersion }
+    } catch (error) {
+      if (error instanceof OpenCodeUpdateError) throw error
+      throw new OpenCodeUpdateError(
+        "upgrade_failed",
+        error instanceof Error ? error.message : "OpenCode upgrade failed",
+      )
+    }
+  }
+
+  private readCurrentVersion(binaryPath: string): string {
+    if (process.platform === "win32" && /["\r\n]/.test(binaryPath)) {
+      throw new OpenCodeUpdateError("binary_unavailable", "The configured OpenCode binary path is invalid")
+    }
+    const result = this.deps.probeBinary(binaryPath)
+    const version = stripTagPrefix(result.version)
+    if (!result.valid || !version) {
+      throw new OpenCodeUpdateError("binary_unavailable", result.error ?? "Unable to read OpenCode version")
+    }
+    return version
+  }
+
+  private async readLatestVersion(): Promise<string> {
+    const now = (this.deps.now ?? Date.now)()
+    if (this.latestVersionCache && this.latestVersionCache.expiresAt > now) {
+      return this.latestVersionCache.version
+    }
+
+    try {
+      const version = stripTagPrefix(await this.deps.fetchLatestVersion())
+      if (!version || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+        throw new Error("OpenCode registry returned an invalid version")
+      }
+      this.latestVersionCache = { version, expiresAt: now + LATEST_VERSION_CACHE_MS }
+      return version
+    } catch (error) {
+      throw new OpenCodeUpdateError(
+        "update_check_failed",
+        error instanceof Error ? error.message : "Unable to check the latest OpenCode version",
+      )
+    }
+  }
+}
+
+export async function fetchLatestOpenCodeVersion(): Promise<string> {
+  const response = await fetch(OPENCODE_LATEST_URL, {
+    headers: { Accept: "application/json", "User-Agent": "CodeNomad-CLI" },
+    signal: AbortSignal.timeout(10_000),
+  })
+  if (!response.ok) {
+    throw new Error(`OpenCode registry responded with ${response.status}`)
+  }
+  const payload = (await response.json()) as { version?: unknown }
+  if (typeof payload.version !== "string") {
+    throw new Error("OpenCode registry response did not include a version")
+  }
+  return payload.version
+}
+
+export function createOpenCodeUpdateService(
+  settings: SettingsService,
+  workspaceManager: WorkspaceManager,
+): OpenCodeUpdateService {
+  const binaryResolver = new BinaryResolver(settings)
+  return new OpenCodeUpdateService({
+    resolveBinary: () => {
+      const binary = binaryResolver.resolveDefault()
+      return { ...binary, path: workspaceManager.resolveBinaryPath(binary.path) }
+    },
+    probeBinary: probeBinaryVersion,
+    findReadyInstanceId: (binaryPath) => workspaceManager.findReadyInstanceIdByBinary(binaryPath),
+    fetchLatestVersion: fetchLatestOpenCodeVersion,
+    upgradeInstance: async (instanceId, target) => {
+      const client = createInstanceClient(workspaceManager, instanceId, { timeoutMs: UPGRADE_TIMEOUT_MS })
+      if (!client) {
+        throw new OpenCodeUpdateError("no_ready_instance", "OpenCode instance is not ready")
+      }
+      const { data } = await client.global.upgrade({ target }, { throwOnError: true })
+      return data
+    },
+  })
+}

packages/server/src/server/http-server.ts

@@ -25,6 +25,7 @@ import { registerBackgroundProcessRoutes } from "./routes/background-processes"
 import { registerYoloRoutes } from "./routes/yolo"
 import { registerWorktreeRoutes } from "./routes/worktrees"
 import { registerSpeechRoutes } from "./routes/speech"
+import { registerOpenCodeUpdateRoutes } from "./routes/opencode-update"
 import { registerRemoteServerRoutes } from "./routes/remote-servers"
 import { registerRemoteProxyRoutes } from "./routes/remote-proxy"
 import { registerSideCarRoutes } from "./routes/sidecars"
@@ -45,6 +46,7 @@ import { VoiceModeManager } from "../plugins/voice-mode"
 import type { SideCarManager } from "../sidecars/manager"
 import type { PreviewManager } from "../previews/manager"
 import type { RemoteProxySessionManager } from "./remote-proxy"
+import { createOpenCodeUpdateService } from "../opencode-update/service"
 
 interface HttpServerDeps {
   bindHost: string
@@ -283,6 +285,10 @@ export function createHttpServer(deps: HttpServerDeps) {
 
   registerWorkspaceRoutes(app, { workspaceManager: deps.workspaceManager })
   registerSettingsRoutes(app, { settings: deps.settings, logger: apiLogger })
+  registerOpenCodeUpdateRoutes(app, {
+    service: createOpenCodeUpdateService(deps.settings, deps.workspaceManager),
+    logger: apiLogger,
+  })
   registerFilesystemRoutes(app, { fileSystemBrowser: deps.fileSystemBrowser })
   registerConfigFileRoutes(app)
   registerMetaRoutes(app, { serverMeta: deps.serverMeta })