release: cli v4.0.0

Author: barrymichaeldoyle

.changeset/v4-breaking-changes.md

@@ -0,0 +1,46 @@
+---
+'patch-pulse': major
+---
+
+## Breaking Changes
+
+### Non-interactive by default
+
+The CLI now exits immediately after the summary. The interactive update prompt no longer appears unless explicitly requested.
+
+- Use `--interactive` (or `-i`) to enter interactive mode
+- `--no-interactive` suppresses the prompt explicitly (now the default behavior)
+- `"interactive": true` in `patchpulse.config.json` to opt in project-wide
+
+### Flag renames
+
+| Old flag             | New flag               |
+| -------------------- | ---------------------- |
+| `--update-prompt`    | `--interactive` / `-i` |
+| `--no-update-prompt` | `--no-interactive`     |
+| `--verbose-projects` | `--expand`             |
+| `--only-outdated`    | `--hide-clean`         |
+
+`--info` and its `-i` alias have been removed. Use `--help` / `-h` instead. `-i` is now the short form of `--interactive`.
+
+### Config file key rename
+
+`"noUpdatePrompt"` has been renamed to `"interactive"` in `patchpulse.config.json`. The value is also inverted — set `"interactive": true` to opt in to the update prompt.
+
+## New
+
+- `--fail` — exits with code `1` if any outdated packages are found, making it easy to use patch-pulse as a CI gate (pairs well with `--json`)
+- `llms.txt` — added LLM-consumable documentation to the CLI package (included in the published files) and a brief overview at the repo root
+
+## Improvements
+
+- Added a blank line between the package manager download output and the start of the report
+- `Location:` now shows the full `package.json` path (e.g. `apps/backend/package.json`) for IDE ctrl-click navigation. Single-project runs now also show the project name and location header
+- Projects with outdated dependencies now also show a `✓  Up to date: N` count alongside the attention summary
+- Interactive prompt menu simplified — removed the `h` (help) and `v` (version) options that interrupted the update flow
+
+## Fixes
+
+- Progress spinners now stop cleanly before dependency results and the final summary print, preventing stray terminal repainting after the CLI has finished
+- Pressing `Ctrl+C` in interactive mode now exits with code `130` instead of falling through to a normal success exit
+- Unsupported `packageManager` values in config files are now ignored during validation instead of causing failures later in the interactive update flow

.github/workflows/ci.yml

@@ -49,3 +49,8 @@ jobs:
 
       - name: Build (VS Code extension)
         run: pnpm build:vscode-extension
+
+      - name: Build (docs)
+        run: pnpm build:docs
+        env:
+          DOCS_BASE_PATH: /patch-pulse

.github/workflows/deploy-docs.yml

@@ -0,0 +1,47 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Install, build, and upload docs
+        uses: withastro/action@v6
+        with:
+          path: .
+          node-version: 22
+          package-manager: pnpm@10.30.3
+          build-cmd: pnpm build:docs
+          out-dir: packages/docs/dist
+        env:
+          DOCS_BASE_PATH: /patch-pulse
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

.vscode/settings.json

@@ -40,6 +40,7 @@
   },
   "cSpell.words": [
     "esbuild",
+    "llms",
     "npmhelp",
     "npmlist",
     "npmtrack",

README.md

@@ -7,7 +7,7 @@ PatchPulse helps you stay on top of npm dependency updates across your projects.
 | Tool                                             | Status                          | Description                                              |
 | ------------------------------------------------ | ------------------------------- | -------------------------------------------------------- |
 | [Slack bot](#slack-bot)                          | Live                            | Get notified in Slack when your packages release updates |
-| [CLI](./packages/cli)                            | v2.x on npm · v3 in development | Check for outdated dependencies from the terminal        |
+| [CLI](./packages/cli)                            | v3.x on npm · v4 in development | Check for outdated dependencies from the terminal        |
 | [VS Code extension](./packages/vscode-extension) | Early development               | In-editor dependency info (not yet released)             |
 
 ---
@@ -60,6 +60,7 @@ PatchPulse is a `pnpm` monorepo.
 ### Packages
 
 - `packages/cli` — npm CLI for checking outdated dependencies
+- `packages/docs` — Astro/Starlight docs site
 - `packages/notifier-bot` — Convex-powered Slack notification backend
 - `packages/shared` — shared runtime helpers and types
 - `packages/vscode-extension` — VS Code extension for in-editor dependency info
@@ -88,6 +89,7 @@ pnpm install          # install all dependencies
 pnpm ci:check         # lint, format, knip, typecheck, test, build — mirrors CI
 
 pnpm dev:notifier     # run Slack bot locally (requires Convex setup)
+pnpm dev:docs         # run docs locally
 pnpm dev:cli          # run CLI in dev mode
 pnpm pp               # dogfood the local CLI from the repo root
 pnpm -s pp -- --json  # same, but without pnpm's script banner for pipe-safe JSON

knip.json

@@ -1,5 +1,6 @@
 {
   "$schema": "https://unpkg.com/knip@6/schema.json",
+  "ignoreFiles": ["packages/docs/.astro/**"],
   "workspaces": {
     "packages/shared": {
       "project": ["src/**/*.ts"]

llms.txt

@@ -0,0 +1,14 @@
+# Patch Pulse
+
+Patch Pulse checks for outdated npm dependencies across single projects and monorepos. It hits the npm registry, categorises updates by severity (patch / minor / major), and optionally applies updates in-place.
+
+## Packages in this repo
+
+- `patch-pulse` (`packages/cli`) — the CLI tool, published to npm. This is the main product.
+- `@patch-pulse/shared` (`packages/shared`) — shared logic (npm registry fetching, version comparison). Internal.
+- `@patch-pulse/notifier-bot` (`packages/notifier-bot`) — Slack bot that notifies workspaces of new releases. Internal.
+- `patch-pulse-vscode-extension` (`packages/vscode-extension`) — VS Code extension. In progress.
+
+## Detailed reference
+
+See `packages/cli/llms.txt` for the full CLI flag reference, config schema, output format, and common recipes.

package.json

@@ -24,15 +24,17 @@
   "scripts": {
     "build:cli": "pnpm --filter patch-pulse build",
     "build:vscode-extension": "pnpm --filter patch-pulse-vscode-extension compile",
+    "build:docs": "pnpm --filter @patch-pulse/docs build",
     "build": "pnpm run build:cli && pnpm run build:vscode-extension",
+    "dev:docs": "pnpm --filter @patch-pulse/docs dev",
     "deploy:notifier": "pnpm --filter @patch-pulse/notifier-bot deploy",
     "dev:notifier": "pnpm --filter @patch-pulse/notifier-bot dev",
     "dev:cli": "pnpm --filter patch-pulse dev",
     "pp": "node --import tsx packages/cli/src/index.ts",
     "dev:vscode-extension": "pnpm --filter patch-pulse-vscode-extension watch",
-    "format": "pnpm exec oxfmt --write .",
-    "format:check": "pnpm exec oxfmt --check .",
-    "ci:check": "pnpm lint && pnpm format:check && pnpm knip && pnpm typecheck && pnpm test:shared && pnpm test:cli && pnpm test:notifier && pnpm build:cli && pnpm build:vscode-extension",
+    "format": "pnpm exec oxfmt --write . '!packages/docs/.astro/**'",
+    "format:check": "pnpm exec oxfmt --check . '!packages/docs/.astro/**'",
+    "ci:check": "pnpm lint && pnpm format:check && pnpm knip && pnpm typecheck && pnpm test:shared && pnpm test:cli && pnpm test:notifier && pnpm build:cli && pnpm build:vscode-extension && pnpm build:docs",
     "knip": "pnpm exec knip",
     "lint": "pnpm exec oxlint .",
     "lint:fix": "pnpm exec oxlint --fix .",

packages/cli/README.md

@@ -28,8 +28,9 @@ That's it! Patch Pulse scans the current project for `package.json` files and sh
 
 ## Configuration
 
-Patch Pulse supports configuration files for persistent settings. Create one of these files in your project root:
+Patch Pulse supports configuration files for persistent settings. Prefer `patchpulse.json` in your project root. These filenames are supported:
 
+- `patchpulse.json`
 - `patchpulse.config.json`
 - `.patchpulserc.json`
 - `.patchpulserc`
@@ -41,7 +42,7 @@ Patch Pulse supports configuration files for persistent settings. Create one of
   "skip": ["lodash", "@types/*", "test-*"],
   "ignorePaths": ["packages/cli/e2e"],
   "packageManager": "npm",
-  "noUpdatePrompt": false
+  "interactive": true
 }
 ```
 
@@ -68,29 +69,29 @@ The `packageManager` option allows you to override the package manager detection
 - `yarn`
 - `bun`
 
-### No Update Prompt
+### Interactive Mode
 
-The `noUpdatePrompt` option allows you to skip the update prompt.
+The `interactive` option opts in to the interactive update prompt after the summary.
 
 ### CLI vs File Configuration
 
 CLI arguments override file configuration:
 
 ```bash
-# This will override any settings in patchpulse.config.json
-npx patch-pulse --skip "react,react-dom" --package-manager pnpm --no-update-prompt
+# This will override any settings in patchpulse.json
+npx patch-pulse --skip "react,react-dom" --package-manager pnpm --no-interactive
 ```
 
-For monorepos, use `--verbose-projects` to print full dependency sections for clean workspaces too.
+For monorepos, use `--expand` to print full dependency sections for clean workspaces too.
 
 ```bash
-npx patch-pulse --verbose-projects
+npx patch-pulse --expand
 ```
 
-Use `--only-outdated` to hide clean workspaces entirely.
+Use `--hide-clean` to hide clean workspaces entirely.
 
 ```bash
-npx patch-pulse --only-outdated
+npx patch-pulse --hide-clean
 ```
 
 Focus one project by workspace path or package name:
@@ -105,7 +106,15 @@ Use `--json` for scripts, CI, or editor integrations:
 npx patch-pulse --json
 ```
 
-When dogfooding the local workspace CLI through the root script, use `pnpm -s`
+Use `--fail` to exit with code `1` if any outdated packages are found — useful as a CI gate:
+
+```bash
+npx patch-pulse --fail
+# or combine with --json for machine-readable output + non-zero exit
+npx patch-pulse --json --fail
+```
+
+When running the local workspace CLI through the root script, use `pnpm -s`
 to suppress pnpm's script banner before JSON output:
 
 ```bash

packages/cli/e2e/basic/__snapshots__/basic.test.ts.snap

@@ -1,7 +1,10 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`basic project > prints a full dependency summary 1`] = `
-"Dependencies:
+"fixture-basic
+Location: package.json
+────────────────────────────────────────────────────────────
+Dependencies:
 ─────────────
 MINOR chalk 5.0.0 → 5.6.2
 UP TO DATE lodash 4.17.21