Capabilities: what is guaranteed vs best-effort
Upshift combines deterministic tooling (your package manager, tests, lockfiles) with optional AI (explain --ai, fix). This page sets expectations so you know what CI and docs promise versus what depends on models and prompts.
Guardrails, not autopilot
Upshift accelerates upgrades with AI. It does not silently rewrite your codebase. Your tests stay the gate; you stay in the loop.
- Test-gated upgrades:
upshift upgraderuns your test script; failures trigger automatic rollback. Honest fine print: no test script means no gate. The CLI warns you and upgrades without a net. - Review before apply:
upshift fix --dry-runshows diffs; major bumps can require prompt or webhook approval. - Optional outcomes:
UPSHIFT_RECORD_OUTCOMES=1logs upgrade results locally for your own analysis.
Guaranteed in automated tests (CLI)
These paths are exercised in-repo on fixtures and (where noted) pinned public repos:
| Area | Coverage |
|---|---|
| npm | scan, scan --json, scan --report, suggest, plan, upgrade --dry-run on tests/fixtures/minimal and workspace / no-test fixtures |
| pnpm / yarn | Same commands when pnpm / yarn are on PATH (see tests/fixtures/minimal-pnpm, minimal-yarn) |
| npm workspaces | scan / suggest / plan on tests/fixtures/minimal-workspace |
| Python | scan, scan --licenses, upgrade --dry-run on tests/fixtures/minimal-python |
| JSON shape (Node) | Top-level keys for scan --json and scan --report per tests/golden/node-scan-json-keys.json |
| Pure semver helpers | Unit tests (npm run test:unit) for getUpgradeType in src/lib/version-bump-kind.ts |
| Corpus (optional job) | Read-only upshift scan, plus selected explain <pkg> --risk (no --ai) on pinned tags in tests/corpus/repos.json (npm run test:corpus, weekly workflow) |
Platform, site parity, and Playwright checks run via npm test as documented in CONTRIBUTING.md.
Best-effort (AI and models)
| Capability | Notes |
|---|---|
explain --ai | Quality varies by model, prompt, and package; not snapshotted in default CI. |
fix / codemods | Node-first; review diffs and run tests. Use --dry-run before applying. |
| Risk scores & changelog summaries | Heuristic + network; treat as guidance, not proof. |
Optional AI eval rubrics (npm run test:ai-eval, key-gated) give a repeatable smoke check for a small prompt set; see ai-eval.md in the repo.
Deepest product investment (“hero stack”)
Strongest workflows and templates target npm / yarn / pnpm on Node, especially React / Next.js (explain, fix, migrations). Other ecosystems are supported for scan (and many for upgrade) with varying depth; see ROADMAP.md and the README hero-stack callouts.
Beta feedback
If something fails in the wild, use the Beta feedback issue template on GitHub: include CLI version, OS, package manager, and a redacted upshift scan --json when possible so I can reproduce the shape without leaking secrets.