@ark-code/upgear

一个优雅的全局 npm 包更新检查和管理工具，提供美观的交互式 CLI 界面。

特性

• ✅ 检查全局 npm 包的版本更新
• ✅ 交互式选择要更新的包
• ✅ 实时显示更新进度
• ✅ 支持程序化 API 和 CLI 两种使用方式
• ✅ 完善的错误处理和重试机制
• ✅ 美观的终端 UI（基于 @ark-code/prompt）

安装

# 全局安装（推荐）
npm install -g @ark-code/upgear

# 或作为项目依赖
pnpm add @ark-code/upgear

快速开始

全局命令使用（推荐）

安装后可直接使用 ark-upgear 命令：

# 使用默认配置检查更新
ark-upgear

# 指定要检查的包
ark-upgear -p @ark-code/core,codex

# 自动更新模式（不询问）
ark-upgear --auto

# 同时指定包和自动更新
ark-upgear -p typescript,eslint --auto

# 查看帮助
ark-upgear --help

# 查看版本
ark-upgear --version

命令行参数：

| 参数 | 别名 | 类型 | 默认值 | 说明 | | ------------------- | ---- | ------- | ----------------------------------------- | -------------------------------- | | --packages | -p | string | @ark-code/core,@google/gemini-cli,codex | 要检查的包（逗号分隔） | | --auto | -a | boolean | false | 自动更新（跳过确认） | | --global | -g | boolean | true | 检查全局包 | | --location | -l | string | - | 安装位置 (global|project|both) | | --ask-location | - | boolean | true | 是否询问安装位置 | | --no-ask-location | - | boolean | - | 不询问安装位置 | | --help | -h | boolean | - | 显示帮助信息 | | --version | -v | boolean | - | 显示版本号 |

安装位置选项示例：

# 默认行为：会询问用户选择安装位置
ark-upgear

# 直接指定全局安装
ark-upgear -l global

# 直接指定项目依赖安装
ark-upgear -l project

# 同时安装到全局和项目
ark-upgear -l both

# 不询问，使用默认全局安装
ark-upgear --no-ask-location

作为独立脚本使用

创建一个 check-updates.ts 或 check-updates.js 文件：

import { upgear } from "@ark-code/upgear";

// 检查默认包的更新
upgear();

运行脚本：

# 使用 tsx（推荐）
npx tsx check-updates.ts

# 或使用 ts-node
npx ts-node check-updates.ts

# 或使用 Node.js（需要先构建）
node check-updates.js

在项目中集成

import { upgear } from "@ark-code/upgear";

async function main() {
  // 在你的 CLI 工具启动时检查更新
  await upgear({
    packages: ["@ark-code/core", "@google/gemini-cli", "codex"],
    autoUpdate: false,
  });

  // 继续你的主要逻辑
  console.log("开始执行主要任务...");
}

main();

使用

交互式 CLI

import { upgear } from "@ark-code/upgear";

// 使用默认配置
await upgear();

// 自定义配置
await upgear({
  packages: ["@ark-code/core", "@google/gemini-cli", "codex"],
  autoUpdate: false, // 是否自动更新（不询问）
  global: true, // 检查全局包
});

CLI 交互流程示例：

┌  upgear
│
◇  检查完成
│
│  发现 2 个可更新的包
│  ↑ @ark-code/core: 1.0.0 → 1.2.0
│  ↑ gemini-cli: 2.1.0 → 2.3.1
│  ✓ codex: 0.5.0
│
◆  选择要更新的包:
│  ◼ @ark-code/core (1.0.0 → 1.2.0)
│  ◼ gemini-cli (2.1.0 → 2.3.1)
│
◆  选择安装位置:
│  ○ 全局安装 (npm install -g)
│  ● 项目依赖 (npm install)
│  ○ 两者都安装
│
◇  正在项目安装 @ark-code/core...
◇  正在项目安装 gemini-cli...
│
└  更新完成

程序化 API

检查更新

import { checkUpdate, checkUpdates } from "@ark-code/upgear";

// 检查单个包
const updateInfo = await checkUpdate("@ark-code/core");
console.log(updateInfo);
// {
//   name: '@ark-code/core',
//   currentVersion: '1.0.0',
//   latestVersion: '1.2.0',
//   needsUpdate: true
// }

// 批量检查多个包
const updates = await checkUpdates([
  "@ark-code/core",
  "@google/gemini-cli",
  "codex",
]);

执行更新

import { updatePackage, updatePackages } from "@ark-code/upgear";

// 更新单个包
await updatePackage("@ark-code/core", true);

// 批量更新包（带进度回调）
await updatePackages(updates, true, (result) => {
  console.log(`${result.package}: ${result.status}`);
});

API

upgear(options?: UpgearOptions): Promise<void>

交互式 CLI 入口，会展示美观的 UI 并引导用户选择要更新的包。

UpgearOptions:

interface UpgearOptions {
  packages?: string[]; // 要检查的包列表，默认: ['@ark-code/core', '@google/gemini-cli', 'codex']
  global?: boolean; // 是否检查全局包，默认: true
  autoUpdate?: boolean; // 是否自动更新（跳过确认），默认: false
  silent?: boolean; // 静默模式，默认: false
  askLocation?: boolean; // 是否询问安装位置，默认: true
  installLocation?: InstallLocation; // 安装位置 ('global' | 'project' | 'both')
}

checkUpdate(packageName: string, global?: boolean): Promise<UpdateInfo>

检查单个包的更新信息。

返回值:

interface UpdateInfo {
  name: string; // 包名
  currentVersion: string | null; // 当前版本（未安装时为 null）
  latestVersion: string; // 最新版本
  needsUpdate: boolean; // 是否需要更新
}

checkUpdates(packages: string[], global?: boolean): Promise<UpdateInfo[]>

批量检查多个包的更新信息。

updatePackage(packageName: string, global?: boolean, onProgress?: (data: string) => void): Promise<void>

更新单个包。

updatePackages(updates: UpdateInfo[], global?: boolean, onProgress?: (result: UpdateResult) => void): Promise<UpdateResult[]>

批量更新包，支持进度回调。

UpdateResult:

interface UpdateResult {
  package: string; // 包名
  status: "pending" | "updating" | "success" | "error"; // 状态
  error?: string; // 错误信息（失败时）
}

常量

import { DEFAULT_PACKAGES, DEFAULT_OPTIONS, MESSAGES } from "@ark-code/upgear";

// 默认检查的包列表
DEFAULT_PACKAGES; // ['@ark-code/core', '@google/gemini-cli', 'codex']

// 默认配置
DEFAULT_OPTIONS; // { packages: DEFAULT_PACKAGES, global: true, autoUpdate: false, silent: false }

// 消息文本
MESSAGES; // { CHECKING_START, UPDATE_SUCCESS, ... }

错误处理

upgear 内置了完善的错误处理机制：

• 网络错误: 自动重试 3 次（间隔 1 秒）
• 权限错误: 提示使用 sudo（macOS/Linux）
• npm 不存在: 提示安装 Node.js
• 包不存在: 友好的错误提示

使用场景

场景 1: 定期检查工具更新

在 CLI 工具启动时自动检查更新：

#!/usr/bin/env node
import { upgear } from "@ark-code/upgear";

async function main() {
  // 检查工具本身的更新
  await upgear({
    packages: ["your-cli-tool"],
    autoUpdate: false,
  });

  // 继续执行工具的主要功能
  console.log("工具正在运行...");
}

main();

场景 2: 批量检查多个工具

import { upgear } from "@ark-code/upgear";

// 一次性检查所有全局开发工具
await upgear({
  packages: [
    "@ark-code/core",
    "@google/gemini-cli",
    "codex",
    "typescript",
    "eslint",
    "prettier",
  ],
});

场景 3: 自动化更新（CI/CD）

import { checkUpdates, updatePackages } from "@ark-code/upgear";

async function autoUpdate() {
  const updates = await checkUpdates(["eslint", "typescript"]);
  const outdated = updates.filter((u) => u.needsUpdate);

  if (outdated.length > 0) {
    console.log(`发现 ${outdated.length} 个过期的包`);

    // 在 CI 环境中自动更新
    if (process.env.CI) {
      await updatePackages(outdated);
    } else {
      // 本地环境提示
      outdated.forEach((u) => {
        console.log(`  ${u.name}: ${u.currentVersion} → ${u.latestVersion}`);
      });
    }
  }
}

场景 4: 指定安装位置

import { upgear } from "@ark-code/upgear";

// 直接安装到项目依赖，不询问
await upgear({
  packages: ["typescript", "eslint"],
  installLocation: "project",
  askLocation: false,
});

// 同时安装到全局和项目
await upgear({
  packages: ["prettier"],
  installLocation: "both",
  askLocation: false,
});

场景 5: 静默检查（仅获取信息）

import { checkUpdate } from "@ark-code/upgear";

async function checkSilently() {
  try {
    const info = await checkUpdate("@ark-code/core");

    if (info.needsUpdate) {
      console.log(`新版本可用: ${info.latestVersion}`);
      console.log("运行更新命令: npm install -g @ark-code/core");
    } else {
      console.log("已是最新版本");
    }
  } catch (error) {
    console.error("检查更新失败:", error);
  }
}

场景 6: package.json scripts 集成

在 package.json 中添加更新检查脚本：

{
  "scripts": {
    "check-updates": "ark-upgear",
    "check-updates:project": "ark-upgear -l project",
    "check-updates:custom": "ark-upgear -p typescript,eslint,prettier",
    "update-tools": "ark-upgear --auto -l global"
  }
}

或者使用脚本文件 scripts/check-updates.ts:

import { upgear } from "@ark-code/upgear";

upgear({
  packages: ["@ark-code/core", "@google/gemini-cli", "codex"],
  autoUpdate: false,
  installLocation: "project", // 默认安装到项目
});

然后运行：

# 使用全局命令
pnpm run check-updates

# 或使用脚本
pnpm run check-updates:project

场景 7: 使用全局命令快速检查

# 快速检查默认工具的更新
ark-upgear

# 检查特定工具
ark-upgear -p typescript,eslint

# 定时任务（crontab）
0 9 * * * /usr/local/bin/ark-upgear --auto > /tmp/upgear.log 2>&1

依赖

• @ark-code/prompt: 提供美观的交互式 CLI 组件
• execa: 更好的子进程执行
• semver: 语义化版本比较
• picocolors: 轻量级终端颜色

License

MIT © Derrick