feat(codex): codex setup auto-upgrade — version check, network detection, offline guidance

[chenliuyun]

Current situation

switchbot codex setup installs @switchbot/openapi-cli globally but never checks whether an existing install is outdated. Users running a stale global install would silently skip the upgrade step with just "already installed", leaving them on an old version.

Additionally, Codex workspaces are offline by default — no network check existed, so setup would hit multiple sequential timeouts and emit confusing raw npm errors with no guidance on how to fix it.

Proposed solution

Auto-upgrade via npm registry check

• fetchLatestPublishedVersion queries npm view @switchbot/openapi-cli version (8 s timeout) to get the true latest from the registry
• Falls back to VERSION (the running binary) when offline — correct when invoked via npx since VERSION == latest
• compareVersions does a numeric semver comparison (pre-release segments stripped); upgrades automatically if installed version is behind
• After a successful install, re-verifies the actual installed version with npm list -g to report an accurate "upgraded X → Y" message

Network detection step (check-network)

• New 2nd step (skippable) probes the npm registry with npm ping
• On failure: emits a warn outcome with the exact ~/.codex/config.toml fix and skips install-switchbot-cli automatically (avoids ~13 s of serial timeouts)
• JSON output now includes hasWarnings: true when any step warns

Plugin docs for Codex sandbox

• New packages/codex-plugin/skills/switchbot/references/codex-network.md — explains the three network operations required and gives the exact config snippet
• SKILL.md gains a ## Network requirements section pointing to that reference

Code review fixes (from post-implementation review)

• compareVersions: strips pre-release/build metadata before numeric comparison (3.8.0-rc.1 no longer causes NaN)
• fetchLatestPublishedVersion regex: removed $ anchor so pre-release versions from the registry are accepted
• runRepair icon renderer: added warn → chalk.yellow('⚠') arm (was falling through to red ✗)
• Removed dead as … | null | undefined cast on registerCodexPluginAuto() call sites

Release Notes

codex setup now:

1. Checks the npm registry for the latest CLI version and upgrades automatically if your global install is outdated
2. Detects offline/sandboxed environments early and prints the exact ~/.codex/config.toml fix before wasting time on network calls
3. Reports the actually installed version in the success message (not a stale reference version)

No breaking changes. The step count increases from 5 to 6 (check-network inserted as step 2, skippable).

Testing

• 36 tests in tests/commands/codex.test.ts (was 30), all passing
• New tests cover: already-at-latest, outdated→auto-upgrade, upgrade failure, npm-view offline fallback, check-network ok, check-network warn + config.toml hint, auto-skip install when offline
• 6 unit tests for compareVersions covering pre-release edge cases
• Pre-push smoke: build + version test + pack-install smoke all pass

Reviewer nudge

Start with src/commands/codex.ts:

1. fetchLatestPublishedVersion + compareVersions (~line 20–50) — version check logic
2. setupStepCheckNetwork (~line 380) — new network probe step
3. setupStepInstallGlobalPackage (~line 440) — rewritten install/upgrade logic
4. runSetup (~line 515) — networkOffline flag + auto-skip wiring

Then packages/codex-plugin/skills/switchbot/references/codex-network.md for the user-facing guidance.