@outputai/cli 0.7.1-next.ae5bab4.0 → 0.7.1-next.d67ad85.0

package/bin/run.js

@@ -7,7 +7,7 @@ import { loadCredentialRefs } from '../dist/utils/credentials_loader.js';
 
 // Load environment variables from .env files before executing CLI
 loadEnvironment();
-bootstrapProxy();
+await bootstrapProxy();
 loadCredentialRefs();
 
 await execute( { dir: import.meta.url } );

package/dist/api/generated/api.d.ts

@@ -226,6 +226,39 @@ export declare const WorkflowResultResponseStatus: {
     readonly timed_out: "timed_out";
     readonly continued: "continued";
 };
+/**
+ * Structured failure details if the workflow failed, null otherwise
+ * @nullable
+ */
+export type WorkflowResultResponseErrorDetails = {
+    /**
+       * Friendly failure message (from the underlying application error)
+       * @nullable
+       */
+    message?: string | null;
+    /**
+       * Error name/type (the original error's class)
+       * @nullable
+       */
+    name?: string | null;
+    /**
+       * Whether Temporal flagged the failure retryable; null if unknown
+       * @nullable
+       */
+    retryable?: boolean | null;
+    /**
+       * Failing activity key ("workflow#step"); null if no activity failed
+       * @nullable
+       */
+    activityId?: string | null;
+    /**
+       * Sanitized error cause chain (name/message per level, no stack)
+       * @nullable
+       */
+    cause?: {
+        [key: string]: unknown;
+    } | null;
+} | null | null;
 export interface WorkflowResultResponse {
     /** The workflow execution id */
     workflowId?: string;
@@ -248,6 +281,11 @@ export interface WorkflowResultResponse {
        * @nullable
        */
     error?: string | null;
+    /**
+       * Structured failure details if the workflow failed, null otherwise
+       * @nullable
+       */
+    errorDetails?: WorkflowResultResponseErrorDetails;
 }
 export interface StopWorkflowResponse {
     workflowId?: string;

package/dist/assets/docker/docker-compose-dev.yml

@@ -80,7 +80,7 @@ services:
         condition: service_healthy
       worker:
         condition: service_healthy
-    image: outputai/api:${OUTPUT_API_VERSION:-0.7.1-next.ae5bab4.0}
+    image: outputai/api:${OUTPUT_API_VERSION:-0.7.1-next.d67ad85.0}
     init: true
     networks:
       - main

package/dist/commands/update.js

@@ -31,7 +31,7 @@ export default class Update extends Command {
     async updateCli() {
         const latest = await fetchLatestVersion();
         if (!latest) {
-            this.error('Could not fetch the latest version from npm. Check your network connection.');
+            this.error('Could not fetch the latest version from the npm registry. Run with DEBUG=output-cli:npm-update for details.');
         }
         this.log(`\nLatest @outputai/cli version: v${latest}\n`);
         await this.handleGlobalUpdate(latest);

package/dist/generated/framework_version.json

@@ -1,3 +1,3 @@
 {
-    "framework": "0.7.1-next.ae5bab4.0"
+    "framework": "0.7.1-next.d67ad85.0"
 }

package/dist/hooks/init.js

@@ -1,6 +1,8 @@
 import { ux } from '@oclif/core';
-import { checkForUpdate } from '#services/version_check.js';
+import debugFactory from 'debug';
+import { readCachedResult, spawnBackgroundRefresh } from '#services/version_check.js';
 import { setNonInteractive } from '#utils/interactive.js';
+const debug = debugFactory('output-cli:init');
 export const INTERACTIVE_FLAGS = ['--yes', '--non-interactive'];
 export const GLOBAL_FLAGS = new Set(INTERACTIVE_FLAGS);
 export const hasInteractiveFlag = (argv) => argv.some(arg => INTERACTIVE_FLAGS.includes(arg));
@@ -18,7 +20,13 @@ const hook = async function (opts) {
         setNonInteractive(true);
     }
     try {
-        const result = await checkForUpdate(this.config.version, this.config.cacheDir);
+        // Only the local cache is read here; the registry roundtrip happens in a
+        // detached child so it never delays the invoked command.
+        const result = await readCachedResult(this.config.version, this.config.cacheDir);
+        if (!result) {
+            spawnBackgroundRefresh(this.config.version, this.config.cacheDir);
+            return;
+        }
         if (!result.updateAvailable) {
             return;
         }
@@ -39,8 +47,9 @@ const hook = async function (opts) {
         ux.stdout(border);
         ux.stdout('');
     }
-    catch {
+    catch (error) {
         // Never block CLI execution
+        debug('Version banner failed: %O', error);
     }
 };
 export default hook;

package/dist/hooks/init.spec.js

@@ -1,9 +1,10 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { checkForUpdate } from '#services/version_check.js';
+import { readCachedResult, spawnBackgroundRefresh } from '#services/version_check.js';
 import { setNonInteractive } from '#utils/interactive.js';
 vi.mock('#services/version_check.js', () => ({
-    checkForUpdate: vi.fn()
+    readCachedResult: vi.fn(),
+    spawnBackgroundRefresh: vi.fn()
 }));
 vi.mock('#utils/interactive.js', () => ({
     setNonInteractive: vi.fn()
@@ -23,15 +24,16 @@ describe('init hook', () => {
     const createHookContext = (version = '0.8.4') => ({
         config: { version, cacheDir: '/tmp/test-cache' }
     });
-    it('should display warning when update is available', async () => {
-        vi.mocked(checkForUpdate).mockResolvedValue({
+    it('should display warning when cached result says an update is available', async () => {
+        vi.mocked(readCachedResult).mockResolvedValue({
             updateAvailable: true,
             currentVersion: '0.8.4',
             latestVersion: '1.0.0'
         });
         const ctx = createHookContext();
         await hook.call(ctx, { argv: [], id: undefined });
-        expect(checkForUpdate).toHaveBeenCalledWith('0.8.4', '/tmp/test-cache');
+        expect(readCachedResult).toHaveBeenCalledWith('0.8.4', '/tmp/test-cache');
+        expect(spawnBackgroundRefresh).not.toHaveBeenCalled();
         expect(ux.stdout).toHaveBeenCalled();
         const output = vi.mocked(ux.stdout).mock.calls.map(c => c[0]).join('\n');
         expect(output).toContain('Uhoh');
@@ -40,17 +42,25 @@ describe('init hook', () => {
         expect(output).toContain('npx output update');
     });
     it('should not display anything when up to date', async () => {
-        vi.mocked(checkForUpdate).mockResolvedValue({
+        vi.mocked(readCachedResult).mockResolvedValue({
             updateAvailable: false,
             currentVersion: '0.8.4',
             latestVersion: '0.8.4'
         });
         const ctx = createHookContext();
         await hook.call(ctx, { argv: [], id: undefined });
+        expect(spawnBackgroundRefresh).not.toHaveBeenCalled();
+        expect(ux.stdout).not.toHaveBeenCalled();
+    });
+    it('should kick off a background refresh and stay silent when the cache is stale', async () => {
+        vi.mocked(readCachedResult).mockResolvedValue(null);
+        const ctx = createHookContext();
+        await hook.call(ctx, { argv: [], id: undefined });
+        expect(spawnBackgroundRefresh).toHaveBeenCalledWith('0.8.4', '/tmp/test-cache');
         expect(ux.stdout).not.toHaveBeenCalled();
     });
     it('should silently handle errors', async () => {
-        vi.mocked(checkForUpdate).mockRejectedValue(new Error('network failure'));
+        vi.mocked(readCachedResult).mockRejectedValue(new Error('cache failure'));
         const ctx = createHookContext();
         await hook.call(ctx, { argv: [], id: undefined });
         expect(ux.stdout).not.toHaveBeenCalled();
@@ -58,7 +68,7 @@ describe('init hook', () => {
     describe('global interactive flags', () => {
         const originalArgv = process.argv;
         beforeEach(() => {
-            vi.mocked(checkForUpdate).mockResolvedValue({
+            vi.mocked(readCachedResult).mockResolvedValue({
                 updateAvailable: false,
                 currentVersion: '0.8.4',
                 latestVersion: '0.8.4'

package/dist/scripts/refresh_version_check.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/refresh_version_check.js

@@ -0,0 +1,9 @@
+// Detached helper spawned by spawnBackgroundRefresh (version_check.ts):
+// refreshes the version-check cache off the critical path.
+// Args: <currentVersion> <cacheDir>
+import debugFactory from 'debug';
+import { bootstrapProxy } from '#utils/proxy.js';
+import { runRefresh } from '#services/version_check.js';
+const debug = debugFactory('output-cli:version-check');
+await bootstrapProxy().catch(error => debug('Proxy bootstrap failed: %O', error));
+process.exitCode = await runRefresh(process.argv);

package/dist/services/npm_update_service.js

@@ -6,6 +6,8 @@ import packageJson from '../../package.json' with { type: 'json' };
 const execFile = promisify(execFileCb);
 const debug = debugFactory('output-cli:npm-update');
 const PACKAGE_NAME = packageJson.name;
+const REGISTRY_URL = 'https://registry.npmjs.org';
+const REGISTRY_TIMEOUT_MS = 5000;
 /* eslint-disable @typescript-eslint/no-explicit-any */
 function findVersionInTree(deps) {
     if (!deps) {
@@ -33,9 +35,15 @@ function parseNpmLsVersion(output) {
 }
 export async function fetchLatestVersion() {
     try {
-        const { stdout } = await execFile('npm', ['view', PACKAGE_NAME, 'version']);
-        const version = stdout.trim();
-        return version || null;
+        const response = await fetch(`${REGISTRY_URL}/${PACKAGE_NAME}/latest`, {
+            signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS)
+        });
+        if (!response.ok) {
+            debug('Registry responded with status %d', response.status);
+            return null;
+        }
+        const data = await response.json();
+        return data.version || null;
     }
     catch (error) {
         debug('Failed to fetch latest version: %O', error);

package/dist/services/npm_update_service.spec.js

@@ -8,24 +8,37 @@ vi.mock('node:child_process', () => ({
 vi.mock('node:util', () => ({
     promisify: vi.fn(() => mockExecFile)
 }));
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
 describe('npm_update_service', () => {
     beforeEach(() => {
         vi.clearAllMocks();
     });
     describe('fetchLatestVersion', () => {
-        it('should return version from npm view output', async () => {
-            mockExecFile.mockResolvedValue({ stdout: '1.2.3\n' });
+        it('should return version from the registry response', async () => {
+            mockFetch.mockResolvedValue({
+                ok: true,
+                json: async () => ({ version: '1.2.3' })
+            });
             const result = await fetchLatestVersion();
             expect(result).toBe('1.2.3');
-            expect(mockExecFile).toHaveBeenCalledWith('npm', ['view', '@outputai/cli', 'version']);
+            expect(mockFetch).toHaveBeenCalledWith('https://registry.npmjs.org/@outputai/cli/latest', { signal: expect.any(AbortSignal) });
         });
-        it('should return null on empty output', async () => {
-            mockExecFile.mockResolvedValue({ stdout: '' });
+        it('should return null on non-ok response', async () => {
+            mockFetch.mockResolvedValue({ ok: false, status: 404 });
+            const result = await fetchLatestVersion();
+            expect(result).toBeNull();
+        });
+        it('should return null when response has no version', async () => {
+            mockFetch.mockResolvedValue({
+                ok: true,
+                json: async () => ({})
+            });
             const result = await fetchLatestVersion();
             expect(result).toBeNull();
         });
-        it('should return null on whitespace-only output', async () => {
-            mockExecFile.mockResolvedValue({ stdout: '  \n' });
+        it('should return null on network failure or timeout', async () => {
+            mockFetch.mockRejectedValue(new Error('aborted'));
             const result = await fetchLatestVersion();
             expect(result).toBeNull();
         });

package/dist/services/version_check.d.ts

@@ -3,4 +3,22 @@ export interface VersionCheckResult {
     currentVersion: string;
     latestVersion: string;
 }
-export declare function checkForUpdate(currentVersion: string, cacheDir?: string): Promise<VersionCheckResult>;
+export declare function readCachedResult(currentVersion: string, cacheDir: string): Promise<VersionCheckResult | null>;
+/**
+ * Fetches the latest published version and persists the comparison to the
+ * cache file. Skips the write and returns false when the latest version
+ * can't be determined so the next invocation retries.
+ */
+export declare function refreshVersionCheck(currentVersion: string, cacheDir: string): Promise<boolean>;
+/**
+ * Entry point for the detached refresh helper. Validates the argv contract
+ * (`<currentVersion> <cacheDir>`) and returns the process exit code:
+ * 0 on success, 1 on bad args, 2 when the latest version couldn't be fetched.
+ */
+export declare function runRefresh(argv: string[]): Promise<number>;
+/**
+ * Refreshes the version-check cache in a detached child process so the
+ * registry roundtrip never blocks the invoked command. The result is picked
+ * up from the cache on the next invocation.
+ */
+export declare function spawnBackgroundRefresh(currentVersion: string, cacheDir: string): void;

package/dist/services/version_check.js

@@ -1,9 +1,13 @@
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import debugFactory from 'debug';
 import { fetchLatestVersion, isOutdated } from '#services/npm_update_service.js';
+const debug = debugFactory('output-cli:version-check');
 const CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
 const CACHE_FILENAME = 'version_check.json';
-async function readCache(cacheDir, currentVersion) {
+export async function readCachedResult(currentVersion, cacheDir) {
     try {
         const raw = await readFile(join(cacheDir, CACHE_FILENAME), 'utf-8');
         const cache = JSON.parse(raw);
@@ -15,7 +19,8 @@ async function readCache(cacheDir, currentVersion) {
         }
         return cache.result;
     }
-    catch {
+    catch (error) {
+        debug('Failed to read version cache: %O', error);
         return null;
     }
 }
@@ -25,28 +30,59 @@ async function writeCache(cacheDir, result) {
         const cache = { timestamp: Date.now(), result };
         await writeFile(join(cacheDir, CACHE_FILENAME), JSON.stringify(cache));
     }
-    catch {
-        // Silently ignore cache write failures
+    catch (error) {
+        debug('Failed to write version cache: %O', error);
     }
 }
-export async function checkForUpdate(currentVersion, cacheDir) {
-    if (cacheDir) {
-        const cached = await readCache(cacheDir, currentVersion);
-        if (cached) {
-            return cached;
-        }
-    }
+/**
+ * Fetches the latest published version and persists the comparison to the
+ * cache file. Skips the write and returns false when the latest version
+ * can't be determined so the next invocation retries.
+ */
+export async function refreshVersionCheck(currentVersion, cacheDir) {
     const latestVersion = await fetchLatestVersion();
     if (!latestVersion) {
-        return { updateAvailable: false, currentVersion, latestVersion: currentVersion };
+        debug('Latest version unavailable, skipping cache write');
+        return false;
     }
-    const result = {
+    await writeCache(cacheDir, {
         updateAvailable: isOutdated(currentVersion, latestVersion),
         currentVersion,
         latestVersion
-    };
-    if (cacheDir) {
-        await writeCache(cacheDir, result);
+    });
+    return true;
+}
+/**
+ * Entry point for the detached refresh helper. Validates the argv contract
+ * (`<currentVersion> <cacheDir>`) and returns the process exit code:
+ * 0 on success, 1 on bad args, 2 when the latest version couldn't be fetched.
+ */
+export async function runRefresh(argv) {
+    const [, , currentVersion, cacheDir] = argv;
+    if (!currentVersion || !cacheDir) {
+        console.error('Usage: refresh_version_check.js <currentVersion> <cacheDir>');
+        return 1;
+    }
+    return await refreshVersionCheck(currentVersion, cacheDir) ? 0 : 2;
+}
+/**
+ * Refreshes the version-check cache in a detached child process so the
+ * registry roundtrip never blocks the invoked command. The result is picked
+ * up from the cache on the next invocation.
+ */
+export function spawnBackgroundRefresh(currentVersion, cacheDir) {
+    try {
+        const scriptPath = fileURLToPath(new URL('../scripts/refresh_version_check.js', import.meta.url));
+        // stdio is discarded in normal use; surface the child's output when
+        // debugging is on so refresh failures are diagnosable
+        const stdio = debugFactory.enabled('output-cli:version-check') ? 'inherit' : 'ignore';
+        spawn(process.execPath, [scriptPath, currentVersion, cacheDir], {
+            detached: true,
+            stdio
+        }).unref();
+    }
+    catch (error) {
+        // Best-effort: a failed refresh only delays the update banner
+        debug('Failed to spawn background version refresh: %O', error);
     }
-    return result;
 }

package/dist/services/version_check.spec.js

@@ -1,7 +1,8 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { checkForUpdate } from './version_check.js';
+import { readCachedResult, refreshVersionCheck, runRefresh, spawnBackgroundRefresh } from './version_check.js';
 import { fetchLatestVersion, isOutdated } from '#services/npm_update_service.js';
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
 vi.mock('#services/npm_update_service.js', () => ({
     fetchLatestVersion: vi.fn(),
     isOutdated: vi.fn()
@@ -11,96 +12,125 @@ vi.mock('node:fs/promises', () => ({
     writeFile: vi.fn(),
     mkdir: vi.fn()
 }));
+vi.mock('node:child_process', () => ({
+    spawn: vi.fn()
+}));
+const { mockDebugEnabled } = vi.hoisted(() => ({ mockDebugEnabled: vi.fn() }));
+vi.mock('debug', () => ({
+    default: Object.assign(vi.fn(() => vi.fn()), { enabled: mockDebugEnabled })
+}));
 describe('version_check', () => {
+    const cacheDir = '/tmp/test-cache';
     beforeEach(() => {
         vi.clearAllMocks();
+        mockDebugEnabled.mockReturnValue(false);
     });
-    describe('checkForUpdate', () => {
-        it('should return updateAvailable true when outdated', async () => {
-            vi.mocked(fetchLatestVersion).mockResolvedValue('1.0.0');
-            vi.mocked(isOutdated).mockReturnValue(true);
-            const result = await checkForUpdate('0.8.4');
-            expect(result).toEqual({
-                updateAvailable: true,
-                currentVersion: '0.8.4',
-                latestVersion: '1.0.0'
-            });
-        });
-        it('should return updateAvailable false when up to date', async () => {
-            vi.mocked(fetchLatestVersion).mockResolvedValue('0.8.4');
-            vi.mocked(isOutdated).mockReturnValue(false);
-            const result = await checkForUpdate('0.8.4');
-            expect(result).toEqual({
-                updateAvailable: false,
-                currentVersion: '0.8.4',
-                latestVersion: '0.8.4'
-            });
-        });
-        it('should return updateAvailable false when fetch fails', async () => {
-            vi.mocked(fetchLatestVersion).mockResolvedValue(null);
-            const result = await checkForUpdate('0.8.4');
-            expect(result.updateAvailable).toBe(false);
-            expect(isOutdated).not.toHaveBeenCalled();
-        });
-    });
-    describe('caching', () => {
-        const cacheDir = '/tmp/test-cache';
+    describe('readCachedResult', () => {
         it('should return cached result when cache is fresh', async () => {
             const cached = {
                 timestamp: Date.now() - 1000,
                 result: { updateAvailable: true, currentVersion: '0.8.4', latestVersion: '1.0.0' }
             };
             vi.mocked(readFile).mockResolvedValue(JSON.stringify(cached));
-            const result = await checkForUpdate('0.8.4', cacheDir);
+            const result = await readCachedResult('0.8.4', cacheDir);
             expect(result).toEqual(cached.result);
-            expect(fetchLatestVersion).not.toHaveBeenCalled();
         });
-        it('should fetch fresh result when cache is expired', async () => {
+        it('should return null when cache is expired', async () => {
             const cached = {
                 timestamp: Date.now() - (5 * 60 * 60 * 1000), // 5 hours ago
                 result: { updateAvailable: true, currentVersion: '0.8.4', latestVersion: '0.9.0' }
             };
             vi.mocked(readFile).mockResolvedValue(JSON.stringify(cached));
-            vi.mocked(fetchLatestVersion).mockResolvedValue('1.0.0');
-            vi.mocked(isOutdated).mockReturnValue(true);
-            const result = await checkForUpdate('0.8.4', cacheDir);
-            expect(fetchLatestVersion).toHaveBeenCalled();
-            expect(result.latestVersion).toBe('1.0.0');
+            expect(await readCachedResult('0.8.4', cacheDir)).toBeNull();
         });
-        it('should fetch fresh result when cached version differs from current', async () => {
+        it('should return null when cached version differs from current', async () => {
             const cached = {
                 timestamp: Date.now() - 1000,
                 result: { updateAvailable: true, currentVersion: '0.8.4', latestVersion: '1.0.0' }
             };
             vi.mocked(readFile).mockResolvedValue(JSON.stringify(cached));
-            vi.mocked(fetchLatestVersion).mockResolvedValue('1.0.0');
-            vi.mocked(isOutdated).mockReturnValue(true);
-            const result = await checkForUpdate('0.9.0', cacheDir);
-            expect(fetchLatestVersion).toHaveBeenCalled();
-            expect(result.currentVersion).toBe('0.9.0');
+            expect(await readCachedResult('0.9.0', cacheDir)).toBeNull();
         });
-        it('should fetch fresh result when cache file is missing', async () => {
+        it('should return null when cache file is missing', async () => {
             vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
-            vi.mocked(fetchLatestVersion).mockResolvedValue('1.0.0');
-            vi.mocked(isOutdated).mockReturnValue(true);
-            const result = await checkForUpdate('0.8.4', cacheDir);
-            expect(fetchLatestVersion).toHaveBeenCalled();
-            expect(result.latestVersion).toBe('1.0.0');
+            expect(await readCachedResult('0.8.4', cacheDir)).toBeNull();
         });
-        it('should write cache after fresh fetch', async () => {
-            vi.mocked(readFile).mockRejectedValue(new Error('ENOENT'));
+        it('should return null when cache file is corrupt', async () => {
+            vi.mocked(readFile).mockResolvedValue('not json');
+            expect(await readCachedResult('0.8.4', cacheDir)).toBeNull();
+        });
+    });
+    describe('refreshVersionCheck', () => {
+        it('should write comparison result to the cache', async () => {
             vi.mocked(fetchLatestVersion).mockResolvedValue('1.0.0');
             vi.mocked(isOutdated).mockReturnValue(true);
-            await checkForUpdate('0.8.4', cacheDir);
+            await expect(refreshVersionCheck('0.8.4', cacheDir)).resolves.toBe(true);
             expect(mkdir).toHaveBeenCalledWith(cacheDir, { recursive: true });
-            expect(writeFile).toHaveBeenCalled();
+            expect(writeFile).toHaveBeenCalledTimes(1);
+            const written = JSON.parse(vi.mocked(writeFile).mock.calls[0][1]);
+            expect(written.result).toEqual({
+                updateAvailable: true,
+                currentVersion: '0.8.4',
+                latestVersion: '1.0.0'
+            });
+            // A missing/invalid timestamp would make the cache immortal (NaN > TTL is false)
+            expect(written.timestamp).toBeCloseTo(Date.now(), -3);
+        });
+        it('should skip the cache write when fetch fails so the next invocation retries', async () => {
+            vi.mocked(fetchLatestVersion).mockResolvedValue(null);
+            await expect(refreshVersionCheck('0.8.4', cacheDir)).resolves.toBe(false);
+            expect(isOutdated).not.toHaveBeenCalled();
+            expect(writeFile).not.toHaveBeenCalled();
         });
-        it('should skip caching when no cacheDir provided', async () => {
+    });
+    describe('runRefresh', () => {
+        it('should refresh the cache from argv in spawn order (script, currentVersion, cacheDir)', async () => {
             vi.mocked(fetchLatestVersion).mockResolvedValue('1.0.0');
             vi.mocked(isOutdated).mockReturnValue(true);
-            await checkForUpdate('0.8.4');
-            expect(readFile).not.toHaveBeenCalled();
+            const exitCode = await runRefresh(['node', 'refresh_version_check.js', '0.8.4', cacheDir]);
+            expect(exitCode).toBe(0);
+            expect(mkdir).toHaveBeenCalledWith(cacheDir, { recursive: true });
+            const written = JSON.parse(vi.mocked(writeFile).mock.calls[0][1]);
+            expect(written.result.currentVersion).toBe('0.8.4');
+            expect(written.result.latestVersion).toBe('1.0.0');
+        });
+        it('should exit with a distinct code when the latest version cannot be fetched', async () => {
+            vi.mocked(fetchLatestVersion).mockResolvedValue(null);
+            const exitCode = await runRefresh(['node', 'refresh_version_check.js', '0.8.4', cacheDir]);
+            expect(exitCode).toBe(2);
+            expect(writeFile).not.toHaveBeenCalled();
+        });
+        it('should exit non-zero with usage on missing args without fetching', async () => {
+            const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+            const exitCode = await runRefresh(['node', 'refresh_version_check.js']);
+            expect(exitCode).toBe(1);
+            expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Usage:'));
+            expect(fetchLatestVersion).not.toHaveBeenCalled();
             expect(writeFile).not.toHaveBeenCalled();
+            errorSpy.mockRestore();
+        });
+    });
+    describe('spawnBackgroundRefresh', () => {
+        it('should spawn a detached unref-ed helper with version and cache dir args', () => {
+            const unref = vi.fn();
+            vi.mocked(spawn).mockReturnValue({ unref });
+            spawnBackgroundRefresh('0.8.4', cacheDir);
+            expect(spawn).toHaveBeenCalledWith(process.execPath, [expect.stringContaining('refresh_version_check.js'), '0.8.4', cacheDir], { detached: true, stdio: 'ignore' });
+            expect(unref).toHaveBeenCalled();
+        });
+        it('should inherit stdio when the version-check debug namespace is enabled', () => {
+            mockDebugEnabled.mockReturnValue(true);
+            const unref = vi.fn();
+            vi.mocked(spawn).mockReturnValue({ unref });
+            spawnBackgroundRefresh('0.8.4', cacheDir);
+            expect(mockDebugEnabled).toHaveBeenCalledWith('output-cli:version-check');
+            expect(spawn).toHaveBeenCalledWith(process.execPath, expect.any(Array), { detached: true, stdio: 'inherit' });
+        });
+        it('should swallow spawn failures', () => {
+            vi.mocked(spawn).mockImplementation(() => {
+                throw new Error('spawn failure');
+            });
+            expect(() => spawnBackgroundRefresh('0.8.4', cacheDir)).not.toThrow();
         });
     });
 });

package/dist/utils/proxy.d.ts

@@ -4,6 +4,7 @@
  * `http_proxy`). No-op when none are set. Invalid URLs are logged and
  * skipped so the CLI keeps running.
  *
- * Call once at CLI startup, before any network activity.
+ * Call once at CLI startup, before any network activity. `undici` is
+ * imported lazily so invocations without a proxy skip loading it.
  */
-export declare const bootstrapProxy: () => void;
+export declare const bootstrapProxy: () => Promise<void>;

package/dist/utils/proxy.js

@@ -1,13 +1,13 @@
-import { EnvHttpProxyAgent, setGlobalDispatcher } from 'undici';
 /**
  * Routes all `fetch()` calls through an HTTP/HTTPS proxy when standard
  * proxy env vars are set (`HTTPS_PROXY`, `https_proxy`, `HTTP_PROXY`,
  * `http_proxy`). No-op when none are set. Invalid URLs are logged and
  * skipped so the CLI keeps running.
  *
- * Call once at CLI startup, before any network activity.
+ * Call once at CLI startup, before any network activity. `undici` is
+ * imported lazily so invocations without a proxy skip loading it.
  */
-export const bootstrapProxy = () => {
+export const bootstrapProxy = async () => {
     const proxyUrl = process.env.HTTPS_PROXY || process.env.https_proxy ||
         process.env.HTTP_PROXY || process.env.http_proxy;
     if (!proxyUrl) {
@@ -20,5 +20,6 @@ export const bootstrapProxy = () => {
         console.warn(`[proxy] Ignoring invalid proxy URL: ${proxyUrl}`);
         return;
     }
+    const { EnvHttpProxyAgent, setGlobalDispatcher } = await import('undici');
     setGlobalDispatcher(new EnvHttpProxyAgent());
 };