fix(cli): enable native automatic updates by default (#295)

- Enable the native staged updater by default on macOS, Linux, and Windows.
- Interactive updates keep the confirmation prompt; explicit native updates in scripts or pipes download and stage without prompting.
- Report native installs as staged for the next CLI start instead of already installed.
- Preserve config/env opt-outs, rollout, checksum verification, and install locks; document startup prompts and opt-outs.

Author: elkaix

.changeset/fix-native-auto-update.md

@@ -0,0 +1,5 @@
+---
+"@pymodel/pythinker-code": patch
+---
+
+Enable automatic updates by default for native CLI installations.

apps/pythinker-code/src/cli/sub/upgrade.ts

@@ -86,7 +86,8 @@ export async function handleUpgrade(
 
   const source = await deps.detectInstallSource().catch(() => 'unsupported' as const);
   const installCommand = installCommandFor(source, target.version, deps.platform);
-  if (!canAutoInstall(source, deps.platform) || !deps.isInteractive) {
+  const needsConfirmation = source !== 'native';
+  if (!canAutoInstall(source, deps.platform) || (!deps.isInteractive && needsConfirmation)) {
     trackUpgradeEvent(deps.track, 'upgrade_command_manual_command', {
       current_version: currentVersion,
       target_version: target.version,
@@ -101,34 +102,36 @@ export async function handleUpgrade(
     return 0;
   }
 
-  trackUpgradeEvent(deps.track, 'upgrade_command_prompted', {
-    current_version: currentVersion,
-    target_version: target.version,
-    source,
-  });
-  logUpgradeInfo(deps.logger, 'manual upgrade prompted', {
-    currentVersion,
-    targetVersion: target.version,
-    source,
-  });
-  const choice = await deps.promptForInstallChoice({
-    currentVersion,
-    target,
-    installCommand,
-    installSource: source,
-  });
-  if (choice === 'skip') {
-    trackUpgradeEvent(deps.track, 'upgrade_command_skipped', {
+  if (deps.isInteractive) {
+    trackUpgradeEvent(deps.track, 'upgrade_command_prompted', {
       current_version: currentVersion,
       target_version: target.version,
       source,
     });
-    logUpgradeInfo(deps.logger, 'manual upgrade skipped', {
+    logUpgradeInfo(deps.logger, 'manual upgrade prompted', {
       currentVersion,
       targetVersion: target.version,
       source,
     });
-    return 0;
+    const choice = await deps.promptForInstallChoice({
+      currentVersion,
+      target,
+      installCommand,
+      installSource: source,
+    });
+    if (choice === 'skip') {
+      trackUpgradeEvent(deps.track, 'upgrade_command_skipped', {
+        current_version: currentVersion,
+        target_version: target.version,
+        source,
+      });
+      logUpgradeInfo(deps.logger, 'manual upgrade skipped', {
+        currentVersion,
+        targetVersion: target.version,
+        source,
+      });
+      return 0;
+    }
   }
 
   try {
@@ -148,7 +151,7 @@ export async function handleUpgrade(
       targetVersion: target.version,
       source,
     });
-    deps.stdout.write(renderInstallSuccessMessage(target));
+    deps.stdout.write(renderInstallSuccessMessage(target, source));
     return 0;
   } catch (error) {
     trackUpgradeEvent(deps.track, 'upgrade_command_failed', {

apps/pythinker-code/src/cli/update/preflight.ts

@@ -3,6 +3,7 @@ import { spawn } from 'node:child_process';
 import { log, type Logger } from '@pymodel/pythinker-code-sdk';
 import type { TelemetryProperties } from '@pymodel/pythinker-telemetry';
 
+import { CLI_COMMAND_NAME, PRODUCT_NAME } from '#/constant/app';
 import { loadTuiConfig } from '#/tui/config';
 import { resolveCommandPath } from '#/utils/process/resolve-command';
 
@@ -77,7 +78,7 @@ export function installCommandFor(
     case 'homebrew':
       return 'brew upgrade pythinker-code';
     case 'native':
-      return 'See https://github.com/PyModel/pythinker-code/releases';
+      return `${CLI_COMMAND_NAME} upgrade`;
     case 'unsupported':
       return `npm install -g ${NPM_PACKAGE_NAME}@${version}`;
   }
@@ -89,13 +90,12 @@ export function canAutoInstall(source: InstallSource, _platform: NodeJS.Platform
     case 'pnpm-global':
     case 'yarn-global':
     case 'bun-global':
+    case 'native':
       return true;
     case 'homebrew':
       // Homebrew upgrade may mutate other dependents and the formula can lag
       // behind the CDN release — prompt the user to run `brew upgrade` manually.
       return false;
-    case 'native':
-      return false;
     case 'unsupported':
       return false;
   }
@@ -213,7 +213,10 @@ export function renderManualUpdateMessage(
   );
 }
 
-export function renderInstallSuccessMessage(target: UpdateTarget): string {
+export function renderInstallSuccessMessage(target: UpdateTarget, source: InstallSource): string {
+  if (source === 'native') {
+    return `${PRODUCT_NAME} ${target.version} is staged; it applies the next time you start the CLI.\n`;
+  }
   return `Updated ${NPM_PACKAGE_NAME} to ${target.version}. Restart the CLI to use the new version.\n`;
 }
 
@@ -897,7 +900,7 @@ export async function runUpdatePreflight(
 
     try {
       await installUpdate(source, userVisibleTarget.version, platform);
-      stdout.write(renderInstallSuccessMessage(userVisibleTarget));
+      stdout.write(renderInstallSuccessMessage(userVisibleTarget, source));
       return 'exit';
     } catch (error) {
       stderr.write(

apps/pythinker-code/test/cli/update/preflight.test.ts

@@ -9,7 +9,7 @@ import {
   readUpdateInstallState,
   writeUpdateInstallState,
 } from '#/cli/update/install-state';
-import { canAutoInstall, installCommandFor, runUpdatePreflight } from '#/cli/update/preflight';
+import { runUpdatePreflight } from '#/cli/update/preflight';
 import { promptForInstallChoice } from '#/cli/update/prompt';
 import type * as PromptModule from '#/cli/update/prompt';
 import { refreshUpdateCache } from '#/cli/update/refresh';
@@ -499,50 +499,45 @@ describe('runUpdatePreflight', () => {
     expect(mocks.spawn).not.toHaveBeenCalled();
   });
 
-  it('native: shows the releases page and does not spawn on darwin', async () => {
-    disableAutoInstall();
-    mocks.readUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
-    mocks.refreshUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
-    mocks.detectInstallSource.mockResolvedValue('native');
-    mocks.promptForInstallChoice.mockResolvedValue('install');
-    mockSpawnExit(0);
-    const originalPlatform = process.platform;
-    Object.defineProperty(process, 'platform', { value: 'darwin' });
-    try {
-      expect(canAutoInstall('native', 'darwin')).toBe(false);
-      expect(installCommandFor('native', '0.5.0', 'darwin')).toBe(
-        'See https://github.com/PyModel/pythinker-code/releases',
-      );
-      const { stdout, options } = captureOutput();
-      await expect(runUpdatePreflight('0.4.0', options)).resolves.toBe('continue');
-      expect(mocks.spawn).not.toHaveBeenCalled();
-      expect(stdout.join('')).toContain('See https://github.com/PyModel/pythinker-code/releases');
-    } finally {
-      Object.defineProperty(process, 'platform', { value: originalPlatform });
-    }
-  });
+  it.each(['darwin', 'linux', 'win32'] as const)(
+    'native: downloads in the background by default on %s',
+    async (platform) => {
+      mocks.readUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+      mocks.refreshUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
+      mocks.detectInstallSource.mockResolvedValue('native');
+      mockSpawnExit(0);
+      const originalPlatform = process.platform;
+      Object.defineProperty(process, 'platform', { value: platform });
+      try {
+        const { stdout, options } = captureOutput();
+        await expect(runUpdatePreflight('0.4.0', options)).resolves.toBe('continue');
+        expect(promptForInstallChoice).not.toHaveBeenCalled();
+        expect(mocks.spawn).toHaveBeenCalledWith(
+          process.execPath,
+          ['__update_download', '0.5.0'],
+          platform === 'win32'
+            ? { detached: true, stdio: 'ignore', windowsHide: true }
+            : { detached: true, stdio: 'ignore' },
+        );
+        expect(stdout.join('')).not.toContain('To update manually');
+        await flushBackgroundInstall();
+      } finally {
+        Object.defineProperty(process, 'platform', { value: originalPlatform });
+      }
+    },
+  );
 
-  it('native: shows the releases page and does not spawn on win32', async () => {
+  it('native: asks before downloading when automatic installation is disabled', async () => {
     disableAutoInstall();
     mocks.readUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
     mocks.refreshUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
     mocks.detectInstallSource.mockResolvedValue('native');
-    mocks.promptForInstallChoice.mockResolvedValue('install');
-    mockSpawnExit(0);
-    const originalPlatform = process.platform;
-    Object.defineProperty(process, 'platform', { value: 'win32' });
-    try {
-      expect(canAutoInstall('native', 'win32')).toBe(false);
-      expect(installCommandFor('native', '0.5.0', 'win32')).toBe(
-        'See https://github.com/PyModel/pythinker-code/releases',
-      );
-      const { stdout, options } = captureOutput();
-      await expect(runUpdatePreflight('0.4.0', options)).resolves.toBe('continue');
-      expect(mocks.spawn).not.toHaveBeenCalled();
-      expect(stdout.join('')).toContain('See https://github.com/PyModel/pythinker-code/releases');
-    } finally {
-      Object.defineProperty(process, 'platform', { value: originalPlatform });
-    }
+    mocks.promptForInstallChoice.mockResolvedValue('skip');
+    const { options } = captureOutput();
+
+    await expect(runUpdatePreflight('0.4.0', options)).resolves.toBe('continue');
+    expect(promptForInstallChoice).toHaveBeenCalledTimes(1);
+    expect(mocks.spawn).not.toHaveBeenCalled();
   });
 
   it('unsupported: prints fallback npm command', async () => {
@@ -699,7 +694,7 @@ describe('runUpdatePreflight', () => {
     }
   });
 
-  it('native: does not retry a background install without a download source', async () => {
+  it('native: retries an orphaned background install when the download lock is free', async () => {
     // Orphaned `active`: older than the spawn grace window and the lock is
     // free (beforeEach default) ⇒ the previous downloader is gone; retry.
     mocks.readUpdateCache.mockResolvedValue(cacheWith('0.5.0'));
@@ -716,7 +711,12 @@ describe('runUpdatePreflight', () => {
     const { options } = captureOutput();
 
     await expect(runUpdatePreflight('0.4.0', options)).resolves.toBe('continue');
-    expect(mocks.spawn).not.toHaveBeenCalled();
+    expect(mocks.spawn).toHaveBeenCalledWith(
+      process.execPath,
+      ['__update_download', '0.5.0'],
+      expect.objectContaining({ detached: true, stdio: 'ignore' }),
+    );
+    await flushBackgroundInstall();
   });
 
   it('native: does not re-spawn while the install lock is genuinely held', async () => {

apps/pythinker-code/test/cli/upgrade.test.ts

@@ -109,6 +109,59 @@ describe('handleUpgrade', () => {
     expect(stderr.join('')).toBe('');
   });
 
+  it('installs a native update after confirmation instead of showing manual instructions', async () => {
+    const { stdout, writable } = captureOutput();
+    const deps = createDeps({ source: 'native' });
+
+    await expect(handleUpgrade('0.4.0', { ...deps, ...writable })).resolves.toBe(0);
+
+    expect(deps.promptForInstallChoice).toHaveBeenCalledTimes(1);
+    expect(deps.installUpdate).toHaveBeenCalledWith('native', '0.5.0', 'darwin');
+    expect(stdout.join('')).not.toContain('To update manually');
+  });
+
+  it('reports a native install as staged for the next start rather than already applied', async () => {
+    const { stdout, writable } = captureOutput();
+    const deps = createDeps({ latest: '0.5.0', source: 'native' });
+
+    await expect(handleUpgrade('0.4.0', { ...deps, ...writable })).resolves.toBe(0);
+
+    const output = stdout.join('');
+    expect(output).toContain('Pythinker Code 0.5.0 is staged; it applies the next time you start the CLI.');
+    expect(output).not.toContain('Updated @pymodel/pythinker-code to 0.5.0');
+  });
+
+  it('stages a native update without prompting when not interactive', async () => {
+    const { stdout, writable } = captureOutput();
+    const deps = createDeps({ latest: '0.5.0', source: 'native', isInteractive: false });
+
+    await expect(handleUpgrade('0.4.0', { ...deps, ...writable })).resolves.toBe(0);
+
+    expect(deps.promptForInstallChoice).not.toHaveBeenCalled();
+    expect(deps.installUpdate).toHaveBeenCalledWith('native', '0.5.0', 'darwin');
+    const output = stdout.join('');
+    expect(output).toContain('Pythinker Code 0.5.0 is staged; it applies the next time you start the CLI.');
+    expect(output).not.toContain('To update manually');
+  });
+
+  it('returns a failing exit code when a non-interactive native stage fails', async () => {
+    const { stdout, stderr, writable } = captureOutput();
+    const deps = createDeps({
+      latest: '0.5.0',
+      source: 'native',
+      isInteractive: false,
+      installUpdate: vi.fn().mockRejectedValue(new Error('update install exited with code 1')),
+    });
+
+    await expect(handleUpgrade('0.4.0', { ...deps, ...writable })).resolves.toBe(1);
+
+    expect(deps.promptForInstallChoice).not.toHaveBeenCalled();
+    expect(stderr.join('')).toContain(
+      'warning: failed to install @pymodel/pythinker-code@0.5.0: update install exited with code 1',
+    );
+    expect(stdout.join('')).not.toContain('is staged');
+  });
+
   it('skips the foreground install when the update prompt is declined', async () => {
     const { stdout, writable } = captureOutput();
     const deps = createDeps({

docs/guides/getting-started.md

@@ -66,7 +66,11 @@ After installation, verify that the executable is ready:
 pythinker --version
 ```
 
-**Upgrade**: automatic updates are enabled by default. npm, pnpm, yarn, bun, and supported native installations update in the background. Homebrew installations download and verify the formula source in the background, then install it on the next interactive launch and restart into the new version. Run `pythinker upgrade` to check immediately. For npm, pnpm, yarn, bun, and macOS / Linux native installations it offers to install the update right away; for Homebrew and Windows native installations it prints the command to run. You can also upgrade directly via the package manager:
+**Upgrade**: automatic updates are enabled by default for global npm, pnpm, yarn, bun, and native installations. Native installations on macOS, Linux, and Windows download and verify the update in the background, then apply it on the next start. Homebrew installations require `brew upgrade pythinker-code`.
+
+Run `pythinker update` (or `pythinker upgrade`) to check immediately. In a terminal, the command asks you to confirm. For a native installation in a script or a pipe, there is no prompt and the update downloads immediately. Native updates apply on the next start. To disable background installation, set `[upgrade].auto_install = false` in `~/.pythinker-code/tui.toml`. This setting stops unattended installation, but a startup prompt can still show when an update is available, as it does for a package manager installation. Set `PYTHINKER_CODE_NO_AUTO_UPDATE=1` to also disable automatic checks, startup prompts, and automatic update application.
+
+You can also upgrade directly via the package manager:
 
 ```sh
 npm install -g @pymodel/pythinker-code@latest

docs/reference/pythinker-command.md

@@ -253,13 +253,13 @@ pythinker export 01HZ...XYZ -o ./bug-report.zip --no-include-global-log
 
 ### `pythinker upgrade`
 
-Immediately check for the latest version and display an update prompt; exits after you make a selection. `pythinker update` is an alias for this command.
+Immediately check for the latest version. In a terminal, the command displays an update prompt and exits after you make a selection. `pythinker update` is an alias for this command.
 
 ```sh
 pythinker upgrade
 ```
 
-For global npm, pnpm, yarn, and bun installations, `pythinker upgrade` shows update options; selecting `Install update now` runs the corresponding foreground install command. For native installations (including Windows), it downloads and verifies the new binary in the foreground and swaps it in on the next start. When the current installation method cannot be upgraded automatically, the manual update command is printed instead.
+For global npm, pnpm, yarn, and bun installations, `pythinker upgrade` shows update options; selecting `Install update now` runs the corresponding foreground install command. For native installations (including Windows), it downloads and verifies the new binary in the foreground and swaps it in on the next start; when there is no terminal, such as in a script or a pipe, there is no prompt and the download starts immediately. When the current installation method cannot be upgraded automatically, the manual update command is printed instead.
 
 ### `pythinker vis`