fix(ccr): detect installed version without running CCR

[WitMiao]

Description

• Read the installed @musistudio/claude-code-router version from the active command path and its matching package.json.
• Cover Unix npm/fnm/nvm symlinks and Windows npm .cmd shims without invoking the CCR CLI.
• Fix the false “CCR is not installed” result for CCR 3.0.21.
• Eliminate the high-risk CCR 3.x probe side effect: ccr -v, ccr --version, or other version-like arguments can be treated as profiles and rewrite the user’s global Codex config before profile validation.
• Keep Claude Code and CCometixLine version detection unchanged.

Fixes #377

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Testing

• Tests added/updated
• All tests pass
• Coverage maintained

Validation performed:

• pnpm vitest run tests/unit/utils/ccr-version-detection.test.ts tests/unit/utils/version-checker.test.ts tests/unit/utils/auto-updater.test.ts tests/commands/check-updates.test.ts — 120 tests passed
• pnpm typecheck — passed
• pnpm lint — passed
• pnpm test:run — 145 files, 2552 tests passed
• pnpm build — passed
• Local read-only package metadata check detected CCR 3.0.21 without executing ccr
• GitHub CI — lint, Ubuntu, macOS, Windows, and Codecov patch checks passed

Checklist

• Code follows style guidelines
• Self-review completed
• Documentation updated (not applicable: no user-facing contract changed)
• No new warnings introduced

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-31T02:49:20.964296Z	08163ef	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Detect CCR version safely from installed package metadata

🐞 Bug fix 🧪 Tests 🕐 20-40 Minutes

AI Description

• Reads CCR versions from package metadata instead of executing unsafe CLI probes.
• Supports active Unix symlinks and Windows npm shims across common installation layouts.
• Adds regression coverage for CCR 3.0.21 detection and Codex configuration safety.

Diagram

graph TD
  A["Update Check"] --> B["CCR Version Check"] --> C["Command Locator"] --> D["Metadata Paths"] --> E[("package.json")] --> F["Semver Validation"] --> G["Version Result"]
  B --> H["npm Registry"] --> G

Loading

High-Level Assessment

The package-metadata approach is the safest fit because it follows the active command installation while avoiding CCR execution entirely. CLI flag probing was rejected due to CCR 3.x configuration side effects, while relying on a global npm root command could inspect a different installation than the executable selected by PATH.

Files changed (3) +240 / -8

Bug fix (1) +71 / -2

version-checker.tsResolve CCR versions from local package metadata +71/-2

Resolve CCR versions from local package metadata

• Adds CCR-specific installed-version detection that resolves the active command, searches matching npm package metadata, and validates package identity and semantic version. 'checkCcrVersion' now uses this read-only path while retaining npm lookup for the latest release and leaving generic tool detection unchanged.

src/utils/version-checker.ts

Tests (2) +169 / -6

ccr-version-detection.test.tsCover safe CCR detection across npm installation layouts +148/-0

Cover safe CCR detection across npm installation layouts

• Adds isolated filesystem regressions for fnm-style Unix symlinks and Windows npm '.cmd' shims. The command-level check verifies CCR 3.0.21 is reported as installed without executing CCR or creating Codex configuration artifacts.

tests/unit/utils/ccr-version-detection.test.ts

version-checker.test.tsAdapt version-checker tests to metadata-based CCR lookup +21/-6

Adapt version-checker tests to metadata-based CCR lookup

• Extends filesystem mocks for package metadata and realpath resolution, then verifies installed CCR comparison using a resolved package.json. The generic version fallback test now uses a neutral tool command so CCR-specific behavior remains isolated.

tests/unit/utils/version-checker.test.ts

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. where path retains carriage return ✓ Resolved 📎 Requirement gap ≡ Correctness

Description

When Windows where ccr returns multiple CRLF-separated matches, findCommandPath() leaves \r on
the selected first path; the new metadata lookup then builds unreadable paths and falsely reports an
installed CCR as absent. This violates both installed-CCR detection and supported Windows behavior.

Code

src/utils/version-checker.ts[70]

+  for (const packageJsonPath of getPackageJsonPaths(commandPath)) {

Evidence

Rule 1 requires installed CCR to remain detectable, and Rule 10 requires Windows compatibility.
findCommandPath() splits Windows where output only on \n, while the newly introduced line 70
consumes that path for filesystem metadata discovery; with multiple CRLF results, the first path
ends in \r, realpathSync() fails, fallback paths are malformed, and getCcrInstalledVersion()
returns null.

检测已安装的 CCR
CLAUDE.md: Preserve Cross-Platform Compatibility: CLAUDE.md: Preserve Cross-Platform Compatibility: CLAUDE.md: Preserve Cross-Platform Compatibility: CLAUDE.md: Preserve Cross-Platform Compatibility
src/utils/platform.ts[376-383]
src/utils/version-checker.ts[30-54]
src/utils/version-checker.ts[65-76]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Windows `where` can return multiple CRLF-separated matches. The selected first command path retains a carriage return, causing CCR package metadata resolution to fail.
## Issue Context
Normalize the selected line in `findCommandPath()` before returning it, and add a regression test covering multiple Windows `where` results so the active CCR installation remains detectable.
## Fix Focus Areas
- src/utils/platform.ts[379-383]
- tests/unit/utils/ccr-version-detection.test.ts[117-126]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Path operations bypass pathe ✓ Resolved 📘 Rule violation ⚙ Maintainability

Description

The new CCR path traversal imports dirname and join from node:path, even though the
cross-platform rule explicitly requires the repository's established pathe abstraction. This
introduces the sole node:path import under src/ and makes the new platform-sensitive code
inconsistent with the project convention.

Code

src/utils/version-checker.ts[3]

+import { dirname, join } from 'node:path'

Evidence

Rule 10's success criteria explicitly require path operations to use pathe. The changed import
uses node:path, while the repository's platform utility demonstrates the established pathe
import for path handling.

CLAUDE.md: Preserve Cross-Platform Compatibility: CLAUDE.md: Preserve Cross-Platform Compatibility: CLAUDE.md: Preserve Cross-Platform Compatibility: CLAUDE.md: Preserve Cross-Platform Compatibility
src/utils/version-checker.ts[3-3]
src/utils/version-checker.ts[30-54]
src/utils/platform.ts[1-5]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new cross-platform CCR metadata lookup bypasses the required `pathe` path abstraction by importing from `node:path`.
## Issue Context
Use the repository's existing `pathe` dependency for `dirname` and `join`, preserving the current behavior and typings.
## Fix Focus Areas
- src/utils/version-checker.ts[3-3]
- src/utils/version-checker.ts[30-54]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can type 'qodo, fix this' on a finding and the fix lands right on your PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[codecov]

Codecov Report

❌ Patch coverage is 91.83673% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/utils/version-checker.ts	91.66%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 30b07fc49c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[WitMiao]

审查跟进已完成（HEAD 08163ef）：\n\n- 已修复 Windows where 多路径输出中的 CRLF 尾随字符，并增加回归测试。\n- 已将本次新增的路径处理统一改为仓库约定的 pathe，同时明确 CCR 专用辅助函数命名。\n- 已评估 pnpm/Volta 普通 shim 建议；因其超出 #377 明确的 fnm/nvm/npm 全局安装范围，且需要包管理器特定解析规则，本 PR 不扩展该兼容范围。\n- 本地验证：lint、typecheck、build、完整 coverage 均通过；145 个测试文件、2552 个测试通过。\n- GitHub CI：lint、Ubuntu、macOS、Windows、Codecov patch 全部通过。\n- 所有审查线程均已逐条回复并解决。