fix: make update check non-blocking by spawning detached child process

[bukinoshita]

Summary

Fixes a bug where the CLI update notifier blocks command exit for up to ~5 seconds on slow/offline networks (BU-642).

After every successful non-update command, checkForUpdates() was awaiting a live GitHub fetch() with a 5-second AbortSignal.timeout whenever the cached update state was stale or missing. This kept the Node event loop alive and made fast commands appear to hang.

Changes

src/lib/update-check.ts

• checkForUpdates() is now synchronous — it reads the cached state file, optionally prints a stale update notice, and when the cache is stale/missing, spawns a detached child process to refresh the cache in the background
• spawnBackgroundRefresh() spawns a detached node -e child process with stdio: 'ignore' and .unref() so the main CLI process exits immediately
• buildRefreshScript() generates a self-contained Node script that fetches the latest GitHub release and writes update-state.json, falling back to writing the current version on any failure (prevents repeated fetch retries on every subsequent command)
• resolveNodePath() determines the correct Node binary path for spawning the child process
• All functions converted to const arrow functions per coding standards
• Removed JSDoc comments per coding standards

src/cli.ts

• Removed .catch() wrapper since checkForUpdates() is no longer async and never throws

tests/lib/update-check.test.ts

• Rewrote tests using vi.mock('node:child_process') to mock the spawn call in ESM
• Added tests for the new background refresh behavior: spawn on stale cache, spawn on missing cache, stale notice display, skip conditions
• Added dedicated test suites for buildRefreshScript, resolveNodePath, and spawnBackgroundRefresh
• Converted from test() to it() per coding standards

How it works

Before: cli.ts → checkForUpdates() → await fetchLatestVersion() → fetch(..., timeout: 5s) — blocks process exit

After: cli.ts → checkForUpdates() → spawnBackgroundRefresh() — spawns a detached child process that fetches and writes the state file independently; main process exits immediately

The cached notice path (fresh cache) remains in-process and is unaffected. On the next command after a background refresh, the updated cache will be read and any update notice displayed.

Linear Issue: BU-642

  

---

Summary by cubic

Make the CLI update check non‑blocking by moving the network fetch to a detached background process. Commands now exit immediately even on slow/offline networks, addressing BU-642.

• Bug Fixes
  • checkForUpdates() is now synchronous; uses cached state, shows a stale notice if it indicates a newer version, and spawns a background refresh when the cache is stale/missing.
  • Introduced spawnBackgroundRefresh() to run node -e detached with stdio: 'ignore' and .unref(); spawn failures are ignored so the main process always exits.
  • buildRefreshScript() fetches the latest GitHub release and writes update-state.json, writing the current version on any failure or invalid response to avoid repeated retries.
  • resolveNodePath() selects the correct Node binary across platforms.
  • src/cli.ts: call checkForUpdates() without awaiting or catching.
  • Tests: mock node:child_process spawn; add coverage for background refresh, buildRefreshScript, resolveNodePath, spawn failure handling, and stale notice behavior.

^{Written for commit 53e8cc1. Summary will update on new commits.}

[bukinoshita]

@cubic-dev-ai can you review?

[cubic-dev-ai]

@cubic-dev-ai can you review?

@bukinoshita I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

2 issues found across 3 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/lib/update-check.ts">

<violation number="1" location="src/lib/update-check.ts:30">
P2: Falling back to `'node'` disables background update refresh for standalone binary installs that do not have Node in PATH.</violation>
</file>

<file name="src/cli.ts">

<violation number="1" location="src/cli.ts:189">
P2: Wrap `checkForUpdates()` in a local guard; it can still throw on malformed cached state and currently bubbles into the global error handler.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

[cubic-dev-ai]

P2: Falling back to 'node' disables background update refresh for standalone binary installs that do not have Node in PATH.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/lib/update-check.ts, line 30:

<comment>Falling back to `'node'` disables background update refresh for standalone binary installs that do not have Node in PATH.</comment>

<file context>
@@ -1,38 +1,81 @@
+  if (/(?:^|[\\/])node(?:\.exe)?$/i.test(process.execPath)) {
+    return process.execPath;
+  }
+  return 'node';
+};
+
</file context>

[cubic-dev-ai]

P2: Wrap checkForUpdates() in a local guard; it can still throw on malformed cached state and currently bubbles into the global error handler.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/cli.ts, line 189:

<comment>Wrap `checkForUpdates()` in a local guard; it can still throw on malformed cached state and currently bubbles into the global error handler.</comment>

<file context>
@@ -186,7 +186,7 @@ program
     }
 
-    return checkForUpdates().catch(() => {});
+    checkForUpdates();
   })
   .catch((err) => {
</file context>