Add automatic Prisma CLI update checks

[rtbenfield]

Adds advisory update checks to the CLI so interactive users can learn when a newer @prisma/cli release is available without changing command results or automation behavior.

Changes

• Update check shell flow: Adds packages/cli/src/shell/update-check.ts and wires it into packages/cli/src/cli.ts so cached stale-version notices render before eligible human command output. Notices are stderr-only and skipped for CI, --json, --quiet, non-TTY stderr, --version, tests by default, and NO_UPDATE_NOTIFIER.

• Background discovery: Adds a detached worker path in packages/cli/src/bin.ts that checks the npm latest dist-tag for @prisma/cli at most once every 24 hours. Discovery uses a 3s fetch timeout, persists only package/version/check metadata in a user-level cache, and silently ignores network or registry failures.

• Update instructions: Adds best-effort install guidance for local npm, global npm, pnpm, and Bun installs. Ephemeral or ambiguous invocations such as npx, pnpx, bunx, and unknown launch paths fall back to https://prisma.io/docs instead of guessing.

• Product docs and planning artifacts: Documents update-notification stream behavior in docs/product/output-conventions.md and global command behavior in docs/product/command-spec.md. Includes the resolved spec and phased execution plan under docs/specs.

• Coverage: Adds packages/cli/tests/update-check.test.ts for cached notices, suppression rules, stdout/JSON stability, interval behavior, stubbed registry discovery, failed discovery, and package-manager instruction selection.

Why

The CLI beta changes quickly, so users need a low-friction way to discover newer releases. The implementation keeps this advisory and automation-safe: command stdout remains machine-readable, command exit codes are unchanged, and remote discovery never blocks the original command. Cached notifications are separated from background npm lookup so short commands stay fast and offline or restricted environments fail silently.

[coderabbitai]

Summary by CodeRabbit

• New Features

  • Automatic update notifications: The CLI now periodically checks for newer versions and displays non-blocking notifications via stderr when updates are available. Notifications only appear in appropriate contexts—skipped in CI, with --json/--quiet, on non-TTY stderr, or when NO_UPDATE_NOTIFIER is set.

• Documentation

  • Updated CLI specification and output conventions to document automatic update notification behavior and conditions.

Walkthrough

This PR adds automatic CLI update notifications as an advisory feature. The CLI now checks for newer versions from npm, caches the result locally, and displays a notification to stderr when a stale version is detected—gated by TTY, CI, test mode, and explicit flags (--json, --quiet, NO_UPDATE_NOTIFIER). Remote discovery runs in a background worker to avoid blocking the user's command.

Changes

Automatic Update Check Feature

Layer / File(s)	Summary
Documentation and Specification docs/product/command-spec.md, docs/product/output-conventions.md	CLI specification and output conventions document automatic update check conditions (CI, --json, --quiet, non-TTY, NO_UPDATE_NOTIFIER), stderr-only output, and two recommended message formats (package-manager command vs. docs link).
Update State Types and Cache Persistence packages/cli/src/shell/update-check.ts	UpdateCheckState interface and UpdateCheckStore class persist cached version metadata in update-check.json with atomic write (temp file + rename) and graceful read error handling.
Notification Entry Point and Gating packages/cli/src/shell/update-check.ts	maybeWriteCachedUpdateNotification loads cached state and conditionally renders to stderr; canRunUpdateCheck gates by TTY, CI, test mode, flags, and env; shouldNotify rate-limits by interval.
Update Message Selection and Rendering packages/cli/src/shell/update-check.ts	selectUpdateInstruction analyzes entrypoint context and npm environment to choose package-manager-specific install commands or docs fallback; rendering helpers format notification for stderr.
Remote Discovery and Background Worker packages/cli/src/shell/update-check.ts	runUpdateDiscovery fetches latest npm version and updates cache; scheduleRemoteDiscovery spawns detached worker with env config; runUpdateDiscoveryWorker reads env and invokes discovery; fetchLatestVersion queries registry with timeout.
Supporting Utilities packages/cli/src/shell/update-check.ts	Semver parsing and comparison logic (including prerelease handling) and interval predicates for rate-limiting decisions.
CLI Entrypoint Integration packages/cli/src/bin.ts, packages/cli/src/cli.ts	bin.ts conditionally routes to runUpdateDiscoveryWorker or runCli; cli.ts awaits maybeWriteCachedUpdateNotification before command handling.
Comprehensive Test Suite packages/cli/tests/update-check.test.ts	Validates notification emission to stderr in TTY, suppression across flags/env/CI/non-TTY, state persistence, rate-limiting, remote discovery scheduling, registry fetch, message selection across npm/pnpm/bun contexts, and test helpers.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: adding automatic update checks to the Prisma CLI.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, detailing the implementation of advisory update checks with clear explanations of each component and design rationale.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/automatic-update-check

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch codex/automatic-update-check

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/cli/src/shell/update-check.ts`:
- Around line 97-103: The UpdateCheckStore.write call in the discovery update
replaces the entire cache entry and drops the existing notifiedAt timestamp; to
fix this, read the existing entry from UpdateCheckStore (or use
UpdateCheckStore.read/get) before calling write, merge the existing notifiedAt
into the new object (e.g., preserve existingEntry?.notifiedAt when creating the
payload for UpdateCheckStore.write), and then write the merged object; apply the
same merge logic for the other discovery write site around the code referenced
at lines 151-153 so notification throttling is preserved.
- Around line 36-45: The read() method currently rethrows on any non-ENOENT
error which causes parse/permission failures to abort update-check; change
read() (and the similar logic around lines 62-80) to treat unreadable or
unparsable cache files as a corrupt cache: catch JSON.parse and permission
errors, optionally attempt to unlink the cache file (fs.unlink) or at minimum
log the problem, then return null instead of throwing so the update-check flow
still proceeds to schedule discovery; update references to UpdateCheckState and
ensure callers that expect null continue to work.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: dba6da29-685a-4910-b920-a0b26c744d77

📥 Commits

Reviewing files that changed from the base of the PR and between c573c86 and 2fa7e41.

📒 Files selected for processing (6)

• docs/product/command-spec.md
• docs/product/output-conventions.md
• packages/cli/src/bin.ts
• packages/cli/src/cli.ts
• packages/cli/src/shell/update-check.ts
• packages/cli/tests/update-check.test.ts

[luanvdw]

🙏

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/cli/tests/update-check.test.ts`:
- Line 28: The test's expectation for the exact docs URL in update-check.test.ts
is brittle and points to a page that doesn't specifically contain step-by-step
CLI update instructions; update the assertion around expect(result.stderr) (the
expectation that currently contains "See
https://www.prisma.io/docs/orm/tools/prisma-cli for update instructions.") to
reference the correct, authoritative update instructions URL or loosen the check
(e.g., assert presence of a more general help domain or a shorter message like
"See prisma.io/docs for update instructions") so the test matches the intended
guidance; locate the expect(result.stderr).toContain(...) call and replace the
literal URL with the appropriate URL or a less strict substring/regex that
matches the intended user guidance.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: fc7da6c2-3f46-49f3-8f78-be2db334949c

📥 Commits

Reviewing files that changed from the base of the PR and between 2fa7e41 and 0f0cbe4.

📒 Files selected for processing (3)

• docs/product/output-conventions.md
• packages/cli/src/shell/update-check.ts
• packages/cli/tests/update-check.test.ts