feat(cli): add squad update-check --json for tooling/CI

[omercangumus]

What

Adds squad update-check [--json] [--refresh], a new CLI command that reports the CLI's cached update status.

Why

self-update.ts already maintains an OS-specific cache (update-check.json) for the background startup update check, but anything outside the CLI process that wants this information (editor extensions, coordinator instructions, CI scripts) currently has to replicate the OS-specific cache path logic, parse the JSON, check TTL freshness, and handle the no-cache-yet case. A dedicated command gives them a single, stable interface.

Closes #1170

How

• New packages/squad-cli/src/cli/commands/update-check.ts:
  • detectChannel(version) derives the release channel (stable/preview/insider) from the version's prerelease tag, reusing the ReleaseChannel type and parseVersion from upgrade.ts.
  • formatCacheAge(ms) formats a millisecond duration as an ISO 8601 duration string (e.g. PT2H15M), matching the schema in the issue.
  • runUpdateCheck(currentVersion, { refresh }) — without refresh, only reads the existing cache (no network call, per the acceptance criteria); with refresh, always re-fetches from npm and updates the cache.
  • runUpdateCheckCommand(args) — CLI entry point; handles --json/--refresh, the SQUAD_NO_UPDATE_CHECK=1 opt-out, and returns the process exit code.
• Exported getCachePath, fetchLatestVersion, and writeCache from self-update.ts (previously private) so the new command reuses the same cache I/O instead of duplicating it.
• Wired into cli-entry.ts routing, the top-level squad help listing, and a dedicated squad update-check --help block in command-help.ts.
• Added a ./commands/update-check subpath export to packages/squad-cli/package.json, following the existing convention for CLI command modules (e.g. ./commands/doctor).
• Documented in README.md's command table and added a new section to docs/src/content/docs/features/self-upgrade.md.

Judgment calls where the issue was ambiguous (flagging for review):

• No cache + no --refresh: reports latest: null, updateAvailable: false, exit code 0, with a human-readable hint to run --refresh. Chosen because the acceptance criteria explicitly says "No new network calls without --refresh", ruling out a fallback fetch.
• Transport failure during --refresh: returns { ..., error: "Failed to reach the npm registry" } (an additive field beyond the issue's schema) and exit code 2.

Testing

• Added test/cli/update-check.test.ts (21 tests): detectChannel branches, formatCacheAge formatting, runUpdateCheck cache-read/refresh/error paths (mocking self-update.js's network/cache functions — no real HTTP calls or shared-cache-path writes), and runUpdateCheckCommand exit codes / --json output / SQUAD_NO_UPDATE_CHECK opt-out.
• Updated test/cli/command-help.test.ts's hardcoded command list to include update-check (was failing before this fix).
• npx vitest run test/cli/update-check.test.ts test/cli/command-help.test.ts — 35 passed.
• npm run build — passes.
• npm run lint (tsc --noEmit) — passes.
• npm run lint:eslint — 0 errors (pre-existing warnings only, unrelated to this change).
• npm run lint:docs (markdownlint + cspell) — passes, since README.md and a docs page changed.
• npm test (full suite) and npx vitest run test/cli/ — no regressions from this change. Verified test/cli/rc.test.ts, test/cli/start.test.ts, test/cli/watch.test.ts time out identically on a clean upstream/dev checkout before my changes (pre-existing local Windows-environment flakiness, not something this PR introduces).

---

⚠️ Quick Check

• Changeset added: .changeset/feat-1170-update-check-json.md (minor bump, @bradygaster/squad-cli), since this adds a new CLI command (packages/squad-cli/src/)

PR Readiness Checklist

Branch & Commit

• Branch created from dev
• Branch is up to date with dev
• Verified diff contains only intended changes (git diff --cached --stat)
• PR is not in draft mode — will mark ready once CI is green
• Commit history is clean (single commit)

Build & Test

• npm run build passes
• npm test passes (see testing notes above for pre-existing unrelated local failures)
• npm run lint passes (type check clean)
• npm run lint:eslint passes (0 errors)

Changeset

• Changeset added (minor, @bradygaster/squad-cli)

Docs

• README.md command table updated
• Docs feature page updated (docs/src/content/docs/features/self-upgrade.md) — new capability documented under the existing self-upgrade feature, not a new page

Exports

• package.json subpath export added (./commands/update-check), matching the convention for other CLI command modules

---

Breaking Changes

None.

Waivers

None.

[github-actions]

🏗️ Architectural Review

⚠️ Architectural review: 1 warning(s).

Severity	Category	Finding	Files
🟡 warning	bootstrap-area	1 file(s) in the bootstrap area (packages/squad-cli/src/cli/core/) were modified. These files must maintain zero external dependencies. Review carefully.	packages/squad-cli/src/cli/core/command-help.ts

---

Automated architectural review — informational only.

[github-actions]

🟡 Impact Analysis — PR #1440

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	10
Files added	3
Files modified	7
Files deleted	0
Modules touched	4
Critical files	1

🎯 Risk Factors

• 10 files changed (6-20 → MEDIUM)
• 4 modules touched (2-4 → MEDIUM)
• Critical files touched: packages/squad-cli/package.json

📦 Modules Affected

docs (1 file)

• docs/src/content/docs/features/self-upgrade.md

root (2 files)

• .changeset/feat-1170-update-check-json.md
• README.md

squad-cli (5 files)

• packages/squad-cli/package.json
• packages/squad-cli/src/cli-entry.ts
• packages/squad-cli/src/cli/commands/update-check.ts
• packages/squad-cli/src/cli/core/command-help.ts
• packages/squad-cli/src/cli/self-update.ts

tests (2 files)

• test/cli/command-help.test.ts
• test/cli/update-check.test.ts

⚠️ Critical Files

• packages/squad-cli/package.json

---

This report is generated automatically for every PR. See #733 for details.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 98769ef

PR Scope: 📦🔧 Mixed (product + infrastructure)

⚠️ 1 item(s) to address before review

Status	Check	Details
✅	Single commit	1 commit — clean history
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	Changeset file found
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	No Copilot review threads
✅	CI passing	All checks passing

Files Changed (10 files, +477 −4)

File	+/−
.changeset/feat-1170-update-check-json.md	+12 −0
README.md	+1 −0
docs/src/content/docs/features/self-upgrade.md	+39 −0
packages/squad-cli/package.json	+4 −0
packages/squad-cli/src/cli-entry.ts	+8 −0
packages/squad-cli/src/cli/commands/update-check.ts	+166 −0
packages/squad-cli/src/cli/core/command-help.ts	+12 −0
packages/squad-cli/src/cli/self-update.ts	+5 −4
test/cli/command-help.test.ts	+1 −0
test/cli/update-check.test.ts	+229 −0

Total: +477 −4

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[tamirdresher]

Seems like the change is in hidden chars or something. Please fix. There are a bunch of other files with same whitespace changes

[omercangumus]

yeah, windows autocrlf snuck in there and flipped a bunch of untouched lines in cli-entry.ts to CRLF. reset the file to upstream and reapplied just the real hunks, diff is down to the actual 10 files now (477 insertions, 4 deletions), no more phantom removes/adds.