@hifullmoon/aicommit 2.2.2 → 2.3.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ This file lists notable user-facing changes. Internal refactors, test-only chang
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-09-05
+
+### Added
+
+- Added `aicommit update` for verified self-updates of regular npm-global installations, with exact-version installation, JSON output, and safeguards against updating source links or the wrong Node.js environment.
+
+### Changed
+
+- Moved the cancel action to the end of sensitive-data confirmation menus to keep send choices together.
+
+## [2.2.3] - 2026-09-01
+
+### Fixed
+
+- Prevented accepted provider requests from being replayed after response-body interruptions, avoiding duplicate generations and potential duplicate billing.
+- Honored provider retry timing safely by failing clearly when `Retry-After` exceeds the configured maximum delay instead of retrying too early.
+- Stopped setup from replacing valid JSON configurations with unsupported schemas or invalid structures.
+
 ## [2.2.2] - 2026-08-31
 
 ### Added
@@ -170,7 +188,9 @@ This file lists notable user-facing changes. Internal refactors, test-only chang
 - Added file-level split planning and execution with Git-state concurrency checks.
 - Added provider presets and user/project configuration boundaries.
 
-[Unreleased]: https://github.com/hi-fullmoon/AICommit/compare/v2.2.2...HEAD
+[Unreleased]: https://github.com/hi-fullmoon/AICommit/compare/v2.3.0...HEAD
+[2.3.0]: https://github.com/hi-fullmoon/AICommit/releases/tag/v2.3.0
+[2.2.3]: https://github.com/hi-fullmoon/AICommit/releases/tag/v2.2.3
 [2.2.2]: https://github.com/hi-fullmoon/AICommit/releases/tag/v2.2.2
 [2.2.1]: https://github.com/hi-fullmoon/AICommit/releases/tag/v2.2.1
 [2.2.0]: https://github.com/hi-fullmoon/AICommit/releases/tag/v2.2.0

package/README.md

@@ -32,6 +32,14 @@ npm install --global @hifullmoon/aicommit
 
 Requires Node.js >= 18.
 
+Update an npm-global installation from the configured registry:
+
+```bash
+aicommit update
+```
+
+The command resolves npm's `latest` dist-tag, installs that exact version, and verifies the installed manifest. It refuses to modify a source checkout, an `npm link`, or a package owned by a different active Node.js/npm environment; use the manual upgrade command from the distribution guide in those cases.
+
 See the bilingual [installation, upgrade, signature-verification, and rollback guide](docs/distribution.md). The npm package has an automated installation smoke test.
 
 To install a source checkout instead, run `npm install --global .` from the repository root.
@@ -287,6 +295,7 @@ Project-level configuration is treated as untrusted: it cannot change the endpoi
 
 ```bash
 aicommit setup           # interactive configuration wizard
+aicommit update          # update the global npm installation to latest
 aicommit doctor          # diagnose runtime, config, credentials, and connectivity
 aicommit config show     # show the effective config with secrets redacted
 aicommit config validate # validate config without resolving credentials
@@ -376,7 +385,7 @@ Verify the registration with `whence -w _aicommit`; it should print `_aicommit:
 
 ### Machine-readable output
 
-Use `--output=json` for scripts and CI. Commit and split flows also require `--yes`, preventing a machine consumer from hanging on an interactive prompt. stdout contains exactly one JSON object; progress, debug details, and diagnostics go to stderr. `doctor --output=json` does not require `--yes`.
+Use `--output=json` for scripts and CI. Commit and split flows also require `--yes`, preventing a machine consumer from hanging on an interactive prompt. stdout contains exactly one JSON object; progress, debug details, and diagnostics go to stderr. `doctor --output=json` and `update --output=json` do not require `--yes`.
 
 ```json
 {

package/README.zh-CN.md

@@ -34,6 +34,14 @@ npm install --global @hifullmoon/aicommit
 
 需要 Node.js >= 18。
 
+从当前配置的 registry 更新 npm 全局安装：
+
+```bash
+aicommit update
+```
+
+该命令会解析 npm 的 `latest` dist-tag，安装对应的精确版本，并校验安装后的 manifest。源码检出、`npm link`，或属于另一个 Node.js/npm 环境的安装会被拒绝；这些情况请使用分发指南中的手动升级命令。
+
 安装、升级、签名校验与回滚请参阅双语[分发指南](docs/distribution.md)。npm package 带有自动化安装冒烟测试。
 
 如需直接安装源码检出版本，请在仓库根目录运行 `npm install --global .`。
@@ -289,6 +297,7 @@ AICommit 不会主动发送无关的仓库文件、历史提交正文、环境
 
 ```bash
 aicommit setup           # 交互式配置向导
+aicommit update          # 将 npm 全局安装更新到最新版
 aicommit doctor          # 诊断运行时、配置、凭据和连接
 aicommit config show     # 显示脱敏后的有效配置
 aicommit config validate # 校验配置，但不解析凭据
@@ -378,7 +387,7 @@ exec zsh
 
 ### 机器可读输出
 
-脚本和 CI 请使用 `--output=json`。提交和 split 流程还必须使用 `--yes`，避免机器消费者卡在交互提示上。stdout 只包含一个 JSON 对象；进度、调试信息和诊断输出会写入 stderr。`doctor --output=json` 不要求 `--yes`。
+脚本和 CI 请使用 `--output=json`。提交和 split 流程还必须使用 `--yes`，避免机器消费者卡在交互提示上。stdout 只包含一个 JSON 对象；进度、调试信息和诊断输出会写入 stderr。`doctor --output=json` 和 `update --output=json` 不要求 `--yes`。
 
 ```json
 {

package/docs/distribution.md

@@ -11,6 +11,9 @@ AICommit is distributed exclusively through npm.
 npm install --global @hifullmoon/aicommit
 
 # upgrade / 升级
+aicommit update
+
+# manual upgrade / 手动升级
 npm install --global @hifullmoon/aicommit@latest
 
 # pin or roll back / 固定或回滚
@@ -19,6 +22,10 @@ npm install --global @hifullmoon/aicommit@1.4.0
 aicommit --version
 ```
 
+`aicommit update` 使用当前 `PATH` 中的 npm 和它配置的 registry，解析 `latest` dist-tag 后安装精确版本，并校验安装后的 package manifest。它仅更新当前 npm 全局根目录中的普通安装；源码检出、`npm link`、`npx` 缓存和其他 Node.js/npm 环境中的安装会被拒绝，以免更新错误的可执行文件。此时请切换到安装 AICommit 的 Node.js 环境，或使用上面的手动命令。
+
+`aicommit update` uses the npm on the current `PATH` and its configured registry. It resolves the `latest` dist-tag, installs that exact version, and verifies the installed package manifest. It only updates a regular installation in the active npm global root; source checkouts, `npm link`, `npx` caches, and installations owned by another Node.js/npm environment are rejected to avoid updating the wrong executable. Switch to the Node.js environment that installed AICommit, or use the manual command above.
+
 发布工作流使用 npm Trusted Publishing，不保存长期 `NPM_TOKEN`。来自公开 GitHub 仓库的 OIDC 发布会自动携带 npm provenance。可使用当前 npm CLI 检查 registry signature 与 provenance：
 
 The release workflow uses npm Trusted Publishing without a long-lived `NPM_TOKEN`. OIDC publishing from the public GitHub repository automatically includes npm provenance. Verify registry signatures and provenance with a current npm CLI:
@@ -26,7 +33,7 @@ The release workflow uses npm Trusted Publishing without a long-lived `NPM_TOKEN
 ```bash
 workdir=$(mktemp -d)
 cd "$workdir"
-npm install --package-lock-only @hifullmoon/aicommit@2.2.2
+npm install --package-lock-only @hifullmoon/aicommit@2.3.0
 npm audit signatures
 ```
 

package/docs/troubleshooting.md

@@ -26,6 +26,8 @@ JSON 模式保证 stdout 只有一个机器对象，诊断进入 stderr。`error
 | `split run --scope=all --yes` stops before API call / split 非交互在 API 前停止 | `sensitive_data` / `7`          | Complete untracked scan found sensitive-looking data / 完整未跟踪扫描发现疑似敏感数据                                           | Review/stage intended files explicitly; do not bypass without checking the actual content                                                               |
 | Commit aborts after generation / 生成后提交中止                                 | `concurrent_modification` / `8` | Index/worktree changed during the protected window / 受保护窗口中 index/worktree 被修改                                         | Review `git status`, restore the intended snapshot, and generate again                                                                                  |
 | Split stopped after one or more commits / split 部分提交后停止                  | reported Git failure            | Hook, crash, SIGINT, or concurrent pending edit / hook、崩溃、中断或待处理文件变化                                              | Run `aicommit split resume`; if another Git workflow already replaced the transaction, use `aicommit split abort`（只删除恢复元数据，不改提交或工作区） |
+| `aicommit update` refuses the installation / update 拒绝当前安装                | `config` / `2`                  | Source checkout, npm link, or another active Node/npm environment / 源码、npm link 或当前是另一套 Node/npm 环境                 | Activate the Node environment that installed AICommit, or run `npm install --global @hifullmoon/aicommit@latest` manually                               |
+| `aicommit update` cannot reach npm / update 无法访问 npm                        | `network` / `4`                 | Registry authentication, proxy, DNS, or network failure / registry 鉴权、代理、DNS 或网络失败                                   | Check `npm config get registry` and npm authentication/proxy settings, then retry                                                                       |
 | npm provenance is absent or invalid / npm provenance 缺失或失败                 | npm audit failure               | Old npm CLI, non-trusted release, or wrong version / npm 过旧、非可信发布或版本错误                                             | Upgrade npm; run `npm audit signatures`; install only a version linked to the official workflow                                                         |
 
 If a failure remains, capture `aicommit doctor --output=json`, Node/Git versions, the error category, and redacted config sources. Never attach a diff, commit message, config file, API key, reasoning trace, or credential-helper output to a public issue.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hifullmoon/aicommit",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "Safe, local-first AI commit message generator for Git workflows",
   "type": "module",
   "bin": {

package/src/api.js

@@ -136,18 +136,24 @@ async function fetchWithRetry(apiUrl, init, timeout, configuredPolicy, consume)
       } catch (err) {
         const wrappedTimeout = timeoutError(err, timeout);
         if (wrappedTimeout) throw wrappedTimeout;
-        if (!networkFailure(err) || attempt >= policy.maxAttempts) throw err;
-        const delay = Math.min(policy.baseDelayMs * 2 ** (attempt - 1), policy.maxDelayMs);
-        await policy.sleep(delay);
-        continue;
+        // Once the provider has accepted a generation request, replaying it is
+        // unsafe: the first request may already have completed and been billed
+        // even though its response body was interrupted locally.
+        throw err;
       }
     }
     if (RETRYABLE_STATUS.has(response.status) && attempt < policy.maxAttempts) {
       const requestedDelay = retryAfterMs(response.headers.get('retry-after'), policy.now);
-      const delay = Math.min(
-        requestedDelay ?? policy.baseDelayMs * 2 ** (attempt - 1),
-        policy.maxDelayMs,
-      );
+      if (requestedDelay !== null && requestedDelay > policy.maxDelayMs) {
+        await response.body?.cancel().catch(() => {});
+        throw new Error(
+          `HTTP ${response.status}: provider requested a retry after ${Math.ceil(
+            requestedDelay / 1000,
+          )}s, exceeding the configured retry.maxDelayMs limit.`,
+        );
+      }
+      const delay =
+        requestedDelay ?? Math.min(policy.baseDelayMs * 2 ** (attempt - 1), policy.maxDelayMs);
       await response.body?.cancel().catch(() => {});
       await policy.sleep(delay);
       continue;

package/src/cli.js

@@ -15,10 +15,12 @@ function showHelp() {
   ${chalk.bold('Usage:')}
     ${chalk.dim('$')} aicommit [path] [options]
     ${chalk.dim('$')} aicommit setup
+    ${chalk.dim('$')} aicommit update
     ${chalk.dim('$')} aicommit split [run|plan|apply|resume|abort] [options]
 
   ${chalk.bold('Everyday commands:')}
     setup                 Interactive configuration wizard
+    update                Update the global npm installation to latest
     doctor                Diagnose runtime, config, credentials, and connectivity
     split                 Plan and create file-level logical commits
 
@@ -92,6 +94,7 @@ function parsedDefaults(overrides = {}) {
     dryRun: false,
     yes: false,
     setup: false,
+    update: false,
     doctor: false,
     configAction: null,
     policyAction: null,
@@ -132,7 +135,10 @@ export function parseArgs(args = process.argv.slice(2)) {
     return parsedDefaults({ completionShell: shell });
   }
 
-  if (args[0] === 'policy' && args[1] === 'template') {
+  const update = args[0] === 'update';
+  if (update) args = args.slice(1);
+
+  if (!update && args[0] === 'policy' && args[1] === 'template') {
     if (args.length !== 2) {
       throw fail(ERROR_CATEGORIES.CONFIG, 'policy template takes no arguments.');
     }
@@ -140,7 +146,7 @@ export function parseArgs(args = process.argv.slice(2)) {
   }
 
   let policyAction = null;
-  if (args[0] === 'policy') {
+  if (!update && args[0] === 'policy') {
     policyAction = args[1];
     if (policyAction !== 'check') {
       throw fail(ERROR_CATEGORIES.CONFIG, 'policy requires one action: template or check.');
@@ -149,7 +155,7 @@ export function parseArgs(args = process.argv.slice(2)) {
   }
 
   let configAction = null;
-  if (args[0] === 'config') {
+  if (!update && args[0] === 'config') {
     configAction = args[1];
     if (!['show', 'validate', 'path'].includes(configAction)) {
       throw fail(ERROR_CATEGORIES.CONFIG, 'config requires one action: show, validate, or path.');
@@ -158,7 +164,7 @@ export function parseArgs(args = process.argv.slice(2)) {
   }
 
   let splitCommand = null;
-  if (args[0] === 'split') {
+  if (!update && args[0] === 'split') {
     const requestedAction = args[1];
     const actions = ['run', 'plan', 'apply', 'resume', 'abort'];
     if (!requestedAction || requestedAction.startsWith('-')) {
@@ -178,7 +184,7 @@ export function parseArgs(args = process.argv.slice(2)) {
     }
   }
 
-  const doctor = args[0] === 'doctor';
+  const doctor = !update && args[0] === 'doctor';
   if (doctor) args = args.slice(1);
 
   let targetPath = null;
@@ -458,6 +464,25 @@ export function parseArgs(args = process.argv.slice(2)) {
       'doctor accepts only --provider, --model, --output, and --debug options.',
     );
   }
+  if (
+    update &&
+    (targetPath ||
+      cliLang ||
+      cliProvider ||
+      cliModel ||
+      cliReasoning ||
+      split ||
+      splitCommand ||
+      splitPlanFile ||
+      dryRun ||
+      yes ||
+      configAction ||
+      policyAction ||
+      policyMessageFile ||
+      policyRange)
+  ) {
+    throw fail(ERROR_CATEGORIES.CONFIG, 'update accepts only --output and --debug options.');
+  }
 
   return {
     targetPath,
@@ -473,6 +498,7 @@ export function parseArgs(args = process.argv.slice(2)) {
     dryRun,
     yes,
     setup,
+    update,
     doctor,
     configAction,
     policyAction,

package/src/completion.js

@@ -1,5 +1,6 @@
 const TOP_LEVEL = [
   'setup',
+  'update',
   'doctor',
   'config',
   'policy',
@@ -51,6 +52,7 @@ _aicommit() {
   typeset -A opt_args
   commands=(
     'setup:interactive configuration wizard'
+    'update:update the global npm installation'
     'doctor:diagnose configuration and connectivity'
     'config:inspect or validate configuration'
     'policy:print or enforce a repository team policy'
@@ -94,6 +96,7 @@ _aicommit "$@"
 const FISH = `# fish completion for aicommit
 complete -c aicommit -f
 complete -c aicommit -n '__fish_use_subcommand' -a setup -d 'Interactive configuration wizard'
+complete -c aicommit -n '__fish_use_subcommand' -a update -d 'Update the global npm installation'
 complete -c aicommit -n '__fish_use_subcommand' -a doctor -d 'Diagnose configuration and connectivity'
 complete -c aicommit -n '__fish_use_subcommand' -a config -d 'Inspect or validate configuration'
 complete -c aicommit -n '__fish_use_subcommand' -a policy -d 'Print or enforce a repository team policy'

package/src/main.js

@@ -50,6 +50,7 @@ import { runDoctor } from './doctor.js';
 import { runConfigCommand } from './config-command.js';
 import { generateCompletion } from './completion.js';
 import { runPolicyCommand } from './policy-command.js';
+import { runUpdate } from './update.js';
 import {
   applyCommitlintPolicy,
   collectRepositoryContext,
@@ -97,6 +98,7 @@ async function runMain() {
     dryRun,
     yes,
     setup,
+    update,
     doctor,
     configAction,
     policyAction,
@@ -113,10 +115,12 @@ async function runMain() {
     return { exitReason: 'completion' };
   }
   const machineOutput = output === 'json';
-  if (machineOutput && !yes && !doctor && !configAction && !policyAction) {
+  if (machineOutput && !yes && !doctor && !configAction && !policyAction && !update) {
     throw fail(ERROR_CATEGORIES.CONFIG, '--output=json requires --yes for commit and split flows.');
   }
 
+  if (update) return runUpdate({ machineOutput, debug });
+
   // The setup wizard is a standalone flow — no git repo, diff, or loaded
   // config required.
   if (setup) {
@@ -513,12 +517,12 @@ async function runMain() {
               description:
                 'Omit sensitive files/private keys and redact detected credential values',
             },
-            { name: 'Cancel', value: 'cancel', description: 'Do not send repository content' },
             {
               name: 'Send original diff',
               value: 'original',
               description: 'Send the unredacted content to the configured provider',
             },
+            { name: 'Cancel', value: 'cancel', description: 'Do not send repository content' },
           ],
         });
     if (sensitiveAction === 'cancel') {

package/src/setup.js

@@ -74,9 +74,9 @@ export function mergeSetupConfig(existing, { providerName, entry, language }) {
 
 async function readExistingConfig(path) {
   if (!(await fileExists(path))) return {};
+  let parsed;
   try {
-    const parsed = JSON.parse(await readFile(path, 'utf-8'));
-    return validateUserConfig(parsed);
+    parsed = JSON.parse(await readFile(path, 'utf-8'));
   } catch (err) {
     const backup = `${path}.invalid-${Date.now()}.bak`;
     await copyFile(path, backup);
@@ -84,6 +84,16 @@ async function readExistingConfig(path) {
     console.log(chalk.dim(`    The original file was preserved at ${backup}.`));
     return {};
   }
+
+  try {
+    return validateUserConfig(parsed);
+  } catch (err) {
+    throw new Error(
+      `Existing config ${path} is valid JSON but has an unsupported structure: ${err.message} ` +
+        'Fix it or move it aside before running setup.',
+      { cause: err },
+    );
+  }
 }
 
 async function writeConfigAtomic(path, value) {

package/src/split.js

@@ -1518,12 +1518,12 @@ export async function splitFlow(
           description:
             'Protect model input only; sensitive files remain in the reviewed commit plan',
         },
-        { name: 'Cancel', value: 'cancel', description: 'Do not send repository content' },
         {
           name: 'Send original diff',
           value: 'original',
           description: 'Send the unredacted content to the configured provider',
         },
+        { name: 'Cancel', value: 'cancel', description: 'Do not send repository content' },
       ],
     });
     if (sensitiveAction === 'cancel') {

package/src/update.js

@@ -0,0 +1,326 @@
+import { spawnSync } from 'node:child_process';
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import chalk from 'chalk';
+
+import { ERROR_CATEGORIES, fail } from './errors.js';
+
+const require = createRequire(import.meta.url);
+const manifest = require('../package.json');
+
+export const PACKAGE_NAME = manifest.name;
+export const CURRENT_VERSION = manifest.version;
+
+const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const SEMVER =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+const NETWORK_CODES = new Set([
+  'ECONNRESET',
+  'ECONNREFUSED',
+  'EHOSTUNREACH',
+  'ENETUNREACH',
+  'ENOTFOUND',
+  'ETIMEDOUT',
+  'EAI_AGAIN',
+]);
+const PERMISSION_CODES = new Set(['EACCES', 'EPERM']);
+
+function parseVersion(version) {
+  const match = SEMVER.exec(version || '');
+  if (!match) throw new Error(`Invalid semantic version: ${version || '(empty)'}`);
+  const prerelease = match[4]?.split('.') || [];
+  if (prerelease.some((part) => /^\d+$/.test(part) && part.length > 1 && part.startsWith('0'))) {
+    throw new Error(`Invalid semantic version: ${version}`);
+  }
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease,
+  };
+}
+
+function compareIdentifiers(left, right) {
+  const leftNumeric = /^\d+$/.test(left);
+  const rightNumeric = /^\d+$/.test(right);
+  if (leftNumeric && rightNumeric) return Number(left) - Number(right);
+  if (leftNumeric) return -1;
+  if (rightNumeric) return 1;
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}
+
+export function compareVersions(leftVersion, rightVersion) {
+  const left = parseVersion(leftVersion);
+  const right = parseVersion(rightVersion);
+  for (const field of ['major', 'minor', 'patch']) {
+    if (left[field] !== right[field]) return left[field] - right[field];
+  }
+  if (left.prerelease.length === 0 && right.prerelease.length === 0) return 0;
+  if (left.prerelease.length === 0) return 1;
+  if (right.prerelease.length === 0) return -1;
+  const length = Math.max(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < length; index += 1) {
+    if (left.prerelease[index] === undefined) return -1;
+    if (right.prerelease[index] === undefined) return 1;
+    const comparison = compareIdentifiers(left.prerelease[index], right.prerelease[index]);
+    if (comparison !== 0) return comparison;
+  }
+  return 0;
+}
+
+function npmInvocation(args, platform = process.platform, env = process.env) {
+  if (platform !== 'win32') return { command: 'npm', args };
+  if (!args.every((arg) => /^[0-9A-Za-z@_./:-]+$/.test(arg))) {
+    throw new Error('Refusing to pass an unsafe argument to npm.cmd.');
+  }
+  return {
+    command: env.ComSpec || env.COMSPEC || 'cmd.exe',
+    args: ['/d', '/c', `npm.cmd ${args.join(' ')}`],
+  };
+}
+
+export function runNpm(args, options = {}) {
+  const platform = options.platform || process.platform;
+  const invocation = npmInvocation(args, platform, options.env || process.env);
+  return spawnSync(invocation.command, invocation.args, {
+    encoding: 'utf8',
+    env: options.env || process.env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: args[0] === 'install' ? 300_000 : 30_000,
+    windowsHide: true,
+  });
+}
+
+function resultText(result) {
+  return `${result?.stderr || ''}\n${result?.stdout || ''}`;
+}
+
+function npmErrorCode(result) {
+  const text = resultText(result);
+  const npmCode = /(?:npm ERR!|npm error)\s+code\s+([A-Z0-9_-]+)/i.exec(text)?.[1];
+  if (npmCode) return npmCode.toUpperCase();
+  return /\b(EACCES|EPERM|ECONNRESET|ECONNREFUSED|EHOSTUNREACH|ENETUNREACH|ENOTFOUND|ETIMEDOUT|EAI_AGAIN)\b/i
+    .exec(text)?.[1]
+    ?.toUpperCase();
+}
+
+function runCheckedNpm(args, runner, action, debug, log) {
+  if (debug) log(chalk.dim(`  npm ${args.join(' ')}`));
+  let result;
+  try {
+    result = runner(args);
+  } catch (error) {
+    throw fail(ERROR_CATEGORIES.CONFIG, `Unable to start npm while ${action}.`, { cause: error });
+  }
+  if (result?.error?.code === 'ENOENT') {
+    throw fail(
+      ERROR_CATEGORIES.CONFIG,
+      'npm is unavailable in PATH. Install npm or select the Node.js environment that installed aicommit.',
+      { cause: result.error },
+    );
+  }
+  if (result?.error) {
+    const category = NETWORK_CODES.has(result.error.code)
+      ? ERROR_CATEGORIES.NETWORK
+      : ERROR_CATEGORIES.CONFIG;
+    throw fail(category, `npm failed while ${action} (${result.error.code || 'unknown error'}).`, {
+      cause: result.error,
+    });
+  }
+  if (result?.status !== 0) {
+    const code = npmErrorCode(result);
+    if (PERMISSION_CODES.has(code)) {
+      throw fail(
+        ERROR_CATEGORIES.CONFIG,
+        `npm cannot write its global install directory (${code}). Fix npm global permissions and try again.`,
+      );
+    }
+    const category =
+      action === 'checking the registry' || NETWORK_CODES.has(code)
+        ? ERROR_CATEGORIES.NETWORK
+        : ERROR_CATEGORIES.CONFIG;
+    throw fail(
+      category,
+      `npm failed while ${action}${code ? ` (${code})` : ''}. ` +
+        (action === 'checking the registry'
+          ? 'Check the configured registry, authentication, proxy, and network connection.'
+          : `Run "npm install --global ${PACKAGE_NAME}@latest" manually for full npm diagnostics.`),
+    );
+  }
+  return String(result.stdout || '').trim();
+}
+
+function latestVersionFrom(output) {
+  let value;
+  try {
+    value = JSON.parse(output);
+  } catch (error) {
+    throw fail(ERROR_CATEGORIES.NETWORK, 'npm returned invalid metadata for the latest version.', {
+      cause: error,
+    });
+  }
+  if (typeof value !== 'string') {
+    throw fail(ERROR_CATEGORIES.NETWORK, 'npm returned invalid metadata for the latest version.');
+  }
+  try {
+    parseVersion(value);
+  } catch (error) {
+    throw fail(ERROR_CATEGORIES.NETWORK, `npm returned an invalid latest version: ${value}.`, {
+      cause: error,
+    });
+  }
+  return value;
+}
+
+function normalizedRealPath(path, platform) {
+  const value = realpathSync.native(path);
+  return platform === 'win32' ? value.toLowerCase() : value;
+}
+
+function assertActiveGlobalInstall(globalRoot, packageRoot, platform) {
+  const expectedPackageRoot = join(globalRoot, PACKAGE_NAME);
+  let expectedStat;
+  try {
+    expectedStat = lstatSync(expectedPackageRoot);
+  } catch (error) {
+    throw fail(
+      ERROR_CATEGORIES.CONFIG,
+      `Cannot safely self-update this installation. The active npm global root does not contain ${PACKAGE_NAME}. ` +
+        `Reinstall it with "npm install --global ${PACKAGE_NAME}@latest".`,
+      { cause: error },
+    );
+  }
+  if (expectedStat.isSymbolicLink()) {
+    throw fail(
+      ERROR_CATEGORIES.CONFIG,
+      'Cannot self-update an npm-linked source checkout. Update the checkout manually, or replace the link with a global npm installation.',
+    );
+  }
+  let activePath;
+  let currentPath;
+  try {
+    activePath = normalizedRealPath(expectedPackageRoot, platform);
+    currentPath = normalizedRealPath(packageRoot, platform);
+  } catch (error) {
+    throw fail(ERROR_CATEGORIES.CONFIG, 'Cannot resolve the active aicommit installation.', {
+      cause: error,
+    });
+  }
+  if (activePath !== currentPath) {
+    throw fail(
+      ERROR_CATEGORIES.CONFIG,
+      'Cannot safely self-update this installation because it belongs to a different Node.js or npm environment. ' +
+        `Activate the environment that installed it, or run "npm install --global ${PACKAGE_NAME}@latest" manually.`,
+    );
+  }
+}
+
+function installedVersion(packageRoot) {
+  try {
+    const value = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).version;
+    parseVersion(value);
+    return value;
+  } catch (error) {
+    throw fail(
+      ERROR_CATEGORIES.INTERNAL,
+      'The npm update finished, but the installed aicommit version could not be verified.',
+      { cause: error },
+    );
+  }
+}
+
+export function runUpdate(options = {}) {
+  const currentVersion = options.currentVersion || CURRENT_VERSION;
+  const packageRoot = options.packageRoot || PACKAGE_ROOT;
+  const platform = options.platform || process.platform;
+  const runner = options.runner || ((args) => runNpm(args, { platform }));
+  const log = options.log || console.log;
+  const debug = Boolean(options.debug);
+
+  parseVersion(currentVersion);
+  log('');
+  log('  ' + chalk.cyan.bold('Update aicommit'));
+  log('  ' + chalk.dim('─'.repeat(45)));
+  log(chalk.dim('  Checking the npm registry...'));
+
+  const latestVersion = latestVersionFrom(
+    runCheckedNpm(
+      ['view', PACKAGE_NAME, 'dist-tags.latest', '--json'],
+      runner,
+      'checking the registry',
+      debug,
+      log,
+    ),
+  );
+  log(`  Current version: ${chalk.bold(currentVersion)}`);
+  log(`  Latest version:  ${chalk.bold(latestVersion)}`);
+
+  const comparison = compareVersions(currentVersion, latestVersion);
+  if (comparison >= 0) {
+    const newer = comparison > 0;
+    const message = newer
+      ? `aicommit ${currentVersion} is newer than npm latest ${latestVersion}.`
+      : `aicommit ${currentVersion} is already up to date.`;
+    log('\n  ' + chalk.green('✓') + ` ${message}\n`);
+    return {
+      message,
+      warnings: [],
+      exitReason: newer ? 'newer_than_latest' : 'up_to_date',
+      committed: false,
+      data: {
+        packageName: PACKAGE_NAME,
+        currentVersion,
+        latestVersion,
+        installedVersion: currentVersion,
+        updated: false,
+      },
+    };
+  }
+
+  const globalRoot = runCheckedNpm(
+    ['root', '--global'],
+    runner,
+    'locating the global installation',
+    debug,
+    log,
+  );
+  assertActiveGlobalInstall(globalRoot, packageRoot, platform);
+
+  log(chalk.dim(`\n  Installing ${PACKAGE_NAME}@${latestVersion}...`));
+  runCheckedNpm(
+    ['install', '--global', `${PACKAGE_NAME}@${latestVersion}`, '--no-audit', '--no-fund'],
+    runner,
+    'installing the update',
+    debug,
+    log,
+  );
+
+  const verifiedVersion = installedVersion(packageRoot);
+  if (verifiedVersion !== latestVersion) {
+    throw fail(
+      ERROR_CATEGORIES.INTERNAL,
+      `npm completed, but aicommit is still at ${verifiedVersion} instead of ${latestVersion}. ` +
+        'Check which aicommit executable is first in PATH.',
+    );
+  }
+
+  const message = `Updated aicommit from ${currentVersion} to ${verifiedVersion}.`;
+  log('\n  ' + chalk.green('✓') + ` ${message}\n`);
+  return {
+    message,
+    warnings: [],
+    exitReason: 'updated',
+    committed: false,
+    data: {
+      packageName: PACKAGE_NAME,
+      currentVersion,
+      latestVersion,
+      installedVersion: verifiedVersion,
+      updated: true,
+    },
+  };
+}