{"_id":"@ark-x/upgear","name":"@ark-x/upgear","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@ark-x/upgear","version":"0.0.1","description":"check and update global npm packages with beautiful CLI interface","keywords":["npm","update","upgrade","cli","version-check"],"license":"MIT","author":{"name":"Derrick","email":"chens.cls@gmail.com"},"type":"module","main":"./dist/index.mjs","types":"./dist/index.d.ts","source":"./src/index.ts","bin":{"ark-x-upgear":"dist/cli.mjs","ax-upgear":"dist/cli.mjs"},"dependencies":{"execa":"^9.5.2","picocolors":"^1.1.1","semver":"^7.6.3","yargs-parser":"^21.1.1","@ark-x/prompt":"^0.0.1"},"devDependencies":{"@types/semver":"^7.5.8","@types/yargs-parser":"^21.0.3","typescript":"^5.0.0"},"publishConfig":{"access":"public"},"scripts":{"build:type":"tsc --project tsconfig.json --emitDeclarationOnly --declarationDir dist-dts","build:cli":"bun build src/bin.ts --external react-devtools-core --minify --outfile dist/cli.mjs --target=node","build:index":"bun build src/index.ts --external react-devtools-core --minify --outfile dist/index.mjs --target=node","build":"rm -rf dist && npm run build:cli && npm run build:index && npm run build:dts","build:dts":"npm run build:type && api-extractor run --local --verbose","dev":"bun ./src/bin.ts","typecheck":"tsc --noEmit"},"_id":"@ark-x/upgear@0.0.1","_integrity":"sha512-TLtI8+9wwD9WkPKxJycngVi7YiqNC5zriyYS3IAqsq9b0y93yHcgxq+Hp7sCiBO+HvV1e/nFTZ4uqLzuG80OUA==","_resolved":"/private/var/folders/j8/d46gh41n3sjc04g_v9lxvq680000gn/T/ed5df590df96475ced61592f0de6e713/ark-x-upgear-0.0.1.tgz","_from":"file:ark-x-upgear-0.0.1.tgz","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-TLtI8+9wwD9WkPKxJycngVi7YiqNC5zriyYS3IAqsq9b0y93yHcgxq+Hp7sCiBO+HvV1e/nFTZ4uqLzuG80OUA==","shasum":"34bd7109570c432e3202f2f0dbdf9836832caaad","tarball":"https://registry.npmjs.org/@ark-x/upgear/-/upgear-0.0.1.tgz","fileCount":6,"unpackedSize":480407,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIG/+Hj/CASz64MlRFKD5zBZGHCt8PC0RBUhuKthTMhKbAiB3nSx7IKsQ9Enz/eEnXnOcGWbOO3XDptT0A9+5frXpCg=="}]},"_npmUser":{"name":"nu1nux","email":"nu1nux@outlook.com"},"directories":{},"maintainers":[{"name":"nu1nux","email":"nu1nux@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/upgear_0.0.1_1761446007564_0.00567332376993801"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-26T02:33:27.509Z","0.0.1":"2025-10-26T02:33:27.840Z","modified":"2025-10-26T02:33:28.135Z"},"maintainers":[{"name":"nu1nux","email":"nu1nux@outlook.com"}],"description":"check and update global npm packages with beautiful CLI interface","keywords":["npm","update","upgrade","cli","version-check"],"author":{"name":"Derrick","email":"chens.cls@gmail.com"},"license":"MIT","readme":"# @ark-x/ear\n\n一个优雅的全局 npm 包更新检查和管理工具，提供美观的交互式 CLI 界面。\n\n## 特性\n\n- ✅ 检查全局 npm 包的版本更新\n- ✅ 交互式选择要更新的包\n- ✅ 实时显示更新进度\n- ✅ 支持程序化 API 和 CLI 两种使用方式\n- ✅ 完善的错误处理和重试机制\n- ✅ 美观的终端 UI（基于 @ark-x/mpt）\n\n## 安装\n\n```bash\n# 全局安装（推荐）\nnpm install -g @ark-x/ear\n\n# 或作为项目依赖\npnpm add @ark-x/ear\n```\n\n## 快速开始\n\n### 全局命令使用（推荐）\n\n安装后可直接使用 `ark-upgear` 命令：\n\n```bash\n# 使用默认配置检查更新\nark-upgear\n\n# 指定要检查的包\nark-upgear -p @ark-x/e,codex\n\n# 自动更新模式（不询问）\nark-upgear --auto\n\n# 同时指定包和自动更新\nark-upgear -p typescript,eslint --auto\n\n# 查看帮助\nark-upgear --help\n\n# 查看版本\nark-upgear --version\n```\n\n**命令行参数：**\n\n| 参数                | 别名 | 类型    | 默认值                              | 说明                             |\n| ------------------- | ---- | ------- | ----------------------------------- | -------------------------------- |\n| `--packages`        | `-p` | string  | `@ark-x/e,@google/gemini-cli,codex` | 要检查的包（逗号分隔）           |\n| `--auto`            | `-a` | boolean | `false`                             | 自动更新（跳过确认）             |\n| `--global`          | `-g` | boolean | `true`                              | 检查全局包                       |\n| `--location`        | `-l` | string  | -                                   | 安装位置 (global\\|project\\|both) |\n| `--ask-location`    | -    | boolean | `true`                              | 是否询问安装位置                 |\n| `--no-ask-location` | -    | boolean | -                                   | 不询问安装位置                   |\n| `--help`            | `-h` | boolean | -                                   | 显示帮助信息                     |\n| `--version`         | `-v` | boolean | -                                   | 显示版本号                       |\n\n**安装位置选项示例：**\n\n```bash\n# 默认行为：会询问用户选择安装位置\nark-upgear\n\n# 直接指定全局安装\nark-upgear -l global\n\n# 直接指定项目依赖安装\nark-upgear -l project\n\n# 同时安装到全局和项目\nark-upgear -l both\n\n# 不询问，使用默认全局安装\nark-upgear --no-ask-location\n```\n\n### 作为独立脚本使用\n\n创建一个 `check-updates.ts` 或 `check-updates.js` 文件：\n\n```typescript\nimport { upgear } from \"@ark-x/ear\";\n\n// 检查默认包的更新\nupgear();\n```\n\n运行脚本：\n\n```bash\n# 使用 tsx（推荐）\nnpx tsx check-updates.ts\n\n# 或使用 ts-node\nnpx ts-node check-updates.ts\n\n# 或使用 Node.js（需要先构建）\nnode check-updates.js\n```\n\n### 在项目中集成\n\n```typescript\nimport { upgear } from \"@ark-x/ear\";\n\nasync function main() {\n  // 在你的 CLI 工具启动时检查更新\n  await upgear({\n    packages: [\"@ark-x/e\", \"@google/gemini-cli\", \"codex\"],\n    autoUpdate: false,\n  });\n\n  // 继续你的主要逻辑\n  console.log(\"开始执行主要任务...\");\n}\n\nmain();\n```\n\n## 使用\n\n### 交互式 CLI\n\n```typescript\nimport { upgear } from \"@ark-x/ear\";\n\n// 使用默认配置\nawait upgear();\n\n// 自定义配置\nawait upgear({\n  packages: [\"@ark-x/e\", \"@google/gemini-cli\", \"codex\"],\n  autoUpdate: false, // 是否自动更新（不询问）\n  global: true, // 检查全局包\n});\n```\n\n**CLI 交互流程示例：**\n\n```\n┌  upgear\n│\n◇  检查完成\n│\n│  发现 2 个可更新的包\n│  ↑ @ark-x/e: 1.0.0 → 1.2.0\n│  ↑ gemini-cli: 2.1.0 → 2.3.1\n│  ✓ codex: 0.5.0\n│\n◆  选择要更新的包:\n│  ◼ @ark-x/e (1.0.0 → 1.2.0)\n│  ◼ gemini-cli (2.1.0 → 2.3.1)\n│\n◆  选择安装位置:\n│  ○ 全局安装 (npm install -g)\n│  ● 项目依赖 (npm install)\n│  ○ 两者都安装\n│\n◇  正在项目安装 @ark-x/e...\n◇  正在项目安装 gemini-cli...\n│\n└  更新完成\n```\n\n### 程序化 API\n\n#### 检查更新\n\n```typescript\nimport { checkUpdate, checkUpdates } from \"@ark-x/ear\";\n\n// 检查单个包\nconst updateInfo = await checkUpdate(\"@ark-x/e\");\nconsole.log(updateInfo);\n// {\n//   name: '@ark-x/e',\n//   currentVersion: '1.0.0',\n//   latestVersion: '1.2.0',\n//   needsUpdate: true\n// }\n\n// 批量检查多个包\nconst updates = await checkUpdates([\"@ark-x/e\", \"@google/gemini-cli\", \"codex\"]);\n```\n\n#### 执行更新\n\n```typescript\nimport { updatePackage, updatePackages } from \"@ark-x/ear\";\n\n// 更新单个包\nawait updatePackage(\"@ark-x/e\", true);\n\n// 批量更新包（带进度回调）\nawait updatePackages(updates, true, (result) => {\n  console.log(`${result.package}: ${result.status}`);\n});\n```\n\n## API\n\n### `upgear(options?: UpgearOptions): Promise<void>`\n\n交互式 CLI 入口，会展示美观的 UI 并引导用户选择要更新的包。\n\n**UpgearOptions:**\n\n```typescript\ninterface UpgearOptions {\n  packages?: string[]; // 要检查的包列表，默认: ['@ark-x/e', '@google/gemini-cli', 'codex']\n  global?: boolean; // 是否检查全局包，默认: true\n  autoUpdate?: boolean; // 是否自动更新（跳过确认），默认: false\n  silent?: boolean; // 静默模式，默认: false\n  askLocation?: boolean; // 是否询问安装位置，默认: true\n  installLocation?: InstallLocation; // 安装位置 ('global' | 'project' | 'both')\n}\n```\n\n### `checkUpdate(packageName: string, global?: boolean): Promise<UpdateInfo>`\n\n检查单个包的更新信息。\n\n**返回值:**\n\n```typescript\ninterface UpdateInfo {\n  name: string; // 包名\n  currentVersion: string | null; // 当前版本（未安装时为 null）\n  latestVersion: string; // 最新版本\n  needsUpdate: boolean; // 是否需要更新\n}\n```\n\n### `checkUpdates(packages: string[], global?: boolean): Promise<UpdateInfo[]>`\n\n批量检查多个包的更新信息。\n\n### `updatePackage(packageName: string, global?: boolean, onProgress?: (data: string) => void): Promise<void>`\n\n更新单个包。\n\n### `updatePackages(updates: UpdateInfo[], global?: boolean, onProgress?: (result: UpdateResult) => void): Promise<UpdateResult[]>`\n\n批量更新包，支持进度回调。\n\n**UpdateResult:**\n\n```typescript\ninterface UpdateResult {\n  package: string; // 包名\n  status: \"pending\" | \"updating\" | \"success\" | \"error\"; // 状态\n  error?: string; // 错误信息（失败时）\n}\n```\n\n## 常量\n\n```typescript\nimport { DEFAULT_PACKAGES, DEFAULT_OPTIONS, MESSAGES } from \"@ark-x/ear\";\n\n// 默认检查的包列表\nDEFAULT_PACKAGES; // ['@ark-x/e', '@google/gemini-cli', 'codex']\n\n// 默认配置\nDEFAULT_OPTIONS; // { packages: DEFAULT_PACKAGES, global: true, autoUpdate: false, silent: false }\n\n// 消息文本\nMESSAGES; // { CHECKING_START, UPDATE_SUCCESS, ... }\n```\n\n## 错误处理\n\nupgear 内置了完善的错误处理机制：\n\n- **网络错误**: 自动重试 3 次（间隔 1 秒）\n- **权限错误**: 提示使用 sudo（macOS/Linux）\n- **npm 不存在**: 提示安装 Node.js\n- **包不存在**: 友好的错误提示\n\n## 使用场景\n\n### 场景 1: 定期检查工具更新\n\n在 CLI 工具启动时自动检查更新：\n\n```typescript\n#!/usr/bin/env node\nimport { upgear } from \"@ark-x/ear\";\n\nasync function main() {\n  // 检查工具本身的更新\n  await upgear({\n    packages: [\"your-cli-tool\"],\n    autoUpdate: false,\n  });\n\n  // 继续执行工具的主要功能\n  console.log(\"工具正在运行...\");\n}\n\nmain();\n```\n\n### 场景 2: 批量检查多个工具\n\n```typescript\nimport { upgear } from \"@ark-x/ear\";\n\n// 一次性检查所有全局开发工具\nawait upgear({\n  packages: [\n    \"@ark-x/e\",\n    \"@google/gemini-cli\",\n    \"codex\",\n    \"typescript\",\n    \"eslint\",\n    \"prettier\",\n  ],\n});\n```\n\n### 场景 3: 自动化更新（CI/CD）\n\n```typescript\nimport { checkUpdates, updatePackages } from \"@ark-x/ear\";\n\nasync function autoUpdate() {\n  const updates = await checkUpdates([\"eslint\", \"typescript\"]);\n  const outdated = updates.filter((u) => u.needsUpdate);\n\n  if (outdated.length > 0) {\n    console.log(`发现 ${outdated.length} 个过期的包`);\n\n    // 在 CI 环境中自动更新\n    if (process.env.CI) {\n      await updatePackages(outdated);\n    } else {\n      // 本地环境提示\n      outdated.forEach((u) => {\n        console.log(`  ${u.name}: ${u.currentVersion} → ${u.latestVersion}`);\n      });\n    }\n  }\n}\n```\n\n### 场景 4: 指定安装位置\n\n```typescript\nimport { upgear } from \"@ark-x/ear\";\n\n// 直接安装到项目依赖，不询问\nawait upgear({\n  packages: [\"typescript\", \"eslint\"],\n  installLocation: \"project\",\n  askLocation: false,\n});\n\n// 同时安装到全局和项目\nawait upgear({\n  packages: [\"prettier\"],\n  installLocation: \"both\",\n  askLocation: false,\n});\n```\n\n### 场景 5: 静默检查（仅获取信息）\n\n```typescript\nimport { checkUpdate } from \"@ark-x/ear\";\n\nasync function checkSilently() {\n  try {\n    const info = await checkUpdate(\"@ark-x/e\");\n\n    if (info.needsUpdate) {\n      console.log(`新版本可用: ${info.latestVersion}`);\n      console.log(\"运行更新命令: npm install -g @ark-x/e\");\n    } else {\n      console.log(\"已是最新版本\");\n    }\n  } catch (error) {\n    console.error(\"检查更新失败:\", error);\n  }\n}\n```\n\n### 场景 6: package.json scripts 集成\n\n在 `package.json` 中添加更新检查脚本：\n\n```json\n{\n  \"scripts\": {\n    \"check-updates\": \"ark-upgear\",\n    \"check-updates:project\": \"ark-upgear -l project\",\n    \"check-updates:custom\": \"ark-upgear -p typescript,eslint,prettier\",\n    \"update-tools\": \"ark-upgear --auto -l global\"\n  }\n}\n```\n\n或者使用脚本文件 `scripts/check-updates.ts`:\n\n```typescript\nimport { upgear } from \"@ark-x/ear\";\n\nupgear({\n  packages: [\"@ark-x/e\", \"@google/gemini-cli\", \"codex\"],\n  autoUpdate: false,\n  installLocation: \"project\", // 默认安装到项目\n});\n```\n\n然后运行：\n\n```bash\n# 使用全局命令\npnpm run check-updates\n\n# 或使用脚本\npnpm run check-updates:project\n```\n\n### 场景 7: 使用全局命令快速检查\n\n```bash\n# 快速检查默认工具的更新\nark-upgear\n\n# 检查特定工具\nark-upgear -p typescript,eslint\n\n# 定时任务（crontab）\n0 9 * * * /usr/local/bin/ark-upgear --auto > /tmp/upgear.log 2>&1\n```\n\n## 依赖\n\n- [@ark-x/mpt](../ark-prompt): 提供美观的交互式 CLI 组件\n- [execa](https://github.com/sindresorhus/execa): 更好的子进程执行\n- [semver](https://github.com/npm/node-semver): 语义化版本比较\n- [picocolors](https://github.com/alexeyraspopov/picocolors): 轻量级终端颜色\n\n## License\n\nMIT © Derrick\n","readmeFilename":"README.md","_rev":"1-e5efb851282e1722ae35f83ba1f6772d"}